GameObjectPool Class

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

Declaration

class helios::engine::runtime::pooling::GameObjectPool { ... }

Public Constructors Index

	GameObjectPool (size_t poolSize)
	Constructs a GameObjectPool with the specified capacity. More...

Public Member Functions Index

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

Protected Member Attributes Index

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

Description

Object pool for efficient GameObject lifecycle management.

GameObjectPool manages a fixed-size collection of GameObject 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

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

Todo

Prevent duplicate EntityHandles from being added to the pool.

Definition at line 45 of file GameObjectPool.ixx.

Public Constructors

GameObjectPool()

helios::engine::runtime::pooling::GameObjectPool::GameObjectPool (size_t poolSize)

inline explicit

Constructs a GameObjectPool 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 GameObjects this pool can manage.

Definition at line 115 of file GameObjectPool.ixx.

115 explicit GameObjectPool(

116 size_t poolSize

117 ) :

118 poolSize_(poolSize),

119 guid_(helios::util::Guid::generate()) {

120 activeGameObjects_.reserve(poolSize);

121 inactiveGameObjects_.reserve(poolSize);

122 }

References activeGameObjects_, guid_, inactiveGameObjects_ and poolSize_.

Public Member Functions

acquire()

bool helios::engine::runtime::pooling::GameObjectPool::acquire (helios::engine::ecs::EntityHandle & entityHandle)

inline nodiscard

Acquires an inactive GameObject 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 GameObject 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 154 of file GameObjectPool.ixx.

154 [[nodiscard]] bool acquire(helios::engine::ecs::EntityHandle& entityHandle) {

155

156 if (inactiveGameObjects_.empty()) {

157 return false;

158 }

159

160 entityHandle = inactiveGameObjects_.back();

161 inactiveGameObjects_.pop_back();

162

163

164 auto idx = entityHandle.entityId - delta_;

165

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

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

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

169 }

170

171 activeIndex_[idx] = activeGameObjects_.size();

172 versionIndex_[idx] = entityHandle.versionId;

173

174 activeGameObjects_.push_back(entityHandle);

175

176 return true;

177 }

References activeGameObjects_, activeIndex_, delta_, helios::engine::ecs::EntityHandle::entityId, helios::engine::ecs::types::EntityTombstone, inactiveGameObjects_, helios::engine::ecs::EntityHandle::versionId and versionIndex_.

activeCount()

size_t helios::engine::runtime::pooling::GameObjectPool::activeCount ()

inline nodiscard noexcept

Returns the number of active game objects.

Returns

The number of active game objects.

Definition at line 336 of file GameObjectPool.ixx.

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

337 return activeGameObjects_.size();

338 }

Reference activeGameObjects_.

Referenced by addInactive.

activeGameObjects()

std::span< helios::engine::ecs::EntityHandle > helios::engine::runtime::pooling::GameObjectPool::activeGameObjects ()

inline

Returns a span of all active EntityHandles.

Returns

Span of active EntityHandles.

Definition at line 363 of file GameObjectPool.ixx.

363 std::span<helios::engine::ecs::EntityHandle> activeGameObjects() {

364 return activeGameObjects_;

365 };

Reference activeGameObjects_.

addInactive()

bool helios::engine::runtime::pooling::GameObjectPool::addInactive (const helios::engine::ecs::EntityHandle entityHandle)

inline

Adds a EntityHandle to the inactive list without acquiring it.

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

Parameters

entityHandle

The EntityHandle of the GameObject to add.

Returns

True if added successfully, false if pool is full.

Definition at line 211 of file GameObjectPool.ixx.

211 bool addInactive(const helios::engine::ecs::EntityHandle entityHandle) {

212

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

214

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

216

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

218

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

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

221

222

223 if (used < size()) {

224 inactiveGameObjects_.push_back(entityHandle);

225 return true;

226 }

227

228 return false;

229 }

References activeCount, helios::engine::ecs::EntityHandle::entityId, inactiveCount, inactiveGameObjects_, helios::engine::ecs::EntityHandle::isValid, locked_, maxEntityId_, minEntityId_ and size.

guid()

helios::util::Guid helios::engine::runtime::pooling::GameObjectPool::guid ()

inline nodiscard noexcept

Returns the unique identifier of this pool.

Returns

The Guid assigned to this pool instance.

Definition at line 130 of file GameObjectPool.ixx.

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

131 return guid_;

132 }

Reference guid_.

inactiveCount()

size_t helios::engine::runtime::pooling::GameObjectPool::inactiveCount ()

inline nodiscard noexcept

Returns the number of inactive game objects.

Returns

The number of inactive game objects.

Definition at line 345 of file GameObjectPool.ixx.

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

346 return inactiveGameObjects_.size();

347 }

Reference inactiveGameObjects_.

Referenced by addInactive.

inactiveGameObjects()

std::span< helios::engine::ecs::EntityHandle > helios::engine::runtime::pooling::GameObjectPool::inactiveGameObjects ()

inline

Returns a span of all inactive EntityHandles.

Returns

Span of inactive EntityHandles.

Definition at line 354 of file GameObjectPool.ixx.

354 std::span<helios::engine::ecs::EntityHandle> inactiveGameObjects() {

355 return inactiveGameObjects_;

356 };

Reference inactiveGameObjects_.

isLocked()

bool helios::engine::runtime::pooling::GameObjectPool::isLocked ()

inline nodiscard noexcept

Checks if the pool is locked.

Returns

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

Definition at line 184 of file GameObjectPool.ixx.

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

185 return locked_;

186 }

Reference locked_.

lock()

void helios::engine::runtime::pooling::GameObjectPool::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 194 of file GameObjectPool.ixx.

194 void lock() noexcept {

195 locked_ = true;

196 delta_ = minEntityId_;

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

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

199 }

References activeIndex_, delta_, helios::engine::ecs::types::EntityTombstone, locked_, maxEntityId_, minEntityId_ and versionIndex_.

release()

bool helios::engine::runtime::pooling::GameObjectPool::release (const helios::engine::ecs::EntityHandle entityHandle)

inline

Releases a GameObject 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 GameObject 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 244 of file GameObjectPool.ixx.

244 bool release(const helios::engine::ecs::EntityHandle entityHandle) {

245

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

247

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

249

250 const auto sparseIdx = entityHandle.entityId - delta_;

251

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

253

254 const auto denseIndex = activeIndex_[sparseIdx];

255 if (denseIndex == helios::engine::ecs::types::EntityTombstone) {

256 return false;

257 }

258

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

260

261 auto lastEntityHandle = activeGameObjects_.back();

262

263 if (denseIndex != activeGameObjects_.size() - 1) {

264 // swap the last entityHandle in activeGameObjects with the

265 // entityHandle to remove, effectively overwriting entityHandle

266 // to release with a currently active entityHandle

267 activeGameObjects_[denseIndex] = lastEntityHandle;

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

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

270 }

271

272

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

274 // remove the one at the tail

275 activeGameObjects_.pop_back();

276

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

278 // inactiveGameObjects

279 activeIndex_[sparseIdx] = helios::engine::ecs::types::EntityTombstone;

280 versionIndex_[sparseIdx] = helios::engine::ecs::types::EntityTombstone;

281

282 inactiveGameObjects_.push_back(entityHandle);

283

284 return true;

285 }

References activeGameObjects_, activeIndex_, delta_, helios::engine::ecs::EntityHandle::entityId, helios::engine::ecs::types::EntityTombstone, inactiveGameObjects_, helios::engine::ecs::EntityHandle::isValid, helios::engine::ecs::EntityHandle::versionId and versionIndex_.

releaseAndRemove()

bool helios::engine::runtime::pooling::GameObjectPool::releaseAndRemove (const helios::engine::ecs::EntityHandle entityHandle)

inline

Releases and permanently removes a GameObject 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 GameObject to remove.

Returns

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

Definition at line 298 of file GameObjectPool.ixx.

298 bool releaseAndRemove(const helios::engine::ecs::EntityHandle entityHandle) {

299

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

301

302 const auto sparseIdx = entityHandle.entityId - delta_;

303

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

305

306 const auto denseIndex = activeIndex_[sparseIdx];

307

308 if (denseIndex == helios::engine::ecs::types::EntityTombstone) {

309 return false;

310 }

311

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

313

314 if (denseIndex != activeGameObjects_.size() - 1) {

315 const auto lastEntityHandle = activeGameObjects_.back();

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

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

318 activeGameObjects_[denseIndex] = lastEntityHandle;

319 }

320

321 activeGameObjects_.pop_back();

322

323 activeIndex_[sparseIdx] = helios::engine::ecs::types::EntityTombstone;

324 versionIndex_[sparseIdx] = helios::engine::ecs::types::EntityTombstone;

325

326 return true;

327

328 }

References activeGameObjects_, activeIndex_, delta_, helios::engine::ecs::EntityHandle::entityId, helios::engine::ecs::types::EntityTombstone, helios::engine::ecs::EntityHandle::isValid, helios::engine::ecs::EntityHandle::versionId and versionIndex_.

size()

size_t helios::engine::runtime::pooling::GameObjectPool::size ()

inline nodiscard noexcept

Returns the maximum capacity of this pool.

Returns

The pool size specified at construction.

Definition at line 139 of file GameObjectPool.ixx.

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

140 return poolSize_;

141 }

Reference poolSize_.

Referenced by addInactive.

Protected Member Attributes

activeGameObjects_

std::vector<helios::engine::ecs::EntityHandle> helios::engine::runtime::pooling::GameObjectPool::activeGameObjects_

protected

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

Definition at line 67 of file GameObjectPool.ixx.

67 std::vector<helios::engine::ecs::EntityHandle> activeGameObjects_;

Referenced by acquire, activeCount, activeGameObjects, GameObjectPool, release and releaseAndRemove.

activeIndex_

std::vector<size_t> helios::engine::runtime::pooling::GameObjectPool::activeIndex_

protected

Maps active GameObject EntityIds to their index in activeGameObjects_.

Enables O(1) lookup for release operations.

Definition at line 55 of file GameObjectPool.ixx.

55 std::vector<size_t> activeIndex_;

Referenced by acquire, lock, release and releaseAndRemove.

delta_

size_t helios::engine::runtime::pooling::GameObjectPool::delta_ = 0

protected

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

Definition at line 92 of file GameObjectPool.ixx.

92 size_t delta_ = 0;

Referenced by acquire, lock, release and releaseAndRemove.

guid_

const helios::util::Guid helios::engine::runtime::pooling::GameObjectPool::guid_

protected

Unique identifier for this pool instance.

Definition at line 97 of file GameObjectPool.ixx.

97 const helios::util::Guid guid_;

Referenced by GameObjectPool and guid.

inactiveGameObjects_

std::vector<helios::engine::ecs::EntityHandle> helios::engine::runtime::pooling::GameObjectPool::inactiveGameObjects_

protected

List of EntityHandles for currently inactive (available) GameObjects.

Definition at line 72 of file GameObjectPool.ixx.

72 std::vector<helios::engine::ecs::EntityHandle> inactiveGameObjects_;

Referenced by acquire, addInactive, GameObjectPool, inactiveCount, inactiveGameObjects and release.

locked_

bool helios::engine::runtime::pooling::GameObjectPool::locked_ = false

protected

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

Definition at line 102 of file GameObjectPool.ixx.

102 bool locked_ = false;

Referenced by addInactive, isLocked and lock.

maxEntityId_

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

protected

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

Definition at line 87 of file GameObjectPool.ixx.

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

Referenced by addInactive and lock.

minEntityId_

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

protected

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

Definition at line 82 of file GameObjectPool.ixx.

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

Referenced by addInactive and lock.

poolSize_

size_t helios::engine::runtime::pooling::GameObjectPool::poolSize_ = 0

protected

The maximum number of objects this pool manages.

Definition at line 77 of file GameObjectPool.ixx.

77 size_t poolSize_ = 0;

Referenced by GameObjectPool and size.

versionIndex_

std::vector<size_t> helios::engine::runtime::pooling::GameObjectPool::versionIndex_

protected

Tracks version numbers for active EntityHandles.

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

Definition at line 62 of file GameObjectPool.ixx.

62 std::vector<size_t> versionIndex_;

Referenced by acquire, lock, release and releaseAndRemove.

---

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

• GameObjectPool.ixx

---

Generated via doxygen2docusaurus 2.0.0 by Doxygen 1.15.0.