LibXR::SPSCQueue< Data > Class Template Reference

单生产者单消费者无锁队列。 More...

#include <spsc_queue.hpp>

Inheritance diagram for LibXR::SPSCQueue< Data >:

Collaboration diagram for LibXR::SPSCQueue< Data >:

Public Types
using	ValueType = Data
Public Types inherited from LibXR::QueueTypedBase< SPSCQueue< Data >, Data >
using	ValueType
	队列元素类型。 Queue element type.
Public Types inherited from LibXR::SPSCQueueBase
using	IndexType = size_t
	环形缓冲区索引类型 / Ring-buffer index type.

Public Member Functions
	SPSCQueue (size_t length)
	构造一个 SPSC 队列。
	~SPSCQueue ()=default
	析构一个 SPSC 队列。
ErrorCode	Peek (Data &item)
	查看一个队头 payload 但不出队。
ErrorCode	PushBatch (const Data *data, size_t size)
	批量推入多个 payload。
template<typename Writer >
ErrorCode	PushWithWriter (Writer &&writer)
	通过写入器回调推入一个 payload。
template<typename Writer >
ErrorCode	PushWithWriter (size_t size, Writer &&writer)
	通过写入器回调批量推入 payload。
template<typename Reader >
ErrorCode	PopWithReader (Reader &&reader)
	通过读取器回调弹出一个 payload。
template<typename Reader >
ErrorCode	PopWithReader (size_t size, Reader &&reader)
	通过读取器回调批量弹出 payload。
ErrorCode	PopBatch (Data *data, size_t size)
	批量弹出多个 payload。
ErrorCode	PeekBatch (Data *data, size_t size)
	批量查看多个 payload 但不出队。
void	Reset ()
	重置队列状态。
Public Member Functions inherited from LibXR::QueueTypedBase< SPSCQueue< Data >, Data >
ErrorCode	Push (const Data &item)
	推入一个强类型元素。
ErrorCode	Pop (Data &item)
	弹出一个强类型元素。
ErrorCode	Pop ()
	丢弃一个队头元素。
Public Member Functions inherited from LibXR::SPSCQueueBase
	SPSCQueueBase (size_t element_size, size_t capacity)
	构造 SPSC 字节队列内核 / Construct the SPSC byte-queue core
	SPSCQueueBase (size_t element_size, size_t element_align, size_t capacity)
	构造 SPSC 字节队列内核并指定元素对齐 / Construct the SPSC byte-queue core with explicit element alignment
	~SPSCQueueBase ()
	析构 SPSC 字节队列内核 / Destroy the SPSC byte-queue core
ErrorCode	PushBytes (const void *value)
	按字节入队一个 payload / Enqueue one payload by bytes
ErrorCode	PopBytes (void *value=nullptr)
	按字节出队一个 payload；传空指针时仅丢弃队头元素 / Dequeue one payload by bytes; pass null to discard the front item only
ErrorCode	PeekBytes (void *value)
	按字节查看一个队头 payload 但不出队 / Peek one front payload by bytes without dequeuing it
ErrorCode	PushBatchBytes (const void *data, size_t count)
	按字节批量入队多个 payload / Enqueue multiple payloads by bytes
template<typename Writer >
ErrorCode	PushBytesWithWriter (size_t count, Writer &&writer)
	通过写入器回调批量入队 payload / Enqueue payloads through a writer callback
ErrorCode	PopBatchBytes (void *data, size_t count)
	按字节批量出队多个 payload / Dequeue multiple payloads by bytes
template<typename Reader >
ErrorCode	PopBytesWithReader (size_t count, Reader &&reader)
	通过读取器回调批量出队 payload / Dequeue payloads through a reader callback
ErrorCode	PeekBatchBytes (void *data, size_t count)
	按字节批量查看多个 payload 但不出队 / Peek multiple payloads by bytes without dequeuing them
void	Reset ()
	重置队列状态 / Reset the queue state
size_t	Size () const
	获取当前已用元素数 / Get the current element count
size_t	EmptySize () const
	获取剩余空槽数 / Get the current free-slot count
size_t	MaxSize () const
	获取队列最大容量 / Get the maximum queue capacity

Detailed Description

template<typename Data>
class LibXR::SPSCQueue< Data >

单生产者单消费者无锁队列。

Single-producer single-consumer lock-free queue.

模板壳只把 Data 映射为固定大小的字节 payload 并复用 SPSCQueueBase， 不在队列内部管理 Data 对象生命周期。调用方必须保证 payload 可以按该 项目的队列契约进行字节搬运。

This template wrapper maps Data to a fixed-size byte payload and reuses SPSCQueueBase. It does not manage Data object lifetime inside the queue. The caller must ensure that the payload is valid for this project's byte-moving queue contract.

Template Parameters

Data	队列存储的数据类型。 Queue element type.

Definition at line 28 of file spsc_queue.hpp.

Member Typedef Documentation

ValueType

template<typename Data >

using LibXR::SPSCQueue< Data >::ValueType = Data

队列元素类型。 Queue element type.

Definition at line 34 of file spsc_queue.hpp.

Constructor & Destructor Documentation

SPSCQueue()

template<typename Data >

LibXR::SPSCQueue< Data >::SPSCQueue ( size_t length )

inlineexplicit

构造一个 SPSC 队列。

Construct one SPSC queue.

Parameters

length

队列容量。 Queue capacity.

Note

包含动态内存分配。 Contains dynamic memory allocation.

Definition at line 47 of file spsc_queue.hpp.

                                    : SPSCQueueBase(sizeof(Data), alignof(Data), length)
  {
  }

~SPSCQueue()

template<typename Data >

LibXR::SPSCQueue< Data >::~SPSCQueue ( )

default

析构一个 SPSC 队列。

Destroy one SPSC queue.

Member Function Documentation

Peek()

template<typename Data >

ErrorCode LibXR::SPSCQueue< Data >::Peek ( Data & item )

inline

查看一个队头 payload 但不出队。

Peek one front payload without dequeuing it.

Parameters

item	用于接收 payload。 Receives the peeked payload.

Returns

成功返回 ErrorCode::OK；队列空返回 ErrorCode::EMPTY Returns ErrorCode::OK on success; returns ErrorCode::EMPTY when the queue is empty

Definition at line 65 of file spsc_queue.hpp.

{ return SPSCQueueBase::PeekBytes(&item); }

PeekBatch()

template<typename Data >

ErrorCode LibXR::SPSCQueue< Data >::PeekBatch ( Data * data, size_t size )

inline

批量查看多个 payload 但不出队。

Peek multiple payloads without dequeuing them.

Parameters

data	用于接收 payload 的数组。 Array receiving peeked payloads.
size	payload 个数。 Number of payloads.

Returns

成功返回 ErrorCode::OK；队列空返回 ErrorCode::EMPTY Returns ErrorCode::OK on success; returns ErrorCode::EMPTY when the queue does not contain enough payloads

Definition at line 217 of file spsc_queue.hpp.

  {
    return SPSCQueueBase::PeekBatchBytes(data, size);
  }

PopBatch()

template<typename Data >

ErrorCode LibXR::SPSCQueue< Data >::PopBatch ( Data * data, size_t size )

inline

批量弹出多个 payload。

Pop multiple payloads from the queue.

Parameters

data	用于接收 payload 的数组。 Array receiving dequeued payloads.
size	payload 个数。 Number of payloads.

Returns

成功返回 ErrorCode::OK；队列空返回 ErrorCode::EMPTY Returns ErrorCode::OK on success; returns ErrorCode::EMPTY when the queue does not contain enough payloads

Definition at line 203 of file spsc_queue.hpp.

  {
    return SPSCQueueBase::PopBatchBytes(data, size);
  }

PopWithReader() [1/2]

template<typename Data >

template<typename Reader >

ErrorCode LibXR::SPSCQueue< Data >::PopWithReader ( Reader && reader )

inline

通过读取器回调弹出一个 payload。

Pop one payload via a reader callback.

Template Parameters

Reader

读取器类型。 Reader callback type.

Parameters

reader

读取器回调，签名为 ErrorCode(const Data* buffer, size_t count) Reader callback with signature ErrorCode(const Data* buffer, size_t count).

Returns

成功返回 ErrorCode::OK；队列空返回 ErrorCode::EMPTY；否则返回读取器错误码 Returns ErrorCode::OK on success; returns ErrorCode::EMPTY when the queue is empty; otherwise returns the reader error code

Note

回调中的 count 固定为 1，读取器成功后才提交出队。 The callback always receives count == 1; the pop is committed only after the reader succeeds.

Definition at line 152 of file spsc_queue.hpp.

  {
    return PopWithReader(1, std::forward<Reader>(reader));
  }

PopWithReader() [2/2]

template<typename Data >

template<typename Reader >

ErrorCode LibXR::SPSCQueue< Data >::PopWithReader ( size_t size, Reader && reader )

inline

通过读取器回调批量弹出 payload。

Pop multiple payloads via a reader callback.

Template Parameters

Reader

读取器类型。 Reader callback type.

Parameters

size	payload 个数。 Number of payloads.
reader	读取器回调，签名为 ErrorCode(const Data* buffer, size_t count)。 Reader callback with signature ErrorCode(const Data* buffer, size_t count).

Returns

成功返回 ErrorCode::OK；队列空返回 ErrorCode::EMPTY；否则返回读取器错误码。 Returns ErrorCode::OK on success; returns ErrorCode::EMPTY when the queue is empty; otherwise returns the reader error code.

Note

仅当读取器处理完整批次后才提交出队。 The pop is committed only after the reader accepts the full batch.

Definition at line 173 of file spsc_queue.hpp.

  {
    static_assert(
        std::is_trivially_copyable_v<Data>,
        "batched SPSCQueue::PopWithReader requires trivially copyable payloads");
    static_assert(
        std::is_trivially_destructible_v<Data>,
        "batched SPSCQueue::PopWithReader requires trivially destructible payloads");
    static_assert(std::is_invocable_v<Reader&, const Data*, size_t>,
                  "PopWithReader reader must be callable as "
                  "ErrorCode(const Data* buffer, size_t count)");
    using ReaderRet = std::invoke_result_t<Reader&, const Data*, size_t>;
    static_assert(std::is_convertible_v<ReaderRet, ErrorCode>,
                  "PopWithReader reader return type must be convertible to ErrorCode");
 
    Reader& reader_ref = reader;
    return SPSCQueueBase::PopBytesWithReader(
        size, [&](const void* buffer, size_t count) -> ErrorCode
        { return reader_ref(static_cast<const Data*>(buffer), count); });
  }

PushBatch()

template<typename Data >

ErrorCode LibXR::SPSCQueue< Data >::PushBatch ( const Data * data, size_t size )

inline

批量推入多个 payload。

Push multiple payloads into the queue.

Parameters

data	payload 数组指针。 Pointer to the payload array.
size	payload 个数。 Number of payloads.

Returns

成功返回 ErrorCode::OK；队列满返回 ErrorCode::FULL Returns ErrorCode::OK on success; returns ErrorCode::FULL when the queue is full

Definition at line 76 of file spsc_queue.hpp.

  {
    return SPSCQueueBase::PushBatchBytes(data, size);
  }

PushWithWriter() [1/2]

template<typename Data >

template<typename Writer >

ErrorCode LibXR::SPSCQueue< Data >::PushWithWriter ( size_t size, Writer && writer )

inline

通过写入器回调批量推入 payload。

Push multiple payloads via a writer callback.

Template Parameters

Writer

写入器类型。 Writer callback type.

Parameters

size	payload 个数。 Number of payloads.
writer	写入器回调，签名为 ErrorCode(Data* buffer, size_t count)。 Writer callback with signature ErrorCode(Data* buffer, size_t count).

Returns

成功返回 ErrorCode::OK；队列满返回 ErrorCode::FULL；否则返回写入器错误码。 Returns ErrorCode::OK on success; returns ErrorCode::FULL when the queue is full; otherwise returns the writer error code.

Note

仅当写入器处理完整批次后才提交入队。 The enqueue is committed only after the writer accepts the full batch.

Definition at line 116 of file spsc_queue.hpp.

  {
    static_assert(
        std::is_trivially_copyable_v<Data>,
        "batched SPSCQueue::PushWithWriter requires trivially copyable payloads");
    static_assert(
        std::is_trivially_destructible_v<Data>,
        "batched SPSCQueue::PushWithWriter requires trivially destructible payloads");
    static_assert(std::is_invocable_v<Writer&, Data*, size_t>,
                  "PushWithWriter writer must be callable as "
                  "ErrorCode(Data* buffer, size_t count)");
    using WriterRet = std::invoke_result_t<Writer&, Data*, size_t>;
    static_assert(std::is_convertible_v<WriterRet, ErrorCode>,
                  "PushWithWriter writer return type must be convertible to ErrorCode");
 
    Writer& writer_ref = writer;
    return SPSCQueueBase::PushBytesWithWriter(
        size, [&](void* buffer, size_t count) -> ErrorCode
        { return writer_ref(static_cast<Data*>(buffer), count); });
  }

PushWithWriter() [2/2]

template<typename Data >

template<typename Writer >

ErrorCode LibXR::SPSCQueue< Data >::PushWithWriter ( Writer && writer )

inline

通过写入器回调推入一个 payload。

Push one payload via a writer callback.

Template Parameters

Writer

写入器类型。 Writer callback type.

Parameters

writer

写入器回调，签名为 ErrorCode(Data* buffer, size_t count) Writer callback with signature ErrorCode(Data* buffer, size_t count).

Returns

成功返回 ErrorCode::OK；队列满返回 ErrorCode::FULL；否则返回写入器错误码 Returns ErrorCode::OK on success; returns ErrorCode::FULL when the queue is full; otherwise returns the writer error code

Note

回调中的 count 固定为 1，成功写入后才提交到队列。 The callback always receives count == 1; the payload is committed only after the writer succeeds.

Definition at line 96 of file spsc_queue.hpp.

  {
    return PushWithWriter(1, std::forward<Writer>(writer));
  }

Reset()

template<typename Data >

void LibXR::SPSCQueue< Data >::Reset ( )

inline

重置队列状态。

Reset the queue state.

Definition at line 226 of file spsc_queue.hpp.

{ SPSCQueueBase::Reset(); }

---

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

• src/structure/queue/spsc_queue.hpp