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...

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::core::data::EntityId	minEntityId_ = std::numeric_limits<helios::engine::core::data::EntityId>::max()
	Minimum EntityId in the pool (used for sparse array offset). More...
helios::engine::core::data::EntityId	maxEntityId_ = std::numeric_limits<helios::engine::core::data::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 43 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 113 of file GameObjectPool.ixx.

113 explicit GameObjectPool(

114 size_t poolSize

115 ) :

116 poolSize_(poolSize),

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

118 activeGameObjects_.reserve(poolSize);

119 inactiveGameObjects_.reserve(poolSize);

120 }

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 152 of file GameObjectPool.ixx.

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

153

154 if (inactiveGameObjects_.empty()) {

155 return false;

156 }

157

158 entityHandle = inactiveGameObjects_.back();

159 inactiveGameObjects_.pop_back();

160

161

162 auto idx = entityHandle.entityId - delta_;

163

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

165 activeIndex_.resize(idx + 1, helios::engine::core::data::EntityTombstone);

166 versionIndex_.resize(idx + 1, helios::engine::core::data::EntityTombstone);

167 }

168

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

170 versionIndex_[idx] = entityHandle.versionId;

171

172 activeGameObjects_.push_back(entityHandle);

173

174 return true;

175 }

References activeGameObjects_, activeIndex_, delta_, helios::engine::ecs::EntityHandle::entityId, helios::engine::core::data::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 334 of file GameObjectPool.ixx.

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

335 return activeGameObjects_.size();

336 }

Reference activeGameObjects_.

Referenced by addInactive.

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 209 of file GameObjectPool.ixx.

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

210

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

212

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

214

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

216

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

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

219

220

221 if (used < size()) {

222 inactiveGameObjects_.push_back(entityHandle);

223 return true;

224 }

225

226 return false;

227 }

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 128 of file GameObjectPool.ixx.

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

129 return guid_;

130 }

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 343 of file GameObjectPool.ixx.

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

344 return inactiveGameObjects_.size();

345 }

Reference inactiveGameObjects_.

Referenced by addInactive.

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 182 of file GameObjectPool.ixx.

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

183 return locked_;

184 }

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 192 of file GameObjectPool.ixx.

192 void lock() noexcept {

193 locked_ = true;

194 delta_ = minEntityId_;

195 activeIndex_.resize(maxEntityId_ - delta_ + 1, helios::engine::core::data::EntityTombstone);

196 versionIndex_.resize(maxEntityId_ - delta_ + 1, helios::engine::core::data::EntityTombstone);

197 }

References activeIndex_, delta_, helios::engine::core::data::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 242 of file GameObjectPool.ixx.

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

243

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

245

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

247

248 const auto sparseIdx = entityHandle.entityId - delta_;

249

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

251

252 const auto denseIndex = activeIndex_[sparseIdx];

253 if (denseIndex == helios::engine::core::data::EntityTombstone) {

254 return false;

255 }

256

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

258

259 auto lastEntityHandle = activeGameObjects_.back();

260

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

262 // swap the last entityHandle in activeGameObjects with the

263 // entityHandle to remove, effectively overwriting entityHandle

264 // to release with a currently active entityHandle

265 activeGameObjects_[denseIndex] = lastEntityHandle;

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

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

268 }

269

270

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

272 // remove the one at the tail

273 activeGameObjects_.pop_back();

274

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

276 // inactiveGameObjects

277 activeIndex_[sparseIdx] = helios::engine::core::data::EntityTombstone;

278 versionIndex_[sparseIdx] = helios::engine::core::data::EntityTombstone;

279

280 inactiveGameObjects_.push_back(entityHandle);

281

282 return true;

283 }

References activeGameObjects_, activeIndex_, delta_, helios::engine::ecs::EntityHandle::entityId, helios::engine::core::data::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 296 of file GameObjectPool.ixx.

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

297

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

299

300 const auto sparseIdx = entityHandle.entityId - delta_;

301

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

303

304 const auto denseIndex = activeIndex_[sparseIdx];

305

306 if (denseIndex == helios::engine::core::data::EntityTombstone) {

307 return false;

308 }

309

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

311

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

313 const auto lastEntityHandle = activeGameObjects_.back();

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

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

316 activeGameObjects_[denseIndex] = lastEntityHandle;

317 }

318

319 activeGameObjects_.pop_back();

320

321 activeIndex_[sparseIdx] = helios::engine::core::data::EntityTombstone;

322 versionIndex_[sparseIdx] = helios::engine::core::data::EntityTombstone;

323

324 return true;

325

326 }

References activeGameObjects_, activeIndex_, delta_, helios::engine::ecs::EntityHandle::entityId, helios::engine::core::data::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 137 of file GameObjectPool.ixx.

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

138 return poolSize_;

139 }

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 65 of file GameObjectPool.ixx.

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

Referenced by acquire, activeCount, 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 53 of file GameObjectPool.ixx.

53 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 90 of file GameObjectPool.ixx.

90 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 95 of file GameObjectPool.ixx.

95 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 70 of file GameObjectPool.ixx.

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

Referenced by acquire, addInactive, GameObjectPool, inactiveCount 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 100 of file GameObjectPool.ixx.

100 bool locked_ = false;

Referenced by addInactive, isLocked and lock.

maxEntityId_

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

protected

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

Definition at line 85 of file GameObjectPool.ixx.

85 helios::engine::core::data::EntityId maxEntityId_ = std::numeric_limits<helios::engine::core::data::EntityId>::lowest();

Referenced by addInactive and lock.

minEntityId_

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

protected

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

Definition at line 80 of file GameObjectPool.ixx.

80 helios::engine::core::data::EntityId minEntityId_ = std::numeric_limits<helios::engine::core::data::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 75 of file GameObjectPool.ixx.

75 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 60 of file GameObjectPool.ixx.

60 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.