基于空闲索引队列的 RAII 槽池。 More...

#include <object_pool.hpp>

Collaboration diagram for LibXR::BasicObjectPool< Data, FreeQueue >:

Data Structures
class	Handle
	槽索引必须是整数类型。 Slot indices must use an integral type. More...

Public Types
using	ValueType = Data
	槽内对象类型。 Slot object type.

using	QueueType = FreeQueue
	空闲索引队列类型。 Free-index queue type.

using	IndexType = typename FreeQueue::ValueType
	槽索引类型。 Slot index type.

Public Member Functions
template<typename T = Data> requires std::is_default_constructible_v<T>
	BasicObjectPool (size_t slot_count)
	用内部 queue 和内部 slots 构造 pool。

	BasicObjectPool (size_t slot_count, Data *slots)
	用内部 queue 和外部 slots 构造 pool。

template<typename T = Data> requires std::is_default_constructible_v<T>
	BasicObjectPool (FreeQueue &free_queue, size_t slot_count)
	用外部 queue 和内部 slots 构造 pool。

	BasicObjectPool (FreeQueue &free_queue, size_t slot_count, Data *slots)
	用外部 queue 和外部 slots 构造 pool。

	~BasicObjectPool ()
	析构对象池，并释放其拥有的内部资源。

	BasicObjectPool (const BasicObjectPool &)=delete
	禁止拷贝构造。 Non-copyable.

BasicObjectPool &	operator= (const BasicObjectPool &)=delete
	禁止拷贝赋值。 Non-copy-assignable.

	BasicObjectPool (BasicObjectPool &&)=delete
	禁止移动构造。 Non-movable.

BasicObjectPool &	operator= (BasicObjectPool &&)=delete
	禁止移动赋值。 Non-move-assignable.

ErrorCode	Acquire (Handle &handle)
	获取一个槽位 handle。

size_t	EmptySize () const
	返回当前仍可获取的空闲槽位数。

size_t	Size () const
	返回对象池总槽位数。

Data &	UnsafeAt (size_t index)
	通过槽位索引直接访问对象，不参与所有权检查。

const Data &	UnsafeAt (size_t index) const
	通过槽位索引只读直接访问对象，不参与所有权检查。

Private Member Functions
ErrorCode	Release (IndexType index)
	把指定槽位索引归还到空闲队列。

void	ConstructOwnedQueue (size_t slot_count)
	在内部存储区里构造一个自拥有空闲队列。

void	AllocateOwnedSlots ()
	申请并拥有内部槽数组。

void	InitializeFreeQueue ()
	用 `0 .. slot_count - 1` 初始化空闲索引队列。

Private Attributes
std::byte	free_queue_storage_ [sizeof(FreeQueue)] = {}
	内部自拥有 queue 的原地构造存储区。 In-place storage for an internally owned queue.

FreeQueue *	free_queue_
	空闲索引队列指针。 Pointer to the free-index queue.

const size_t	slot_count_
	槽位总数。 Total slot count.

Data *	slots_ = nullptr
	槽数组指针。 Pointer to slot storage.

bool	owns_free_queue_
	是否拥有内部 queue。 Whether this pool owns the free queue.

bool	owns_slots_
	是否拥有内部 slots。 Whether this pool owns the slot storage.

Detailed Description

template<typename Data, PoolIndexQueue FreeQueue>
class LibXR::BasicObjectPool< Data, FreeQueue >

基于空闲索引队列的 RAII 槽池。

RAII slot pool backed by a free-index queue.

该池使用一个索引队列管理空闲槽位；成功获取后返回 move-only Handle，其析构会自动把槽位索引归还到空闲队列。这样上层只依赖四类队列共享的最小 typed 接口。

This pool uses one index queue to manage free slots. Successful acquisition returns one move-only Handle, whose destructor automatically returns the slot index back to the free queue. This keeps the upper layer dependent only on the minimal typed interface shared by the queue family.

Template Parameters

Data	槽内对象类型。 Slot object type.
FreeQueue	空闲索引队列类型。 Free-index queue type.

Definition at line 58 of file object_pool.hpp.

Member Typedef Documentation

◆ IndexType

template<typename Data , PoolIndexQueue FreeQueue>

using LibXR::BasicObjectPool< Data, FreeQueue >::IndexType = typename FreeQueue::ValueType

槽索引类型。 Slot index type.

Definition at line 63 of file object_pool.hpp.

◆ QueueType

template<typename Data , PoolIndexQueue FreeQueue>

using LibXR::BasicObjectPool< Data, FreeQueue >::QueueType = FreeQueue

空闲索引队列类型。 Free-index queue type.

Definition at line 62 of file object_pool.hpp.

◆ ValueType

template<typename Data , PoolIndexQueue FreeQueue>

using LibXR::BasicObjectPool< Data, FreeQueue >::ValueType = Data

槽内对象类型。 Slot object type.

Definition at line 61 of file object_pool.hpp.

Constructor & Destructor Documentation

◆ BasicObjectPool() [1/4]

template<typename Data , PoolIndexQueue FreeQueue>

template<typename T = Data>
requires std::is_default_constructible_v<T>

LibXR::BasicObjectPool< Data, FreeQueue >::BasicObjectPool ( size_t slot_count )

inlineexplicit

用内部 queue 和内部 slots 构造 pool。

Construct the pool with an internal queue and internal slots.

Parameters

slot_count 槽位数量。 Number of slots.

Definition at line 237 of file object_pool.hpp.

                                              : slot_count_(slot_count)
  {
    ASSERT(slot_count_ > 0);
    ConstructOwnedQueue(slot_count_);
    AllocateOwnedSlots();
    InitializeFreeQueue();
  }

◆ BasicObjectPool() [2/4]

template<typename Data , PoolIndexQueue FreeQueue>

LibXR::BasicObjectPool< Data, FreeQueue >::BasicObjectPool	(	size_t	slot_count,
		Data *	slots )

inline

用内部 queue 和外部 slots 构造 pool。

Construct the pool with an internal queue and external slots.

Parameters

slot_count	槽位数量。 Number of slots.
slots	外部槽数组。 Caller-provided slot storage.

Note: 调用方必须保证 slots 指向至少 slot_count 个 Data 槽位。 The caller must ensure that slots points to at least slot_count Data slots.

Definition at line 255 of file object_pool.hpp.

                                                  : slot_count_(slot_count), slots_(slots)
  {
    ASSERT(slot_count_ > 0);
    ASSERT(slots_ != nullptr);
    ConstructOwnedQueue(slot_count_);
    InitializeFreeQueue();
  }

◆ BasicObjectPool() [3/4]

template<typename Data , PoolIndexQueue FreeQueue>

template<typename T = Data>
requires std::is_default_constructible_v<T>

LibXR::BasicObjectPool< Data, FreeQueue >::BasicObjectPool	(	FreeQueue &	free_queue,
		size_t	slot_count )

inline

用外部 queue 和内部 slots 构造 pool。

Construct the pool with an external queue and internal slots.

Parameters

free_queue	外部空闲索引队列。 Caller-provided free-index queue.
slot_count	槽位数量。 Number of slots.

Note: 调用方传入的 free_queue 必须是空队列，并且只供当前 pool 独占使用。 The caller-provided free_queue must be empty and dedicated to this pool.; 调用方必须保证 free_queue 的容量至少为 slot_count。 The caller must ensure that free_queue capacity is at least slot_count.

Definition at line 276 of file object_pool.hpp.

      : free_queue_(&free_queue), slot_count_(slot_count)
  {
    ASSERT(slot_count_ > 0);
    ASSERT(free_queue.Size() == 0);
    AllocateOwnedSlots();
    InitializeFreeQueue();
  }

◆ BasicObjectPool() [4/4]

template<typename Data , PoolIndexQueue FreeQueue>

LibXR::BasicObjectPool< Data, FreeQueue >::BasicObjectPool	(	FreeQueue &	free_queue,
		size_t	slot_count,
		Data *	slots )

inline

用外部 queue 和外部 slots 构造 pool。

Construct the pool with an external queue and external slots.

Parameters

free_queue	外部空闲索引队列。 Caller-provided free-index queue.
slot_count	槽位数量。 Number of slots.
slots	外部槽数组。 Caller-provided slot storage.

Note: 调用方传入的 free_queue 必须是空队列，并且只供当前 pool 独占使用。 The caller-provided free_queue must be empty and dedicated to this pool.; 调用方必须保证 free_queue 的容量至少为 slot_count。 The caller must ensure that free_queue capacity is at least slot_count.; 调用方必须保证 slots 指向至少 slot_count 个 Data 槽位。 The caller must ensure that slots points to at least slot_count Data slots.

Definition at line 300 of file object_pool.hpp.

      : free_queue_(&free_queue), slot_count_(slot_count), slots_(slots)
  {
    ASSERT(slot_count_ > 0);
    ASSERT(slots_ != nullptr);
    ASSERT(free_queue.Size() == 0);
    InitializeFreeQueue();
  }

◆ ~BasicObjectPool()

template<typename Data , PoolIndexQueue FreeQueue>

LibXR::BasicObjectPool< Data, FreeQueue >::~BasicObjectPool ( )

inline

析构对象池，并释放其拥有的内部资源。

Destroy the object pool and release owned internal resources.

Definition at line 313 of file object_pool.hpp.

  {
    ASSERT(EmptySize() == slot_count_);
 
    if (owns_slots_)
    {
      delete[] slots_;
    }
 
    if (owns_free_queue_)
    {
      free_queue_->~FreeQueue();
    }
  }

Member Function Documentation

◆ Acquire()

template<typename Data , PoolIndexQueue FreeQueue>

ErrorCode LibXR::BasicObjectPool< Data, FreeQueue >::Acquire ( Handle & handle )

inlinenodiscard

获取一个槽位 handle。

Acquire one slot handle.

Parameters

handle 用于接收成功获取的 handle。 Handle receiving the acquired slot.

Returns: 成功返回 ErrorCode::OK，池空返回 ErrorCode::EMPTY。 Returns ErrorCode::OK on success and ErrorCode::EMPTY when the pool is empty.

Definition at line 345 of file object_pool.hpp.

  {
    ASSERT(!handle.Valid());
 
    IndexType index = 0;
    const ErrorCode ec = free_queue_->Pop(index);
    if (ec != ErrorCode::OK)
    {
      return ec;
    }
 
    ASSERT(static_cast<size_t>(index) < slot_count_);
    handle = Handle(this, index);
    return ErrorCode::OK;
  }

◆ AllocateOwnedSlots()

template<typename Data , PoolIndexQueue FreeQueue>

void LibXR::BasicObjectPool< Data, FreeQueue >::AllocateOwnedSlots ( )

inlineprivate

申请并拥有内部槽数组。

Allocate and own the internal slot storage.

Definition at line 440 of file object_pool.hpp.

  {
    slots_ = new Data[slot_count_];
    owns_slots_ = true;
  }

◆ ConstructOwnedQueue()

template<typename Data , PoolIndexQueue FreeQueue>

void LibXR::BasicObjectPool< Data, FreeQueue >::ConstructOwnedQueue ( size_t slot_count )

inlineprivate

在内部存储区里构造一个自拥有空闲队列。

Construct an owned free queue inside internal storage.

Parameters

slot_count 槽位数量，同时也是初始化时要压入的索引数量。 Slot count and thus the number of indices to preload.

Definition at line 430 of file object_pool.hpp.

  {
    free_queue_ = new (free_queue_storage_) FreeQueue(slot_count);
    owns_free_queue_ = true;
  }

◆ EmptySize()

template<typename Data , PoolIndexQueue FreeQueue>

size_t LibXR::BasicObjectPool< Data, FreeQueue >::EmptySize ( ) const

inlinenodiscard

返回当前仍可获取的空闲槽位数。

Return the number of currently acquirable free slots.

Returns: 当前空闲槽位数。 Current number of free slots.

Definition at line 366 of file object_pool.hpp.

366{ return free_queue_->Size(); }

◆ InitializeFreeQueue()

template<typename Data , PoolIndexQueue FreeQueue>

void LibXR::BasicObjectPool< Data, FreeQueue >::InitializeFreeQueue ( )

inlineprivate

用 0 .. slot_count - 1 初始化空闲索引队列。

Initialize the free-index queue with 0 .. slot_count - 1.

Definition at line 450 of file object_pool.hpp.

  {
    ASSERT(slot_count_ > 0);
    ASSERT(slot_count_ - 1 <= static_cast<size_t>(std::numeric_limits<IndexType>::max()));
    for (size_t index = 0; index < slot_count_; ++index)
    {
      const ErrorCode ec = free_queue_->Push(static_cast<IndexType>(index));
      ASSERT(ec == ErrorCode::OK);
    }
  }

◆ Release()

template<typename Data , PoolIndexQueue FreeQueue>

ErrorCode LibXR::BasicObjectPool< Data, FreeQueue >::Release ( IndexType index )

inlineprivate

把指定槽位索引归还到空闲队列。

Return the given slot index back to the free queue.

Parameters

index 待归还的槽位索引。 Slot index to return.

Returns: 底层空闲队列返回的结果码。 Result code returned by the underlying free queue.

Definition at line 418 of file object_pool.hpp.

  {
    ASSERT(static_cast<size_t>(index) < slot_count_);
    return free_queue_->Push(index);
  }

◆ Size()

template<typename Data , PoolIndexQueue FreeQueue>

size_t LibXR::BasicObjectPool< Data, FreeQueue >::Size ( ) const

inlinenodiscard

返回对象池总槽位数。

Return the total number of slots in the pool.

Returns: 槽位总数。 Total slot count.

Definition at line 373 of file object_pool.hpp.

373{ return slot_count_; }

◆ UnsafeAt() [1/2]

template<typename Data , PoolIndexQueue FreeQueue>

Data & LibXR::BasicObjectPool< Data, FreeQueue >::UnsafeAt ( size_t index )

inlinenodiscard

通过槽位索引直接访问对象，不参与所有权检查。

Access an object by slot index without ownership checks.

Parameters

index 槽位索引。 Slot index.

Returns: 对应槽位对象的引用。 Reference to the object stored in the slot.

Note: 该接口会绕过 Acquire() / Handle 的所有权语义，只适合调试、检查外部存储区或其他明确知道槽位状态的场景。 This API bypasses the ownership semantics of Acquire() / Handle, and is intended only for debugging, external-storage inspection, or other cases where the caller already knows the slot state.

Definition at line 387 of file object_pool.hpp.

  {
    ASSERT(index < slot_count_);
    return slots_[index];
  }

◆ UnsafeAt() [2/2]

template<typename Data , PoolIndexQueue FreeQueue>

const Data & LibXR::BasicObjectPool< Data, FreeQueue >::UnsafeAt ( size_t index ) const

inlinenodiscard

通过槽位索引只读直接访问对象，不参与所有权检查。

Access an object by slot index as const without ownership checks.

Parameters

index 槽位索引。 Slot index.

Returns: 对应槽位对象的常量引用。 Const reference to the object stored in the slot.

Note: 该接口会绕过 Acquire() / Handle 的所有权语义，只适合调试、检查外部存储区或其他明确知道槽位状态的场景。 This API bypasses the ownership semantics of Acquire() / Handle, and is intended only for debugging, external-storage inspection, or other cases where the caller already knows the slot state.

Definition at line 405 of file object_pool.hpp.

  {
    ASSERT(index < slot_count_);
    return slots_[index];
  }

Field Documentation

◆ free_queue_

template<typename Data , PoolIndexQueue FreeQueue>

FreeQueue* LibXR::BasicObjectPool< Data, FreeQueue >::free_queue_

private

Initial value:

=

nullptr

空闲索引队列指针。 Pointer to the free-index queue.

Definition at line 464 of file object_pool.hpp.

◆ free_queue_storage_

template<typename Data , PoolIndexQueue FreeQueue>

std::byte LibXR::BasicObjectPool< Data, FreeQueue >::free_queue_storage_[sizeof(FreeQueue)] = {}

private

内部自拥有 queue 的原地构造存储区。 In-place storage for an internally owned queue.

Definition at line 463 of file object_pool.hpp.

463{};

◆ owns_free_queue_

template<typename Data , PoolIndexQueue FreeQueue>

bool LibXR::BasicObjectPool< Data, FreeQueue >::owns_free_queue_

private

Initial value:

=

false

是否拥有内部 queue。 Whether this pool owns the free queue.

Definition at line 468 of file object_pool.hpp.

◆ owns_slots_

template<typename Data , PoolIndexQueue FreeQueue>

bool LibXR::BasicObjectPool< Data, FreeQueue >::owns_slots_

private

Initial value:

=

false

是否拥有内部 slots。 Whether this pool owns the slot storage.

Definition at line 470 of file object_pool.hpp.

◆ slot_count_

template<typename Data , PoolIndexQueue FreeQueue>

const size_t LibXR::BasicObjectPool< Data, FreeQueue >::slot_count_

private

槽位总数。 Total slot count.

Definition at line 466 of file object_pool.hpp.

◆ slots_

template<typename Data , PoolIndexQueue FreeQueue>

Data* LibXR::BasicObjectPool< Data, FreeQueue >::slots_ = nullptr

private

槽数组指针。 Pointer to slot storage.

Definition at line 467 of file object_pool.hpp.

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

src/structure/object_pool.hpp

Data Structures

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ IndexType

◆ QueueType

◆ ValueType

Constructor & Destructor Documentation

◆ BasicObjectPool() [1/4]

◆ BasicObjectPool() [2/4]

◆ BasicObjectPool() [3/4]

◆ BasicObjectPool() [4/4]

◆ ~BasicObjectPool()

Member Function Documentation

◆ Acquire()

◆ AllocateOwnedSlots()

◆ ConstructOwnedQueue()

◆ EmptySize()

◆ InitializeFreeQueue()

◆ Release()

◆ Size()

◆ UnsafeAt() [1/2]

◆ UnsafeAt() [2/2]

Field Documentation

◆ free_queue_

◆ free_queue_storage_

◆ owns_free_queue_

◆ owns_slots_

◆ slot_count_

◆ slots_