LibXR::ReadPort::ReadQueue Class Reference

接收队列的短期写入接口 / Short-lived producer interface for the RX queue. More...

#include <read_port.hpp>

Public Member Functions
	ReadQueue (const ReadQueue &)=delete
ReadQueue &	operator= (const ReadQueue &)=delete
	ReadQueue (ReadQueue &&)=delete
ReadQueue &	operator= (ReadQueue &&)=delete
	~ReadQueue ()
	开发期检查是否已 Publish / Check for Publish in development builds.
ErrorCode	PushBatch (const uint8_t *data, size_t size)
	批量复制字节到接收队列 / Copy a batch of bytes into the RX queue.
template<typename Writer >
size_t	PushWithWriter (size_t limit, Writer &&writer)
	通过回调直接写入接收队列 / Fill the RX queue through a writer callback.
size_t	EmptySize () const
	获取接收队列当前空闲空间 / Get current RX queue free space.
size_t	Capacity () const
	获取接收队列容量 / Get the RX queue capacity.
void	Publish ()
	结束本次写入并通知挂起读 / End production and notify a pending read.

Friends
class	ReadPort

Detailed Description

接收队列的短期写入接口 / Short-lived producer interface for the RX queue.

一次使用可多次调用同一种入队方法，最后显式调用一次 Publish，包括未写入数据的情况。 不可复制或移动；析构不会自动发布通知。 Use one production method repeatedly, then call Publish exactly once, even if no bytes were written. This object is noncopyable and nonmovable. Destruction does not publish notifications.

Note

入队即通过 SPSC 发布字节；Publish 推进挂起读，可能同步执行完成回调。 Enqueueing makes bytes visible through the SPSC; Publish drives pending reads and may invoke completion callbacks inline.

Definition at line 107 of file read_port.hpp.

Constructor & Destructor Documentation

~ReadQueue()

ReadPort::ReadQueue::~ReadQueue

(

)

开发期检查是否已 Publish / Check for Publish in development builds.

Definition at line 20 of file read_port.cpp.

{ ASSERT_FROM_CALLBACK(finished_, in_isr_); }

Member Function Documentation

Capacity()

size_t ReadPort::ReadQueue::Capacity ( ) const

nodiscard

获取接收队列容量 / Get the RX queue capacity.

Returns

队列总容量，单位为字节 / Total queue capacity in bytes.

Definition at line 40 of file read_port.cpp.

{ return port_.queue_data_->MaxSize(); }

EmptySize()

size_t ReadPort::ReadQueue::EmptySize ( ) const

nodiscard

获取接收队列当前空闲空间 / Get current RX queue free space.

Returns

空闲字节数；查询不预留空间 / Free bytes; the query reserves no space.

Definition at line 38 of file read_port.cpp.

{ return port_.queue_data_->EmptySize(); }

Publish()

void ReadPort::ReadQueue::Publish

(

)

结束本次写入并通知挂起读 / End production and notify a pending read.

Precondition

每个 ReadQueue 仅调用一次，之后不再使用该写入接口。 Call once per ReadQueue and do not use the producer interface afterward.

Note

未写入字节时只结束本次使用；有数据时使用获取接口时的 in_isr 上下文 推进读请求，可能同步复制数据并调用完成回调。 With no produced bytes, only ends this use. Otherwise drives reads using the captured in_isr context and may copy data and invoke callbacks inline.

Definition at line 42 of file read_port.cpp.

{
  ASSERT_FROM_CALLBACK(!finished_, in_isr_);
  finished_ = true;
  if (dirty_)
  {
    port_.PublishProduced(in_isr_);
  }
}

PushBatch()

ErrorCode ReadPort::ReadQueue::PushBatch ( const uint8_t * data, size_t size )

nodiscard

批量复制字节到接收队列 / Copy a batch of bytes into the RX queue.

Parameters

data	数据源；正长度时不可为空 / Source, non-null for a positive size.
size	字节数 / Number of bytes.

Returns

全部入队返回 OK；空间不足返回 FULL，不部分写入。零长度返回 OK。 OK if all bytes are queued; FULL without partial writes if space is insufficient. A zero size returns OK.

Precondition

尚未调用 Publish / Publish has not been called.

Definition at line 22 of file read_port.cpp.

{
  ASSERT_FROM_CALLBACK(!finished_, in_isr_);
  if (size != 0U)
  {
    ASSERT_FROM_CALLBACK(data != nullptr, in_isr_);
  }
 
  const ErrorCode result = port_.queue_data_->PushBatch(data, size);
  if (result == ErrorCode::OK && size != 0U)
  {
    dirty_ = true;
  }
  return result;
}

PushWithWriter()

template<typename Writer >

size_t LibXR::ReadPort::ReadQueue::PushWithWriter ( size_t limit, Writer && writer )

inlinenodiscard

通过回调直接写入接收队列 / Fill the RX queue through a writer callback.

Template Parameters

Writer

写入器类型 / Writer callback type.

Parameters

limit	最多提供的字节数 / Maximum number of bytes to offer.
writer	签名为 size_t(uint8_t*, size_t, uint8_t*, size_t)，接收按 FIFO 顺序排列的最多两段空间，返回已写入的连续前缀长度。 Callable as size_t(uint8_t*, size_t, uint8_t*, size_t); receives up to two FIFO-ordered spans and returns the length of the written prefix.

Returns

实际入队字节数 / Number of bytes actually queued.

Precondition

尚未 Publish；回调不可重入同一队列的生产操作，返回值不得超过提供的空间。 Before Publish; the callback must not reenter production on this queue or return more bytes than offered.

Note

提供长度不超过 limit 和空闲空间。非空时只调用一次回调，指针仅在回调内有效。 The offer is limited by limit and free space. The callback runs once for a nonempty offer; its pointers are valid only during that call.

Definition at line 145 of file read_port.hpp.

    {
      ASSERT_FROM_CALLBACK(!finished_, in_isr_);
 
      const size_t produced = port_.queue_data_->ProduceWithWriter(
          limit,
          [&](void* first, size_t first_size, void* second, size_t second_size) -> size_t
          {
            const size_t produced = writer(static_cast<uint8_t*>(first), first_size,
                                           static_cast<uint8_t*>(second), second_size);
            ASSERT_FROM_CALLBACK(produced <= first_size + second_size, in_isr_);
            return produced;
          });
      dirty_ = dirty_ || (produced != 0U);
      return produced;
    }

Friends And Related Symbol Documentation

ReadPort

friend class ReadPort

friend

Definition at line 186 of file read_port.hpp.

---

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

• src/core/rw/read_port.hpp
• src/core/rw/read_port.cpp