提供固定大小循环缓冲区的字节 FIFO 队列。 Byte FIFO queue providing a fixed-size circular buffer. More...

#include <queue_base.hpp>

Inheritance diagram for LibXR::QueueBase:

Public Member Functions
	QueueBase (uint16_t element_size, size_t length, uint8_t *buffer)
	使用外部缓冲区构造队列 / Construct the queue with an external buffer.

	QueueBase (uint16_t element_size, size_t length)
	由队列内部申请缓冲区并构造队列。 Construct the queue with an internally allocated buffer.

	~QueueBase ()
	析构队列 / Destroy the queue.

void *	operator[] (uint32_t index)
	访问指定物理槽位的原始元素地址。 Access the raw element address of one physical slot.

ErrorCode	PushBytes (const void *data)
	按字节入队一个元素 / Enqueue one element by bytes.

ErrorCode	PeekBytes (void *data)
	按字节查看队头元素但不出队。 Peek the front element by bytes without dequeuing it.

ErrorCode	PopBytes (void *data=nullptr)
	按字节出队一个元素；传空指针时仅丢弃队头。 Dequeue one element by bytes; pass null to discard the front item only.

int	GetLastElementIndex () const
	获取当前最后一个已入队元素的物理槽位下标。 Get the physical slot index of the current last queued element.

int	GetFirstElementIndex () const
	获取当前第一个已入队元素的物理槽位下标。 Get the physical slot index of the current first queued element.

ErrorCode	PushBatchBytes (const void *data, size_t size)
	按字节批量入队多个元素 / Enqueue multiple elements by bytes.

ErrorCode	PopBatchBytes (void *data, size_t size)
	按字节批量出队多个元素 / Dequeue multiple elements by bytes.

ErrorCode	PeekBatchBytes (void *data, size_t size)
	按字节批量查看多个元素但不出队。 Peek multiple elements by bytes without dequeuing them.

ErrorCode	OverwriteBytes (const void *data)
	清空当前状态后，用一个新元素覆盖队列内容。 Reset the queue state and overwrite it with one new element.

void	Reset ()
	重置队列状态 / Reset the queue state.

size_t	Size () const
	获取当前已存储元素个数 / Get the current stored element count.

size_t	EmptySize () const
	获取当前剩余空槽数 / Get the current free-slot count.

size_t	MaxSize () const
	获取队列最大容量 / Get the maximum queue capacity.

Public Attributes
uint8_t *	queue_array_
	队列数据缓冲区 / Queue data buffer.

const uint16_t	ELEMENT_SIZE
	单个元素的字节数 / Byte size of one element.

size_t	head_ = 0
	当前队头物理槽位下标 / Physical slot index of the current head.

size_t	tail_ = 0

bool	is_full_ = false
	当前队列是否已满 / Whether the queue is currently full.

size_t	length_
	队列最大容量 / Maximum queue capacity.

bool	own_buffer_
	是否由当前队列拥有缓冲区 / Whether this queue owns the buffer.

Detailed Description

提供固定大小循环缓冲区的字节 FIFO 队列。 Byte FIFO queue providing a fixed-size circular buffer.

该类只按固定元素大小搬运字节，不管理强类型对象的构造、析构或所有权。 This class moves fixed-size byte elements only and does not manage typed object construction, destruction, or ownership.

Definition at line 19 of file queue_base.hpp.

Constructor & Destructor Documentation

◆ QueueBase() [1/2]

QueueBase::QueueBase	(	uint16_t	element_size,
		size_t	length,
		uint8_t *	buffer )

使用外部缓冲区构造队列 / Construct the queue with an external buffer.

Parameters

element_size	队列中每个元素的字节数 / Byte size of each queue element.
length	队列最大容量 / Maximum queue capacity.
buffer	外部缓冲区指针 / Pointer to the external buffer.

Definition at line 7 of file queue_base.cpp.

    : queue_array_(buffer),
      ELEMENT_SIZE(element_size),
      length_(length),
      own_buffer_(false)
{
}

◆ QueueBase() [2/2]

QueueBase::QueueBase	(	uint16_t	element_size,
		size_t	length )

由队列内部申请缓冲区并构造队列。 Construct the queue with an internally allocated buffer.

Parameters

element_size	队列中每个元素的字节数 / Byte size of each queue element.
length	队列最大容量 / Maximum queue capacity.

Note: 包含动态内存分配 / Contains dynamic memory allocation.

Definition at line 15 of file queue_base.cpp.

    : queue_array_(new uint8_t[length * element_size]),
      ELEMENT_SIZE(element_size),
      length_(length),
      own_buffer_(true)
{
}

◆ ~QueueBase()

QueueBase::~QueueBase ( )

析构队列 / Destroy the queue.

Definition at line 23 of file queue_base.cpp.

{
  if (own_buffer_)
  {
    delete[] queue_array_;
  }
}

Member Function Documentation

◆ EmptySize()

size_t QueueBase::EmptySize ( ) const

nodiscard

获取当前剩余空槽数 / Get the current free-slot count.

Returns: 当前剩余空槽数 / Current number of free slots.

Definition at line 231 of file queue_base.cpp.

231{ return length_ - Size(); }

LibXR::QueueBase::Size

size_t Size() const

获取当前已存储元素个数 / Get the current stored element count.

Definition queue_base.cpp:215

◆ GetFirstElementIndex()

int QueueBase::GetFirstElementIndex ( ) const

获取当前第一个已入队元素的物理槽位下标。 Get the physical slot index of the current first queued element.

Returns: 队列非空时返回第一个元素的物理槽位下标，否则返回 -1。 Returns the physical slot index of the first element, or -1 when the queue is empty.

Definition at line 96 of file queue_base.cpp.

{
  if (Size() == 0)
  {
    return -1;
  }
  return static_cast<int>(head_);
}

◆ GetLastElementIndex()

int QueueBase::GetLastElementIndex ( ) const

获取当前最后一个已入队元素的物理槽位下标。 Get the physical slot index of the current last queued element.

Returns: 队列非空时返回最后一个元素的物理槽位下标，否则返回 -1。 Returns the physical slot index of the last element, or -1 when the queue is empty.

Definition at line 87 of file queue_base.cpp.

{
  if (Size() == 0)
  {
    return -1;
  }
  return static_cast<int>((tail_ + length_ - 1) % length_);
}

◆ MaxSize()

size_t LibXR::QueueBase::MaxSize ( ) const

inlinenodiscard

获取队列最大容量 / Get the maximum queue capacity.

Returns: 队列最大容量 / Maximum queue capacity.

Definition at line 163 of file queue_base.hpp.

163{ return length_; }

◆ operator[]()

void * QueueBase::operator[] ( uint32_t index )

nodiscard

访问指定物理槽位的原始元素地址。 Access the raw element address of one physical slot.

Parameters

index 目标物理槽位下标 / Target physical slot index.

Returns: 指向该槽位元素起始地址的指针。 Pointer to the element base address of the slot.

Definition at line 31 of file queue_base.cpp.

{
  return &queue_array_[static_cast<size_t>(index * ELEMENT_SIZE)];
}

◆ OverwriteBytes()

ErrorCode QueueBase::OverwriteBytes ( const void * data )

清空当前状态后，用一个新元素覆盖队列内容。 Reset the queue state and overwrite it with one new element.

Parameters

data	指向新元素的指针 / Pointer to the new element.

Returns: 成功返回 ErrorCode::OK / Returns ErrorCode::OK on success.

Definition at line 191 of file queue_base.cpp.

{
  ASSERT(data != nullptr);
 
  head_ = tail_ = 0;
  is_full_ = false;
 
  LibXR::Memory::FastCopy(queue_array_, data, ELEMENT_SIZE);
 
  tail_ = (tail_ + 1) % length_;
  if (head_ == tail_)
  {
    is_full_ = true;
  }
 
  return ErrorCode::OK;
}

◆ PeekBatchBytes()

ErrorCode QueueBase::PeekBatchBytes	(	void *	data,
		size_t	size )

按字节批量查看多个元素但不出队。 Peek multiple elements by bytes without dequeuing them.

Parameters

data	接收查看结果的缓冲区 / Buffer receiving the peeked elements.
size	要查看的元素个数 / Number of elements to peek.

Returns: 成功返回 ErrorCode::OK，元素不足返回 ErrorCode::EMPTY。 Returns ErrorCode::OK on success and ErrorCode::EMPTY when stored elements are insufficient.

Definition at line 165 of file queue_base.cpp.

{
  ASSERT(data != nullptr);
 
  if (Size() < size)
  {
    return ErrorCode::EMPTY;
  }
 
  auto index = head_;
 
  auto tmp = reinterpret_cast<uint8_t*>(data);
 
  size_t first_part = LibXR::min(size, length_ - index);
  LibXR::Memory::FastCopy(tmp, &queue_array_[index * ELEMENT_SIZE],
                          first_part * ELEMENT_SIZE);
 
  if (first_part < size)
  {
    LibXR::Memory::FastCopy(&tmp[first_part * ELEMENT_SIZE], queue_array_,
                            (size - first_part) * ELEMENT_SIZE);
  }
 
  return ErrorCode::OK;
}

◆ PeekBytes()

ErrorCode QueueBase::PeekBytes ( void * data )

按字节查看队头元素但不出队。 Peek the front element by bytes without dequeuing it.

Parameters

data	接收队头元素的缓冲区 / Buffer receiving the front element.

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

Definition at line 56 of file queue_base.cpp.

{
  ASSERT(data != nullptr);
 
  if (Size() > 0)
  {
    LibXR::Memory::FastCopy(data, &queue_array_[head_ * ELEMENT_SIZE], ELEMENT_SIZE);
    return ErrorCode::OK;
  }
  else
  {
    return ErrorCode::EMPTY;
  }
}

◆ PopBatchBytes()

ErrorCode QueueBase::PopBatchBytes	(	void *	data,
		size_t	size )

按字节批量出队多个元素 / Dequeue multiple elements by bytes.

Parameters

data	接收出队元素的缓冲区；传 `nullptr` 时仅丢弃。 Buffer receiving dequeued elements; pass `nullptr` to discard only.
size	要出队的元素个数 / Number of elements to dequeue.

Returns: 成功返回 ErrorCode::OK，元素不足返回 ErrorCode::EMPTY。 Returns ErrorCode::OK on success and ErrorCode::EMPTY when stored elements are insufficient.

Definition at line 135 of file queue_base.cpp.

{
  if (Size() < size)
  {
    return ErrorCode::EMPTY;
  }
 
  if (size == 0)
  {
    return ErrorCode::OK;
  }
  is_full_ = false;
 
  size_t first_part = LibXR::min(size, length_ - head_);
  if (data != nullptr)
  {
    auto tmp = reinterpret_cast<uint8_t*>(data);
    LibXR::Memory::FastCopy(tmp, &queue_array_[head_ * ELEMENT_SIZE],
                            first_part * ELEMENT_SIZE);
    if (size > first_part)
    {
      LibXR::Memory::FastCopy(&tmp[first_part * ELEMENT_SIZE], queue_array_,
                              (size - first_part) * ELEMENT_SIZE);
    }
  }
 
  head_ = (head_ + size) % length_;
  return ErrorCode::OK;
}

◆ PopBytes()

ErrorCode QueueBase::PopBytes ( void * data = nullptr )

按字节出队一个元素；传空指针时仅丢弃队头。 Dequeue one element by bytes; pass null to discard the front item only.

Parameters

data	接收出队元素的缓冲区；传 `nullptr` 时仅丢弃。 Buffer receiving the dequeued element; pass `nullptr` to discard only.

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

Definition at line 71 of file queue_base.cpp.

{
  if (Size() == 0)
  {
    return ErrorCode::EMPTY;
  }
 
  if (data != nullptr)
  {
    LibXR::Memory::FastCopy(data, &queue_array_[head_ * ELEMENT_SIZE], ELEMENT_SIZE);
  }
  head_ = (head_ + 1) % length_;
  is_full_ = false;
  return ErrorCode::OK;
}

◆ PushBatchBytes()

ErrorCode QueueBase::PushBatchBytes	(	const void *	data,
		size_t	size )

按字节批量入队多个元素 / Enqueue multiple elements by bytes.

Parameters

data	指向元素数组的缓冲区 / Buffer pointing to the element array.
size	要入队的元素个数 / Number of elements to enqueue.

Returns: 成功返回 ErrorCode::OK，空间不足返回 ErrorCode::FULL。 Returns ErrorCode::OK on success and ErrorCode::FULL when free space is insufficient.

Definition at line 105 of file queue_base.cpp.

{
  ASSERT(data != nullptr);
 
  auto avail = EmptySize();
  if (avail < size)
  {
    return ErrorCode::FULL;
  }
 
  auto tmp = reinterpret_cast<const uint8_t*>(data);
 
  size_t first_part = LibXR::min(size, length_ - tail_);
  LibXR::Memory::FastCopy(&queue_array_[tail_ * ELEMENT_SIZE], tmp,
                          first_part * ELEMENT_SIZE);
 
  if (size > first_part)
  {
    LibXR::Memory::FastCopy(queue_array_, &tmp[first_part * ELEMENT_SIZE],
                            (size - first_part) * ELEMENT_SIZE);
  }
 
  tail_ = (tail_ + size) % length_;
  if (head_ == tail_)
  {
    is_full_ = true;
  }
  return ErrorCode::OK;
}

◆ PushBytes()

ErrorCode QueueBase::PushBytes ( const void * data )

按字节入队一个元素 / Enqueue one element by bytes.

Parameters

data	指向待入队元素的指针 / Pointer to the element to enqueue.

Returns: 成功返回 ErrorCode::OK，队列满返回 ErrorCode::FULL。 Returns ErrorCode::OK on success and ErrorCode::FULL when the queue is full.

Definition at line 36 of file queue_base.cpp.

{
  ASSERT(data != nullptr);
 
  if (is_full_)
  {
    return ErrorCode::FULL;
  }
 
  LibXR::Memory::FastCopy(&queue_array_[tail_ * ELEMENT_SIZE], data, ELEMENT_SIZE);
 
  tail_ = (tail_ + 1) % length_;
  if (head_ == tail_)
  {
    is_full_ = true;
  }
 
  return ErrorCode::OK;
}

◆ Reset()

void QueueBase::Reset ( )

重置队列状态 / Reset the queue state.

Definition at line 209 of file queue_base.cpp.

{
  head_ = tail_ = 0;
  is_full_ = false;
}

◆ Size()

size_t QueueBase::Size ( ) const

nodiscard

获取当前已存储元素个数 / Get the current stored element count.

Returns: 当前已存储元素个数 / Current number of stored elements.

Definition at line 215 of file queue_base.cpp.

{
  if (is_full_)
  {
    return length_;
  }
  else if (tail_ >= head_)
  {
    return tail_ - head_;
  }
  else
  {
    return length_ + tail_ - head_;
  }
}

Member Data Documentation

◆ ELEMENT_SIZE

const uint16_t LibXR::QueueBase::ELEMENT_SIZE

单个元素的字节数 / Byte size of one element.

Definition at line 179 of file queue_base.hpp.

◆ head_

size_t LibXR::QueueBase::head_ = 0

当前队头物理槽位下标 / Physical slot index of the current head.

Definition at line 180 of file queue_base.hpp.

◆ is_full_

bool LibXR::QueueBase::is_full_ = false

当前队列是否已满 / Whether the queue is currently full.

Definition at line 183 of file queue_base.hpp.

◆ length_

size_t LibXR::QueueBase::length_

队列最大容量 / Maximum queue capacity.

Definition at line 184 of file queue_base.hpp.

◆ own_buffer_

bool LibXR::QueueBase::own_buffer_

Initial value:

=

false

是否由当前队列拥有缓冲区 / Whether this queue owns the buffer.

Definition at line 185 of file queue_base.hpp.

◆ queue_array_

uint8_t* LibXR::QueueBase::queue_array_

队列数据缓冲区 / Queue data buffer.

Definition at line 178 of file queue_base.hpp.

◆ tail_

size_t LibXR::QueueBase::tail_ = 0

下一个待写入物理槽位下标 / Physical slot index of the next enqueue position.

Definition at line 181 of file queue_base.hpp.

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

src/structure/queue/queue_base.hpp
src/structure/queue/queue_base.cpp

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ QueueBase() [1/2]

◆ QueueBase() [2/2]

◆ ~QueueBase()

Member Function Documentation

◆ EmptySize()

◆ GetFirstElementIndex()

◆ GetLastElementIndex()

◆ MaxSize()

◆ operator[]()

◆ OverwriteBytes()

◆ PeekBatchBytes()

◆ PeekBytes()

◆ PopBatchBytes()

◆ PopBytes()

◆ PushBatchBytes()

◆ PushBytes()

◆ Reset()

◆ Size()

Member Data Documentation

◆ ELEMENT_SIZE

◆ head_

◆ is_full_

◆ length_

◆ own_buffer_

◆ queue_array_

◆ tail_