EntityPoolManager Class Template

High-level manager for Entity pooling operations. More...

Declaration

template <typename TEntity> class helios::engine::runtime::pooling::EntityPoolManager<TEntity> { ... }

Public Member Typedefs Index

template <typename TEntity>
using	EngineRoleTag = helios::engine::runtime::world::tags::ManagerRole

Private Member Typedefs Index

template <typename TEntity>
using	Handle_type = typename TEntity::Handle_type
template <typename TEntity>
using	Entity_type = TEntity

Public Constructors Index

template <typename TEntity>
EntityPoolManager (helios::engine::runtime::world::EngineWorld &engineWorld)

Public Member Functions Index

template <typename TEntity>
EntityPoolManager &	addPoolConfig (std::unique_ptr< EntityPoolConfig > entityPoolConfig)
	Registers a pool configuration for later initialization. More...
template <typename TEntity>
helios::engine::runtime::pooling::EntityPoolSnapshot	poolSnapshot (const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId) const
	Returns a snapshot of the pool's current state. More...
template <typename TEntity>
auto	release (const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId, const Handle_type &entityHandle) -> std::optional< TEntity >
	Releases a Entity back to its pool. More...
template <typename TEntity>
auto	acquire (const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId) -> std::optional< TEntity >
	Acquires an inactive Entity from the pool. More...
template <typename TEntity>
void	init (CommandHandlerRegistry &commandHandlerRegistry)
	Initializes all registered pools. More...
template <typename TEntity>
void	flush (helios::engine::runtime::world::UpdateContext &update_context) noexcept
	Manager flush callback (currently unused). More...
template <typename TEntity>
auto	pool (const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId) const -> EntityPool< Handle_type > *
	Retrieves a pool by its ID. More...
template <typename TEntity>
void	reset ()
	Resets all pools by releasing all active Entities. More...
template <typename TEntity>
void	reset (const types::EntityPoolId poolId)
	Reset the pool with the specified poolId. More...

Private Member Functions Index

template <typename TEntity>
void	fillPool (const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId, TEntity entityPrefab)
	Populates a pool with cloned prefab instances and locks it. More...

Private Member Attributes Index

template <typename TEntity>
helios::engine::runtime::pooling::EntityPoolRegistry< Handle_type >	pools_ {}
	Registry of EntityPools for entity recycling. More...
template <typename TEntity>
helios::engine::runtime::world::EngineWorld *	engineWorld_ = nullptr
	Non-owning pointer to the associated GameWorld. More...
template <typename TEntity>
std::unordered_map< helios::engine::runtime::pooling::types::EntityPoolId, std::unique_ptr< EntityPoolConfig > >	poolConfigs_
	Pending pool configurations awaiting initialization. More...

Description

High-level manager for Entity pooling operations.

EntityPoolManager provides a unified interface for managing multiple EntityPools. It handles pool configuration, initialization, and the acquire/release lifecycle of pooled Entities.

The manager integrates with the GameWorld to clone prefabs during pool initialization and to look up Entities by their EntityHandle during acquire/release operations.

Definition at line 111 of file EntityPoolManager.ixx.

Public Member Typedefs

EngineRoleTag

template <typename TEntity>

using helios::engine::runtime::pooling::EntityPoolManager< TEntity >::EngineRoleTag = helios::engine::runtime::world::tags::ManagerRole

Definition at line 184 of file EntityPoolManager.ixx.

184 using EngineRoleTag = helios::engine::runtime::world::tags::ManagerRole;

Private Member Typedefs

Entity_type

template <typename TEntity>

using helios::engine::runtime::pooling::EntityPoolManager< TEntity >::Entity_type = TEntity

Definition at line 114 of file EntityPoolManager.ixx.

114 using Entity_type = TEntity;

Handle_type

template <typename TEntity>

using helios::engine::runtime::pooling::EntityPoolManager< TEntity >::Handle_type = typename TEntity::Handle_type

Definition at line 113 of file EntityPoolManager.ixx.

113 using Handle_type = typename TEntity::Handle_type;

Public Constructors

EntityPoolManager()

template <typename TEntity>

helios::engine::runtime::pooling::EntityPoolManager< TEntity >::EntityPoolManager (helios::engine::runtime::world::EngineWorld & engineWorld)

inline explicit

Definition at line 187 of file EntityPoolManager.ixx.

187 explicit EntityPoolManager(helios::engine::runtime::world::EngineWorld& engineWorld) : engineWorld_(&engineWorld) {}

Public Member Functions

acquire()

template <typename TEntity>

std::optional< TEntity > helios::engine::runtime::pooling::EntityPoolManager< TEntity >::acquire (const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId)

inline

Acquires an inactive Entity from the pool.

Retrieves the next available inactive entity and calls onAcquire() to trigger component initialization hooks. The caller is responsible for activating the entity via setActive(true).

If an acquired entity is no longer valid in the GameWorld (stale handle), it is removed from the pool and the next available entity is tried.

Parameters

entityPoolId

The pool to acquire from.

Returns

Optional containing the acquired Entity if available, std::nullopt if the pool is exhausted.

Definition at line 278 of file EntityPoolManager.ixx.

278 [[nodiscard]] std::optional<TEntity> acquire(

279 const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId

280 ) {

281 Handle_type entityHandle{};

282

283 auto* entityPool = pool(entityPoolId);

284

285 while (entityPool->acquire(entityHandle)) {

286

287 auto worldGo = engineWorld_->find(entityHandle);

288

289 if (worldGo) {

290 worldGo->onAcquire();

291 return worldGo;

292 }

293

294 // we assume the pool is owned by this gameWorld,

295 // so removing this entityHandle does not impact another gameWorld that is

296 // using this pool

297 entityPool->releaseAndRemove(entityHandle);

298 }

299

300 return std::nullopt;

301

302 }

References helios::engine::runtime::world::EngineWorld::find, helios::engine::runtime::pooling::EntityPoolManager< TEntity >::pool and helios::engine::runtime::pooling::registerComponents.

addPoolConfig()

template <typename TEntity>

EntityPoolManager & helios::engine::runtime::pooling::EntityPoolManager< TEntity >::addPoolConfig (std::unique_ptr< EntityPoolConfig > entityPoolConfig)

inline

Registers a pool configuration for later initialization.

The configuration specifies the pool ID, capacity, and prefab to use for cloning. Configurations are processed during init().

Parameters

entityPoolConfig

The pool configuration to register.

Returns

Reference to this manager for method chaining.

Exceptions

std::runtime_error

If a pool with the same ID is already registered.

Definition at line 201 of file EntityPoolManager.ixx.

201 EntityPoolManager& addPoolConfig(std::unique_ptr<EntityPoolConfig> entityPoolConfig) {

202

203 if (poolConfigs_.contains(entityPoolConfig->entityPoolId)) {

204 throw std::runtime_error("Pool already registered with this manager");

205 }

206

207 poolConfigs_[entityPoolConfig->entityPoolId] = std::move(entityPoolConfig);

208

209 return *this;

210 }

Reference helios::engine::runtime::pooling::registerComponents.

flush()

template <typename TEntity>

void helios::engine::runtime::pooling::EntityPoolManager< TEntity >::flush (helios::engine::runtime::world::UpdateContext & update_context)

inline noexcept

Manager flush callback (currently unused).

Reserved for future use. May be used to process deferred release requests or pool maintenance operations.

Parameters

gameWorld	The associated GameWorld.
update_context	The current frame's update context.

Definition at line 344 of file EntityPoolManager.ixx.

344 void flush(

345 helios::engine::runtime::world::UpdateContext& update_context

346 ) noexcept {

347

348 }

init()

template <typename TEntity>

void helios::engine::runtime::pooling::EntityPoolManager< TEntity >::init (CommandHandlerRegistry & commandHandlerRegistry)

inline

Initializes all registered pools.

Creates EntityPool instances from the pending configurations and populates them by cloning the specified prefabs into the GameWorld.

Parameters

gameWorld

The GameWorld to associate with this manager.

Definition at line 312 of file EntityPoolManager.ixx.

312 void init(CommandHandlerRegistry& commandHandlerRegistry) {

313

314

315 for (const auto& [entityPoolId, poolConfig] : poolConfigs_) {

316

317 auto pool = std::make_unique<helios::engine::runtime::pooling::EntityPool<Handle_type>>(

318 poolConfig->amount);

319

320 pools_.addPool(entityPoolId, std::move(pool));

321

322 for (auto [entity, pic] : engineWorld_->view<

323 Handle_type,

324 helios::engine::runtime::pooling::components::PrefabIdComponent<Handle_type>>().whereEnabled()) {

325 if (pic->prefabId() == poolConfig->prefabId) {

326 fillPool(entityPoolId, entity);

327 break;

328 }

329 }

330

331 }

332

333 };

References helios::engine::runtime::pooling::EntityPoolRegistry< THandle >::addPool, helios::engine::runtime::pooling::EntityPoolManager< TEntity >::pool, helios::engine::runtime::pooling::registerComponents and helios::engine::runtime::world::EngineWorld::view.

pool()

template <typename TEntity>

EntityPool< Handle_type > * helios::engine::runtime::pooling::EntityPoolManager< TEntity >::pool (const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId)

inline

Retrieves a pool by its ID.

Parameters

entityPoolId

The pool ID to look up.

Returns

Pointer to the EntityPool.

Precondition

The pool must be registered with this manager.

Definition at line 359 of file EntityPoolManager.ixx.

359 [[nodiscard]] EntityPool<Handle_type>* pool(

360 const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId

361 ) const {

362 assert(pools_.has(entityPoolId) && "EntityPoolId not registered with this manager");

363 return pools_.pool(entityPoolId);

364 }

References helios::engine::runtime::pooling::EntityPoolRegistry< THandle >::has, helios::engine::runtime::pooling::EntityPoolRegistry< THandle >::pool and helios::engine::runtime::pooling::registerComponents.

Referenced by helios::engine::runtime::pooling::EntityPoolManager< TEntity >::acquire, helios::engine::runtime::pooling::EntityPoolManager< TEntity >::init, helios::engine::runtime::pooling::EntityPoolManager< TEntity >::poolSnapshot, helios::engine::runtime::pooling::EntityPoolManager< TEntity >::release and helios::engine::runtime::pooling::EntityPoolManager< TEntity >::reset.

poolSnapshot()

template <typename TEntity>

helios::engine::runtime::pooling::EntityPoolSnapshot helios::engine::runtime::pooling::EntityPoolManager< TEntity >::poolSnapshot (const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId)

inline

Returns a snapshot of the pool's current state.

Provides the active and inactive counts for monitoring and debugging purposes.

Parameters

entityPoolId

The pool to query.

Returns

A EntityPoolSnapshot containing active and inactive counts.

Definition at line 222 of file EntityPoolManager.ixx.

222 [[nodiscard]] helios::engine::runtime::pooling::EntityPoolSnapshot poolSnapshot(

223 const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId

224 ) const {

225 auto* entityPool = pool(entityPoolId);

226

227 return {

228 entityPool->activeCount(), entityPool->inactiveCount()

229 };

230 }

References helios::engine::runtime::pooling::EntityPoolManager< TEntity >::pool and helios::engine::runtime::pooling::registerComponents.

release()

template <typename TEntity>

std::optional< TEntity > helios::engine::runtime::pooling::EntityPoolManager< TEntity >::release (const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId, const Handle_type & entityHandle)

inline

Releases a Entity back to its pool.

Marks the entity as inactive in both the pool and the GameWorld. Calls onRelease() on the Entity to trigger component cleanup hooks, then deactivates it.

Parameters

entityPoolId	The pool that owns this entity.
entityHandle	The EntityHandle of the entity to release.

Returns

Optional containing the released Entity if found, std::nullopt if the entity was not found in the GameWorld.

Definition at line 245 of file EntityPoolManager.ixx.

245 std::optional<TEntity> release(

246 const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId,

247 const Handle_type& entityHandle

248 ) {

249 auto* entityPool = pool(entityPoolId);

250

251 auto worldGo = engineWorld_->find<Handle_type>(entityHandle);

252

253 if (worldGo) {

254 if (entityPool->release(entityHandle)) {

255 worldGo->onRelease();

256 worldGo->setActive(false);

257 }

258 }

259

260 return worldGo;

261 }

References helios::engine::runtime::world::EngineWorld::find, helios::engine::runtime::pooling::EntityPoolManager< TEntity >::pool and helios::engine::runtime::pooling::registerComponents.

Referenced by helios::engine::runtime::pooling::EntityPoolManager< TEntity >::reset.

reset()

template <typename TEntity>

void helios::engine::runtime::pooling::EntityPoolManager< TEntity >::reset ()

inline

Resets all pools by releasing all active Entities.

Iterates through all registered pools and releases every active entity back to its pool. This effectively returns all pooled objects to their inactive state without destroying them.

Useful for level transitions or game restarts where all pooled objects should be recycled.

See Also

reset(const types::EntityPoolId)

Definition at line 378 of file EntityPoolManager.ixx.

378 void reset() {

379 for (auto& [poolId, _] : pools_.pools()) {

380 reset(poolId);

381 }

382 }

References helios::engine::runtime::pooling::EntityPoolRegistry< THandle >::pools, helios::engine::runtime::pooling::registerComponents and helios::engine::runtime::pooling::EntityPoolManager< TEntity >::reset.

Referenced by helios::engine::runtime::pooling::EntityPoolManager< TEntity >::reset.

reset()

template <typename TEntity>

void helios::engine::runtime::pooling::EntityPoolManager< TEntity >::reset (const types::EntityPoolId poolId)

inline

Reset the pool with the specified poolId.

Releases every active entity back to its pool specified by poolId. This effectively returns all pooled objects to their inactive state without destroying them.

Parameters

poolId

The ID of the pool to reset.

Definition at line 393 of file EntityPoolManager.ixx.

393 void reset(const types::EntityPoolId poolId) {

394

395 const auto poolPtr = pool(poolId);

396

397 auto activeSpan = poolPtr->activeEntities();

398 auto toRelease = std::vector(activeSpan.begin(), activeSpan.end());

399 for (auto entityHandle : toRelease) {

400 release(poolId, entityHandle);

401 }

402 }

References helios::engine::runtime::pooling::EntityPoolManager< TEntity >::pool, helios::engine::runtime::pooling::registerComponents and helios::engine::runtime::pooling::EntityPoolManager< TEntity >::release.

Private Member Functions

fillPool()

template <typename TEntity>

void helios::engine::runtime::pooling::EntityPoolManager< TEntity >::fillPool (const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId, TEntity entityPrefab)

inline

Populates a pool with cloned prefab instances and locks it.

Clones the prefab Entity until the pool reaches its configured capacity. Each clone is:

1. Added to the GameWorld
2. Immediately deactivated (setActive(false))
3. Prepared for pooling (onRelease())
4. Registered as inactive in the pool

After all clones are created, the pool is locked via lock(). Locking finalizes the sparse array sizing based on the min/max EntityIds and enables O(1) acquire/release operations. Once locked, no new EntityHandles can be added to the pool.

Parameters

entityPoolId	The pool to fill.
entityPrefab	The prefab to clone.

Postcondition

The pool is locked and ready for acquire/release operations.

Definition at line 162 of file EntityPoolManager.ixx.

162 void fillPool(

163 const helios::engine::runtime::pooling::types::EntityPoolId entityPoolId,

164 TEntity entityPrefab

165 ) {

166 Handle_type entityHandle{};

167

168 auto* entityPool = pool(entityPoolId);

169

170 const size_t used = entityPool->activeCount() + entityPool->inactiveCount();

171 const size_t space = used < entityPool->size() ? entityPool->size() - used : 0;

172

173 for (size_t i = 0; i < space; i++) {

174 Entity_type go = engineWorld_->clone(entityPrefab.handle());

175 go.setActive(false);

176 go.onRelease();

177 entityPool->addInactive(go.handle());

178 }

179

180 entityPool->lock();

181 }

Private Member Attributes

engineWorld_

template <typename TEntity>

helios::engine::runtime::world::EngineWorld* helios::engine::runtime::pooling::EntityPoolManager< TEntity >::engineWorld_ = nullptr

Non-owning pointer to the associated GameWorld.

Set during init(). Used for cloning prefabs and looking up Entities by their EntityHandle.

Definition at line 130 of file EntityPoolManager.ixx.

130 helios::engine::runtime::world::EngineWorld* engineWorld_ = nullptr;

poolConfigs_

template <typename TEntity>

std::unordered_map< helios::engine::runtime::pooling::types::EntityPoolId, std::unique_ptr<EntityPoolConfig> > helios::engine::runtime::pooling::EntityPoolManager< TEntity >::poolConfigs_

Pending pool configurations awaiting initialization.

Configurations are consumed during init() to create and populate the actual pools.

Definition at line 140 of file EntityPoolManager.ixx.

140 std::unique_ptr<EntityPoolConfig>> poolConfigs_;

pools_

template <typename TEntity>

helios::engine::runtime::pooling::EntityPoolRegistry<Handle_type> helios::engine::runtime::pooling::EntityPoolManager< TEntity >::pools_ {}

Registry of EntityPools for entity recycling.

Pools enable efficient reuse of Entities without repeated allocation/deallocation. Each pool is identified by a EntityPoolId.

Definition at line 122 of file EntityPoolManager.ixx.

122 helios::engine::runtime::pooling::EntityPoolRegistry<Handle_type> pools_{};

---

The documentation for this class was generated from the following file:

• EntityPoolManager.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.