单生产者单消费者无锁队列。 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 35 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 48 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 67 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 223 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 209 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 158 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 178 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 81 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 121 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 101 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 232 of file spsc_queue.hpp.

232{ SPSCQueueBase::Reset(); }

LibXR::SPSCQueueBase::Reset

void Reset()

重置队列状态 / Reset the queue state

Definition spsc_queue_base.hpp:412

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

src/structure/queue/spsc_queue.hpp

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ ValueType

Constructor & Destructor Documentation

◆ SPSCQueue()

◆ ~SPSCQueue()

Member Function Documentation

◆ Peek()

◆ PeekBatch()

◆ PopBatch()

◆ PopWithReader() [1/2]

◆ PopWithReader() [2/2]

◆ PushBatch()

◆ PushWithWriter() [1/2]

◆ PushWithWriter() [2/2]

◆ Reset()