EntityPool Class Template

Object pool for efficient Entity lifecycle management. More...

Declaration

template <typename THandle> class helios::engine::runtime::pooling::EntityPool<THandle> { ... }

Public Constructors Index

template <typename THandle>
EntityPool (size_t poolSize)
	Constructs a EntityPool with the specified capacity. More...

Public Member Functions Index

template <typename THandle>
helios::engine::util::Guid	guid () const noexcept
	Returns the unique identifier of this pool. More...
template <typename THandle>
size_t	size () const noexcept
	Returns the maximum capacity of this pool. More...
template <typename THandle>
bool	acquire (THandle &entityHandle)
	Acquires an inactive Entity from the pool. More...
template <typename THandle>
bool	isLocked () const noexcept
	Checks if the pool is locked. More...
template <typename THandle>
void	lock () noexcept
	Locks the pool for acquire/release operations. More...
template <typename THandle>
bool	addInactive (const THandle entityHandle)
	Adds a EntityHandle to the inactive list without acquiring it. More...
template <typename THandle>
bool	release (const THandle entityHandle)
	Releases a Entity back to the pool by its EntityHandle. More...
template <typename THandle>
bool	releaseAndRemove (const THandle entityHandle)
	Releases and permanently removes a Entity from the pool. More...
template <typename THandle>
size_t	activeCount () const noexcept
	Returns the number of active game objects. More...
template <typename THandle>
size_t	inactiveCount () const noexcept
	Returns the number of inactive game objects. More...
template <typename THandle>
auto	inactiveEntities () -> std::span< THandle >
	Returns a span of all inactive EntityHandles. More...
template <typename THandle>
auto	activeEntities () -> std::span< THandle >
	Returns a span of all active EntityHandles. More...

Protected Member Attributes Index

template <typename THandle>
std::vector< size_t >	activeIndex_
	Maps active Entity EntityIds to their index in activeEntities_. More...
template <typename THandle>
std::vector< size_t >	versionIndex_
	Tracks version numbers for active EntityHandles. More...
template <typename THandle>
std::vector< THandle >	activeEntities_
	List of EntityHandles for currently active (in-use) Entities. More...
template <typename THandle>
std::vector< THandle >	inactiveEntities_
	List of EntityHandles for currently inactive (available) Entities. More...
template <typename THandle>
size_t	poolSize_ = 0
	The maximum number of objects this pool manages. More...
template <typename THandle>
helios::ecs::types::EntityId	minEntityId_ = std::numeric_limits<helios::ecs::types::EntityId>::max()
	Minimum EntityId in the pool (used for sparse array offset). More...
template <typename THandle>
helios::ecs::types::EntityId	maxEntityId_ = std::numeric_limits<helios::ecs::types::EntityId>::lowest()
	Maximum EntityId in the pool (used for sparse array sizing). More...
template <typename THandle>
size_t	delta_ = 0
	Offset for sparse array indexing (equals minEntityId_ after lock). More...
template <typename THandle>
const helios::engine::util::Guid	guid_
	Unique identifier for this pool instance. More...
template <typename THandle>
bool	locked_ = false
	True if the pool is locked and ready for acquire/release operations. More...

Description

Object pool for efficient Entity lifecycle management.

EntityPool manages a fixed-size collection of Entity identifiers, tracking which objects are currently active (in-use) and which are inactive (available). This pattern eliminates runtime allocation overhead for frequently spawned entities like projectiles, particles, or enemies.

The pool uses O(1) operations for both acquire and release:

• acquire: Pops from the inactive list and adds to active tracking
• release: Swap-and-pop removal from active list, push to inactive

Entities themselves are owned by GameWorld; this pool only tracks their EntityHandles.

Definition at line 46 of file EntityPool.ixx.

Public Constructors

EntityPool()

template <typename THandle>

helios::engine::runtime::pooling::EntityPool< THandle >::EntityPool (size_t poolSize)

inline explicit

Constructs a EntityPool with the specified capacity.

Pre-allocates internal storage for the given pool size. The pool starts empty; use addInactive() or a factory to populate it.

Parameters

poolSize

The maximum number of Entities this pool can manage.

Definition at line 116 of file EntityPool.ixx.

116 explicit EntityPool(

117 size_t poolSize

118 ) :

119 poolSize_(poolSize),

120 guid_(helios::engine::util::Guid::generate()) {

121 activeEntities_.reserve(poolSize);

122 inactiveEntities_.reserve(poolSize);

123 }

References helios::engine::runtime::pooling::EntityPool< THandle >::activeEntities_, helios::engine::runtime::pooling::EntityPool< THandle >::inactiveEntities_ and helios::engine::runtime::pooling::registerComponents.

Public Member Functions

acquire()

template <typename THandle>

bool helios::engine::runtime::pooling::EntityPool< THandle >::acquire (THandle & entityHandle)

inline

Acquires an inactive Entity from the pool.

Removes a EntityHandle from the inactive list and adds it to the active tracking structures. The caller is responsible for activating the actual Entity in the GameWorld.

Parameters

[out] entityHandle

Receives the EntityHandle of the acquired object on success.

Returns

True if an object was acquired, false if the pool is exhausted.

Definition at line 155 of file EntityPool.ixx.

155 [[nodiscard]] bool acquire(THandle& entityHandle) {

156

157 if (inactiveEntities_.empty()) {

158 return false;

159 }

160

161 entityHandle = inactiveEntities_.back();

162 inactiveEntities_.pop_back();

163

164

165 auto idx = entityHandle.entityId - delta_;

166

167 if (activeIndex_.size() <= idx) {

168 activeIndex_.resize(idx + 1, helios::ecs::types::EntityTombstone);

169 versionIndex_.resize(idx + 1, helios::ecs::types::EntityTombstone);

170 }

171

172 activeIndex_[idx] = activeEntities_.size();

173 versionIndex_[idx] = entityHandle.versionId;

174

175 activeEntities_.push_back(entityHandle);

176

177 return true;

178 }

References helios::engine::runtime::pooling::EntityPool< THandle >::activeEntities_, helios::engine::runtime::pooling::EntityPool< THandle >::activeIndex_, helios::engine::runtime::pooling::EntityPool< THandle >::delta_, helios::engine::runtime::pooling::EntityPool< THandle >::inactiveEntities_, helios::engine::runtime::pooling::registerComponents and helios::engine::runtime::pooling::EntityPool< THandle >::versionIndex_.

activeCount()

template <typename THandle>

size_t helios::engine::runtime::pooling::EntityPool< THandle >::activeCount ()

inline noexcept

Returns the number of active game objects.

Returns

The number of active game objects.

Definition at line 337 of file EntityPool.ixx.

337 [[nodiscard]] size_t activeCount() const noexcept {

338 return activeEntities_.size();

339 }

Reference helios::engine::runtime::pooling::EntityPool< THandle >::activeEntities_.

Referenced by helios::engine::runtime::pooling::EntityPool< THandle >::addInactive.

activeEntities()

template <typename THandle>

std::span< THandle > helios::engine::runtime::pooling::EntityPool< THandle >::activeEntities ()

inline

Returns a span of all active EntityHandles.

Returns

Span of active EntityHandles.

Definition at line 364 of file EntityPool.ixx.

364 std::span<THandle> activeEntities() {

365 return activeEntities_;

366 };

Reference helios::engine::runtime::pooling::EntityPool< THandle >::activeEntities_.

addInactive()

template <typename THandle>

bool helios::engine::runtime::pooling::EntityPool< THandle >::addInactive (const THandle entityHandle)

inline

Adds a EntityHandle to the inactive list without acquiring it.

Used during pool initialization to register pre-created Entities. Fails if the pool is already at capacity.

Parameters

entityHandle

The EntityHandle of the Entity to add.

Returns

True if added successfully, false if pool is full.

Definition at line 212 of file EntityPool.ixx.

212 bool addInactive(const THandle entityHandle) {

213

214 assert(!locked_ && "Pool is locked");

215

216 assert(entityHandle.isValid() && "Unexpected invalid entityHandle");

217

218 const size_t used = (activeCount() + inactiveCount());

219

220 minEntityId_ = std::min(minEntityId_, entityHandle.entityId);

221 maxEntityId_ = std::max(maxEntityId_, entityHandle.entityId);

222

223

224 if (used < size()) {

225 inactiveEntities_.push_back(entityHandle);

226 return true;

227 }

228

229 return false;

230 }

References helios::engine::runtime::pooling::EntityPool< THandle >::activeCount, helios::engine::runtime::pooling::EntityPool< THandle >::inactiveCount, helios::engine::runtime::pooling::EntityPool< THandle >::inactiveEntities_, helios::engine::runtime::pooling::EntityPool< THandle >::locked_, helios::engine::runtime::pooling::EntityPool< THandle >::maxEntityId_, helios::engine::runtime::pooling::EntityPool< THandle >::minEntityId_, helios::engine::runtime::pooling::registerComponents and helios::engine::runtime::pooling::EntityPool< THandle >::size.

guid()

template <typename THandle>

helios::engine::util::Guid helios::engine::runtime::pooling::EntityPool< THandle >::guid ()

inline noexcept

Returns the unique identifier of this pool.

Returns

The Guid assigned to this pool instance.

Definition at line 131 of file EntityPool.ixx.

131 [[nodiscard]] helios::engine::util::Guid guid() const noexcept {

132 return guid_;

133 }

Reference helios::engine::runtime::pooling::EntityPool< THandle >::guid_.

inactiveCount()

template <typename THandle>

size_t helios::engine::runtime::pooling::EntityPool< THandle >::inactiveCount ()

inline noexcept

Returns the number of inactive game objects.

Returns

The number of inactive game objects.

Definition at line 346 of file EntityPool.ixx.

346 [[nodiscard]] size_t inactiveCount() const noexcept {

347 return inactiveEntities_.size();

348 }

Reference helios::engine::runtime::pooling::EntityPool< THandle >::inactiveEntities_.

Referenced by helios::engine::runtime::pooling::EntityPool< THandle >::addInactive.

inactiveEntities()

template <typename THandle>

std::span< THandle > helios::engine::runtime::pooling::EntityPool< THandle >::inactiveEntities ()

inline

Returns a span of all inactive EntityHandles.

Returns

Span of inactive EntityHandles.

Definition at line 355 of file EntityPool.ixx.

355 std::span<THandle> inactiveEntities() {

356 return inactiveEntities_;

357 };

Reference helios::engine::runtime::pooling::EntityPool< THandle >::inactiveEntities_.

isLocked()

template <typename THandle>

bool helios::engine::runtime::pooling::EntityPool< THandle >::isLocked ()

inline noexcept

Checks if the pool is locked.

Returns

True if the pool is locked and ready for acquire/release operations.

Definition at line 185 of file EntityPool.ixx.

185 [[nodiscard]] bool isLocked() const noexcept {

186 return locked_;

187 }

Reference helios::engine::runtime::pooling::EntityPool< THandle >::locked_.

lock()

template <typename THandle>

void helios::engine::runtime::pooling::EntityPool< THandle >::lock ()

inline noexcept

Locks the pool for acquire/release operations.

After locking, no more EntityHandles can be added via addInactive(). The sparse arrays are sized based on the min/max EntityIds added.

Definition at line 195 of file EntityPool.ixx.

195 void lock() noexcept {

196 locked_ = true;

197 delta_ = minEntityId_;

198 activeIndex_.resize(maxEntityId_ - delta_ + 1, helios::ecs::types::EntityTombstone);

199 versionIndex_.resize(maxEntityId_ - delta_ + 1, helios::ecs::types::EntityTombstone);

200 }

References helios::engine::runtime::pooling::EntityPool< THandle >::activeIndex_, helios::engine::runtime::pooling::EntityPool< THandle >::delta_, helios::engine::runtime::pooling::EntityPool< THandle >::locked_, helios::engine::runtime::pooling::EntityPool< THandle >::maxEntityId_, helios::engine::runtime::pooling::EntityPool< THandle >::minEntityId_ and helios::engine::runtime::pooling::EntityPool< THandle >::versionIndex_.

release()

template <typename THandle>

bool helios::engine::runtime::pooling::EntityPool< THandle >::release (const THandle entityHandle)

inline

Releases a Entity back to the pool by its EntityHandle.

Validates the EntityHandle against both the GameWorld and the active tracking list. Uses swap-and-pop for O(1) removal from the active list. The object is marked inactive and added to the inactive list for future acquisition.

Parameters

entityHandle

The unique identifier of the Entity to release.

Returns

True if the object was successfully released, false if the EntityHandle was not found in the GameWorld or not tracked as active.

Definition at line 245 of file EntityPool.ixx.

245 bool release(const THandle entityHandle) {

246

247 assert(entityHandle.isValid() && "Unexpected invalid entityHandle");

248

249 assert(entityHandle.entityId >= delta_ && "Unexpected entityHandle");

250

251 const auto sparseIdx = entityHandle.entityId - delta_;

252

253 assert(sparseIdx < activeIndex_.size() && "Unexpected sparse index");

254

255 const auto denseIndex = activeIndex_[sparseIdx];

256 if (denseIndex == helios::ecs::types::EntityTombstone) {

257 return false;

258 }

259

260 assert(versionIndex_[sparseIdx] == entityHandle.versionId && "Version mismatch");

261

262 auto lastEntityHandle = activeEntities_.back();

263

264 if (denseIndex != activeEntities_.size() - 1) {

265 // swap the last entityHandle in activeEntities with the

266 // entityHandle to remove, effectively overwriting entityHandle

267 // to release with a currently active entityHandle

268 activeEntities_[denseIndex] = lastEntityHandle;

269 activeIndex_[lastEntityHandle.entityId-delta_] = denseIndex;

270 versionIndex_[lastEntityHandle.entityId-delta_] = lastEntityHandle.versionId;

271 }

272

273

274 // the swap operation has create a duplicate entry,

275 // remove the one at the tail

276 activeEntities_.pop_back();

277

278 // clear the queried entityHandle from active index and update

279 // inactiveEntities

280 activeIndex_[sparseIdx] = helios::ecs::types::EntityTombstone;

281 versionIndex_[sparseIdx] = helios::ecs::types::EntityTombstone;

282

283 inactiveEntities_.push_back(entityHandle);

284

285 return true;

286 }

References helios::engine::runtime::pooling::EntityPool< THandle >::activeEntities_, helios::engine::runtime::pooling::EntityPool< THandle >::activeIndex_, helios::engine::runtime::pooling::EntityPool< THandle >::delta_, helios::engine::runtime::pooling::EntityPool< THandle >::inactiveEntities_, helios::engine::runtime::pooling::registerComponents and helios::engine::runtime::pooling::EntityPool< THandle >::versionIndex_.

releaseAndRemove()

template <typename THandle>

bool helios::engine::runtime::pooling::EntityPool< THandle >::releaseAndRemove (const THandle entityHandle)

inline

Releases and permanently removes a Entity from the pool.

Unlike release(), this method does not add the EntityHandle back to the inactive list. Use this when a pooled object is being destroyed rather than recycled.

Parameters

entityHandle

The unique identifier of the Entity to remove.

Returns

True if removed successfully, false if EntityHandle was not active.

Definition at line 299 of file EntityPool.ixx.

299 bool releaseAndRemove(const THandle entityHandle) {

300

301 assert(entityHandle.isValid() && "Unexpected invalid entityHandle");

302

303 const auto sparseIdx = entityHandle.entityId - delta_;

304

305 assert(sparseIdx < activeIndex_.size() && "Unexpected sparse index");

306

307 const auto denseIndex = activeIndex_[sparseIdx];

308

309 if (denseIndex == helios::ecs::types::EntityTombstone) {

310 return false;

311 }

312

313 assert(versionIndex_[sparseIdx] == entityHandle.versionId && "Version mismatch");

314

315 if (denseIndex != activeEntities_.size() - 1) {

316 const auto lastEntityHandle = activeEntities_.back();

317 activeIndex_[lastEntityHandle.entityId - delta_] = denseIndex;

318 versionIndex_[lastEntityHandle.entityId - delta_] = lastEntityHandle.versionId;

319 activeEntities_[denseIndex] = lastEntityHandle;

320 }

321

322 activeEntities_.pop_back();

323

324 activeIndex_[sparseIdx] = helios::ecs::types::EntityTombstone;

325 versionIndex_[sparseIdx] = helios::ecs::types::EntityTombstone;

326

327 return true;

328

329 }

References helios::engine::runtime::pooling::EntityPool< THandle >::activeEntities_, helios::engine::runtime::pooling::EntityPool< THandle >::activeIndex_, helios::engine::runtime::pooling::EntityPool< THandle >::delta_, helios::engine::runtime::pooling::registerComponents and helios::engine::runtime::pooling::EntityPool< THandle >::versionIndex_.

size()

template <typename THandle>

size_t helios::engine::runtime::pooling::EntityPool< THandle >::size ()

inline noexcept

Returns the maximum capacity of this pool.

Returns

The pool size specified at construction.

Definition at line 140 of file EntityPool.ixx.

140 [[nodiscard]] size_t size() const noexcept {

141 return poolSize_;

142 }

Reference helios::engine::runtime::pooling::EntityPool< THandle >::poolSize_.

Referenced by helios::engine::runtime::pooling::EntityPool< THandle >::addInactive.

Protected Member Attributes

activeEntities_

template <typename THandle>

std::vector<THandle> helios::engine::runtime::pooling::EntityPool< THandle >::activeEntities_

protected

List of EntityHandles for currently active (in-use) Entities.

Definition at line 68 of file EntityPool.ixx.

68 std::vector<THandle> activeEntities_;

Referenced by helios::engine::runtime::pooling::EntityPool< THandle >::acquire, helios::engine::runtime::pooling::EntityPool< THandle >::activeCount, helios::engine::runtime::pooling::EntityPool< THandle >::activeEntities, helios::engine::runtime::pooling::EntityPool< THandle >::EntityPool, helios::engine::runtime::pooling::EntityPool< THandle >::release and helios::engine::runtime::pooling::EntityPool< THandle >::releaseAndRemove.

activeIndex_

template <typename THandle>

std::vector<size_t> helios::engine::runtime::pooling::EntityPool< THandle >::activeIndex_

protected

Maps active Entity EntityIds to their index in activeEntities_.

Enables O(1) lookup for release operations.

Definition at line 56 of file EntityPool.ixx.

56 std::vector<size_t> activeIndex_;

Referenced by helios::engine::runtime::pooling::EntityPool< THandle >::acquire, helios::engine::runtime::pooling::EntityPool< THandle >::lock, helios::engine::runtime::pooling::EntityPool< THandle >::release and helios::engine::runtime::pooling::EntityPool< THandle >::releaseAndRemove.

delta_

template <typename THandle>

size_t helios::engine::runtime::pooling::EntityPool< THandle >::delta_ = 0

protected

Offset for sparse array indexing (equals minEntityId_ after lock).

Definition at line 93 of file EntityPool.ixx.

93 size_t delta_ = 0;

Referenced by helios::engine::runtime::pooling::EntityPool< THandle >::acquire, helios::engine::runtime::pooling::EntityPool< THandle >::lock, helios::engine::runtime::pooling::EntityPool< THandle >::release and helios::engine::runtime::pooling::EntityPool< THandle >::releaseAndRemove.

guid_

template <typename THandle>

const helios::engine::util::Guid helios::engine::runtime::pooling::EntityPool< THandle >::guid_

protected

Unique identifier for this pool instance.

Definition at line 98 of file EntityPool.ixx.

98 const helios::engine::util::Guid guid_;

Referenced by helios::engine::runtime::pooling::EntityPool< THandle >::guid.

inactiveEntities_

template <typename THandle>

std::vector<THandle> helios::engine::runtime::pooling::EntityPool< THandle >::inactiveEntities_

protected

List of EntityHandles for currently inactive (available) Entities.

Definition at line 73 of file EntityPool.ixx.

73 std::vector<THandle> inactiveEntities_;

Referenced by helios::engine::runtime::pooling::EntityPool< THandle >::acquire, helios::engine::runtime::pooling::EntityPool< THandle >::addInactive, helios::engine::runtime::pooling::EntityPool< THandle >::EntityPool, helios::engine::runtime::pooling::EntityPool< THandle >::inactiveCount, helios::engine::runtime::pooling::EntityPool< THandle >::inactiveEntities and helios::engine::runtime::pooling::EntityPool< THandle >::release.

locked_

template <typename THandle>

bool helios::engine::runtime::pooling::EntityPool< THandle >::locked_ = false

protected

True if the pool is locked and ready for acquire/release operations.

Definition at line 103 of file EntityPool.ixx.

103 bool locked_ = false;

Referenced by helios::engine::runtime::pooling::EntityPool< THandle >::addInactive, helios::engine::runtime::pooling::EntityPool< THandle >::isLocked and helios::engine::runtime::pooling::EntityPool< THandle >::lock.

maxEntityId_

template <typename THandle>

helios::ecs::types::EntityId helios::engine::runtime::pooling::EntityPool< THandle >::maxEntityId_ = std::numeric_limits<helios::ecs::types::EntityId>::lowest()

protected

Maximum EntityId in the pool (used for sparse array sizing).

Definition at line 88 of file EntityPool.ixx.

88 helios::ecs::types::EntityId maxEntityId_ = std::numeric_limits<helios::ecs::types::EntityId>::lowest();

Referenced by helios::engine::runtime::pooling::EntityPool< THandle >::addInactive and helios::engine::runtime::pooling::EntityPool< THandle >::lock.

minEntityId_

template <typename THandle>

helios::ecs::types::EntityId helios::engine::runtime::pooling::EntityPool< THandle >::minEntityId_ = std::numeric_limits<helios::ecs::types::EntityId>::max()

protected

Minimum EntityId in the pool (used for sparse array offset).

Definition at line 83 of file EntityPool.ixx.

83 helios::ecs::types::EntityId minEntityId_ = std::numeric_limits<helios::ecs::types::EntityId>::max();

Referenced by helios::engine::runtime::pooling::EntityPool< THandle >::addInactive and helios::engine::runtime::pooling::EntityPool< THandle >::lock.

poolSize_

template <typename THandle>

size_t helios::engine::runtime::pooling::EntityPool< THandle >::poolSize_ = 0

protected

The maximum number of objects this pool manages.

Definition at line 78 of file EntityPool.ixx.

78 size_t poolSize_ = 0;

Referenced by helios::engine::runtime::pooling::EntityPool< THandle >::size.

versionIndex_

template <typename THandle>

std::vector<size_t> helios::engine::runtime::pooling::EntityPool< THandle >::versionIndex_

protected

Tracks version numbers for active EntityHandles.

Used to validate that a release operation targets the correct entity version.

Definition at line 63 of file EntityPool.ixx.

63 std::vector<size_t> versionIndex_;

Referenced by helios::engine::runtime::pooling::EntityPool< THandle >::acquire, helios::engine::runtime::pooling::EntityPool< THandle >::lock, helios::engine::runtime::pooling::EntityPool< THandle >::release and helios::engine::runtime::pooling::EntityPool< THandle >::releaseAndRemove.

---

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

• EntityPool.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.9.8.