LibXR::SlotPool< T > Class Template Reference

面向任务与中断的小容量消息槽池。 Small message slot pool shared between tasks and interrupts. More...

#include <slot_pool.hpp>

Inheritance diagram for LibXR::SlotPool< T >:

Collaboration diagram for LibXR::SlotPool< T >:

Public Member Functions
	SlotPool (size_t slot_count)
	构造槽池 / Construct one slot pool.
T &	At (size_t index)
	访问自己持有的槽（写入中或读取中）/ Access an owned slot (writing or reading).
const T &	At (size_t index) const
	只读访问自己持有的槽 / Read-only access to an owned slot.
ErrorCode	Put (const T &value)
	便捷入队：Acquire + 拷贝 + Publish / Convenient enqueue: Acquire + copy + Publish.
ErrorCode	Get (T &value)
	便捷出队：Take + 拷贝 + Release / Convenient dequeue: Take + copy + Release.
Public Member Functions inherited from LibXR::SlotPoolBase
	SlotPoolBase (size_t slot_size, size_t slot_align, size_t slot_count)
	构造槽池内核 / Construct the slot-pool core.
	~SlotPoolBase ()
	析构槽池内核 / Destroy the slot-pool core.
ErrorCode	Acquire (size_t &index)
	认领一个空闲槽（空闲 → 写入中） / Claim one free slot (free -> writing).
void	Publish (size_t index)
	发布已写好的槽（写入中 → 就绪），并取得发布序号 / Publish a fully written slot (writing -> ready) and take a publish sequence number.
ErrorCode	Take (size_t &index)
	认领序号最小的就绪槽（就绪 → 读取中） / Claim the oldest ready slot (ready -> reading).
void	Release (size_t index)
	释放自己持有的槽（写入中或读取中 → 空闲） / Release an owned slot (writing or reading -> free).
size_t	Size () const
	获取槽总数 / Get the total number of slots.

Additional Inherited Members
Protected Types inherited from LibXR::SlotPoolBase
enum	SlotState : uint32_t { SLOT_FREE = 0 , SLOT_WRITING = 1 , SLOT_READY = 2 , SLOT_READING = 3 }
	槽状态 / Slot state. More...
Protected Member Functions inherited from LibXR::SlotPoolBase
void *	SlotPtr (size_t index)
	获取指定槽位的存储地址 / Get the storage address of one slot.
const void *	SlotPtr (size_t index) const
	获取指定槽位的存储地址（只读）/ Get the storage address of one slot (const).
Protected Attributes inherited from LibXR::SlotPoolBase
const size_t	slot_size_
	单个槽的字节数 / Byte size of one slot.
const size_t	slot_count_
	槽总数 / Total number of slots.
const size_t	slot_stride_
	相邻槽位之间的步长 / Byte stride between slots.
const size_t	alloc_align_
std::atomic< uint32_t > *	states_
	每槽状态字 / Per-slot atomic state word.
std::atomic< uint32_t > *	seqs_
	每槽发布序号 / Per-slot publish sequence.
std::byte *	slots_
	槽存储缓冲区 / Byte buffer storing slots.
std::atomic< uint32_t >	publish_seq_
std::atomic< uint32_t >	release_count_
Static Protected Attributes inherited from LibXR::SlotPoolBase
static constexpr size_t	INVALID_INDEX = static_cast<size_t>(-1)
	无效槽位下标 / Sentinel for "no slot chosen".

Detailed Description

template<typename T>
class LibXR::SlotPool< T >

面向任务与中断的小容量消息槽池。 Small message slot pool shared between tasks and interrupts.

每个槽一个原子状态（空闲、写入中、就绪、读取中），所有状态转换用 CAS 完成；Publish 时取全局递增的发布序号，Take 选序号最小的就绪槽。 适用于几到几十个槽的小容量场合，Acquire/Take 是 O(N) 扫描。 一个被打断的操作只占住它自己的槽：任务停在 Acquire、写入、Publish、 Take、读取、Release 的任何中间点时，中断里的 Put/Get 都不会被挡住， 拿到的 FULL/EMPTY 反映那一刻的真实状态。多生产者多消费者均可用；请勿在 NMI 中使用。出队顺序按发布序号，同一发布者内部保序；不保证跨发布者的 全局先进先出。

Each slot carries one atomic state (free, writing, ready, reading) and every state transition is a CAS; Publish takes a globally increasing sequence and Take picks the ready slot with the smallest sequence. It targets small pools of a few to a few dozen slots; Acquire/Take are O(N) scans. An interrupted operation only occupies its own slot: while a task stops at any intermediate point of Acquire, writing, Publish, Take, reading or Release, a Put/Get from an interrupt is never blocked by it, and the FULL/EMPTY it observes reflects the true state at that moment. Any number of producers and consumers may run concurrently; do not use it inside NMI. Dequeue order follows the publish sequence, order inside one publisher is preserved, and no global cross-publisher FIFO is guaranteed.

Template Parameters

T	槽存储的数据类型 / Slot element type.

Definition at line 195 of file slot_pool.hpp.

Constructor & Destructor Documentation

SlotPool()

template<typename T >

LibXR::SlotPool< T >::SlotPool ( size_t slot_count )

inlineexplicit

构造槽池 / Construct one slot pool.

Parameters

slot_count

槽总数 / Total number of slots

Note

包含构造期内存分配，运行期不再分配 / Allocates at construction only; no allocation at run time.

Definition at line 205 of file slot_pool.hpp.

                                       : SlotPoolBase(sizeof(T), alignof(T), slot_count)
  {
  }

Member Function Documentation

At() [1/2]

template<typename T >

T & LibXR::SlotPool< T >::At ( size_t index )

inline

访问自己持有的槽（写入中或读取中）/ Access an owned slot (writing or reading).

Parameters

index

自己持有的槽位下标 / Slot index owned by the caller

Returns

槽内数据的引用 / Reference to the slot data

Definition at line 215 of file slot_pool.hpp.

{ return *static_cast<T*>(SlotPtr(index)); }

At() [2/2]

template<typename T >

const T & LibXR::SlotPool< T >::At ( size_t index ) const

inline

只读访问自己持有的槽 / Read-only access to an owned slot.

Definition at line 217 of file slot_pool.hpp.

{ return *static_cast<const T*>(SlotPtr(index)); }

Get()

template<typename T >

ErrorCode LibXR::SlotPool< T >::Get ( T & value )

inline

便捷出队：Take + 拷贝 + Release / Convenient dequeue: Take + copy + Release.

Parameters

value

接收数据的缓冲区 / Buffer receiving the data

Returns

成功返回 ErrorCode::OK；没有就绪槽返回 ErrorCode::EMPTY Returns ErrorCode::OK on success; ErrorCode::EMPTY when no slot is ready

Note

要求 T 平凡可拷贝 / Requires T to be trivially copyable.

Definition at line 252 of file slot_pool.hpp.

  {
    static_assert(std::is_trivially_copyable_v<T>,
                  "SlotPool::Get requires a trivially copyable type");
    size_t index = INVALID_INDEX;
    const ErrorCode ec = Take(index);
    if (ec != ErrorCode::OK)
    {
      return ec;
    }
    Memory::FastCopy(&value, SlotPtr(index), sizeof(T));
    Release(index);
    return ErrorCode::OK;
  }

Put()

template<typename T >

ErrorCode LibXR::SlotPool< T >::Put ( const T & value )

inline

便捷入队：Acquire + 拷贝 + Publish / Convenient enqueue: Acquire + copy + Publish.

Parameters

value

待入队的数据 / Data to enqueue

Returns

成功返回 ErrorCode::OK；没有空闲槽返回 ErrorCode::FULL Returns ErrorCode::OK on success; ErrorCode::FULL when no slot is free

Note

要求 T 平凡可拷贝 / Requires T to be trivially copyable.

Definition at line 228 of file slot_pool.hpp.

  {
    static_assert(std::is_trivially_copyable_v<T>,
                  "SlotPool::Put requires a trivially copyable type");
    size_t index = INVALID_INDEX;
    const ErrorCode ec = Acquire(index);
    if (ec != ErrorCode::OK)
    {
      return ec;
    }
    Memory::FastCopy(SlotPtr(index), &value, sizeof(T));
    Publish(index);
    return ErrorCode::OK;
  }

---

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

• src/structure/slot_pool.hpp