提供固定大小循环缓冲区的字节 FIFO 队列。 More...

#include <queue_base.hpp>

Inheritance diagram for LibXR::QueueBase:

Public Member Functions
	QueueBase (uint16_t element_size, size_t length, uint8_t *buffer)
	使用外部缓冲区构造队列。

	QueueBase (uint16_t element_size, size_t length)
	由队列内部申请缓冲区并构造队列。

	~QueueBase ()
	析构队列。

void *	operator[] (uint32_t index)
	访问指定物理槽位的原始元素地址。

ErrorCode	PushBytes (const void *data)
	按字节入队一个元素。

ErrorCode	PeekBytes (void *data)
	按字节查看队头元素但不出队。

ErrorCode	PopBytes (void *data=nullptr)
	按字节出队一个元素；传空指针时仅丢弃队头。

int	GetLastElementIndex () const
	获取当前最后一个已入队元素的物理槽位下标。

int	GetFirstElementIndex () const
	获取当前第一个已入队元素的物理槽位下标。

ErrorCode	PushBatchBytes (const void *data, size_t size)
	按字节批量入队多个元素。

ErrorCode	PopBatchBytes (void *data, size_t size)
	按字节批量出队多个元素。

ErrorCode	PeekBatchBytes (void *data, size_t size)
	按字节批量查看多个元素但不出队。

ErrorCode	OverwriteBytes (const void *data)
	清空当前状态后，用一个新元素覆盖队列内容。

void	Reset ()
	重置队列状态。

size_t	Size () const
	获取当前已存储元素个数。

size_t	EmptySize () const
	获取当前剩余空槽数。

size_t	MaxSize () const
	获取队列最大容量。

Data Fields
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
	下一个待写入物理槽位下标。 Physical slot index of the next enqueue position.

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

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

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

Private Member Functions
	QueueBase (const QueueBase &)
	禁止拷贝构造。 Non-copyable.

QueueBase &	operator= (const QueueBase &)
	禁止拷贝赋值。 Non-copy-assignable.

QueueBase &	operator= (QueueBase &)
	禁止同类型左值赋值重载。 Non-copy-assignable overload for non-const lvalues.

QueueBase &	operator= (const QueueBase &&)
	禁止移动赋值（const rvalue 形式）。 Non-move-assignable (const rvalue form).

QueueBase &	operator= (QueueBase &&)
	禁止移动赋值。 Non-move-assignable.

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

获取当前已存储元素个数。

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_;
  }
}

Field 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 182 of file queue_base.hpp.

◆ length_

size_t LibXR::QueueBase::length_

队列最大容量。 Maximum queue capacity.

Definition at line 183 of file queue_base.hpp.

◆ own_buffer_

bool LibXR::QueueBase::own_buffer_ = false

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

Definition at line 184 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

Data Fields

Private Member Functions

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()

Field Documentation

◆ ELEMENT_SIZE

◆ head_

◆ is_full_

◆ length_

◆ own_buffer_

◆ queue_array_

◆ tail_