LibXR::SPSCQueue< Data > Class Template Reference

单生产者单消费者无锁队列 / Single-producer single-consumer lock-free queue. 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 队列 / Construct one SPSC queue.
	~SPSCQueue ()=default
	析构一个 SPSC 队列 / Destroy one SPSC queue.
ErrorCode	Peek (Data &item)
	查看一个队头 payload 但不出队 / Peek one front payload without dequeuing it.
ErrorCode	PushBatch (const Data *data, size_t size)
	批量推入多个 payload / Push multiple payloads into the queue.
template<typename Writer >
ErrorCode	PushWithWriter (Writer &&writer)
	通过写入器回调推入一个 payload / Push one payload via a writer callback.
template<typename Writer >
ErrorCode	PushWithWriter (size_t size, Writer &&writer)
	通过写入器回调批量推入 payload / Push multiple payloads via a writer callback.
template<typename Writer >
size_t	ProduceWithWriter (size_t limit, Writer &&writer)
	通过一次双 span 回调生产 payload 前缀 / Produce a payload prefix through one two-span writer callback.
template<typename Reader >
ErrorCode	PopWithReader (Reader &&reader)
	通过读取器回调弹出一个 payload / Pop one payload via a reader callback.
template<typename Reader >
ErrorCode	PopWithReader (size_t size, Reader &&reader)
	通过读取器回调批量弹出 payload / Pop multiple payloads via a reader callback.
template<typename Reader >
size_t	ConsumeWithReader (size_t limit, Reader &&reader)
	通过一次双 span 回调消费 payload 前缀 / Consume a payload prefix through one two-span reader callback.
ErrorCode	PopBatch (Data *data, size_t size)
	批量弹出多个 payload / Pop multiple payloads from the queue.
ErrorCode	PeekBatch (Data *data, size_t size)
	批量查看多个 payload 但不出队 / Peek multiple payloads without dequeuing them.
void	Reset ()
	从 consumer 侧丢弃当前可见的全部 payload / Discard currently available payloads from the consumer side
Public Member Functions inherited from LibXR::QueueTypedBase< SPSCQueue< Data >, Data >
ErrorCode	Push (const Data &item)
	推入一个强类型元素 / Push one typed element.
ErrorCode	Pop (Data &item)
	弹出一个强类型元素 / Pop one typed element.
ErrorCode	Pop ()
	丢弃一个队头元素 / Discard one front element.
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
template<typename Writer >
size_t	ProduceWithWriter (size_t limit, Writer &&writer)
	通过一次双 span 回调生产 payload 前缀 / Produce a payload prefix through one two-span 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
template<typename Reader >
size_t	ConsumeWithReader (size_t limit, Reader &&reader)
	通过一次双 span 回调消费 payload 前缀 / Consume a payload prefix through one two-span reader callback.
ErrorCode	PeekBatchBytes (void *data, size_t count)
	按字节批量查看多个 payload 但不出队 / Peek multiple payloads by bytes without dequeuing them
void	Reset ()
	从 consumer 侧丢弃当前可见的全部 payload / Discard all currently available payloads from the consumer side
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 27 of file spsc_queue.hpp.

Member Typedef Documentation

ValueType

template<typename Data >

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

队列元素类型 / Queue element type.

Definition at line 33 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 45 of file spsc_queue.hpp.

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

Member Function Documentation

ConsumeWithReader()

template<typename Data >

template<typename Reader >

size_t LibXR::SPSCQueue< Data >::ConsumeWithReader ( size_t limit, Reader && reader )

inline

通过一次双 span 回调消费 payload 前缀 / Consume a payload prefix through one two-span reader callback.

Template Parameters

Reader

读取器类型 / Reader callback type.

Parameters

limit	最多提供的 payload 个数 / Maximum number of offered payloads.
reader	签名为 size_t(const Data*, size_t, const Data*, size_t)，返回已接受的 前缀个数 / Callback with signature size_t(const Data*, size_t, const Data*, size_t); returns the accepted prefix count.

Returns

实际从队列移除的 payload 个数 / Number of payloads removed from the queue.

Precondition

队列只有一个 consumer；回调期间不得重入同侧操作或 Reset / The queue has one consumer; no same-side operation or Reset during the callback.

Note

没有可用数据或 limit == 0 时不调用回调；回调指针只在调用期间有效 / The callback is skipped when no data is available or limit == 0; pointers are valid only during the callback.

Definition at line 231 of file spsc_queue.hpp.

  {
    static_assert(std::is_trivially_copyable_v<Data>);
    static_assert(std::is_trivially_destructible_v<Data>);
    return SPSCQueueBase::ConsumeWithReader(
        limit,
        [&](const void* first, size_t first_size, const void* second,
            size_t second_size) -> size_t
        {
          return reader(static_cast<const Data*>(first), first_size,
                        static_cast<const Data*>(second), second_size);
        });
  }

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 61 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 266 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 253 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 174 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 194 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); });
  }

ProduceWithWriter()

template<typename Data >

template<typename Writer >

size_t LibXR::SPSCQueue< Data >::ProduceWithWriter ( size_t limit, Writer && writer )

inline

通过一次双 span 回调生产 payload 前缀 / Produce a payload prefix through one two-span writer callback.

Template Parameters

Writer

写入器类型 / Writer callback type.

Parameters

limit	最多提供的 payload 个数 / Maximum number of offered payloads.
writer	签名为 size_t(Data*, size_t, Data*, size_t)，返回已写入的前缀个数 / Callback with signature size_t(Data*, size_t, Data*, size_t); returns the written prefix count.

Returns

实际发布到队列的 payload 个数 / Number of payloads published to the queue.

Precondition

队列只有一个 producer；回调期间不得重入同侧操作或 Reset / The queue has one producer; no same-side operation or Reset during the callback.

Note

没有可用空间或 limit == 0 时不调用回调；回调指针只在调用期间有效 / The callback is skipped when no space is available or limit == 0; pointers are valid only during the callback.

Definition at line 147 of file spsc_queue.hpp.

  {
    static_assert(std::is_trivially_copyable_v<Data>);
    static_assert(std::is_trivially_destructible_v<Data>);
    return SPSCQueueBase::ProduceWithWriter(
        limit,
        [&](void* first, size_t first_size, void* second, size_t second_size) -> size_t
        {
          return writer(static_cast<Data*>(first), first_size, static_cast<Data*>(second),
                        second_size);
        });
  }

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 71 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 110 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 90 of file spsc_queue.hpp.

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

Reset()

template<typename Data >

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

inline

从 consumer 侧丢弃当前可见的全部 payload / Discard currently available payloads from the consumer side

Definition at line 275 of file spsc_queue.hpp.

{ SPSCQueueBase::Reset(); }

---

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

• src/structure/queue/spsc_queue.hpp