LibXR::WritePort::WriteQueue Class Reference

已提交队头的出队接口 / Consumer interface for one released front. More...

#include <write_port.hpp>

Public Member Functions
	WriteQueue (const WriteQueue &)=delete
WriteQueue &	operator= (const WriteQueue &)=delete
	WriteQueue (WriteQueue &&)=delete
WriteQueue &	operator= (WriteQueue &&)=delete
	~WriteQueue () noexcept
	结算出队，使用获取时的上下文 / Settle progress using the captured context.
size_t	AvailableSize () const
	获取当前队头的剩余长度 / Get the current front remainder.
bool	Empty () const
	检查本接口是否还有数据 / Check whether this interface has remaining data.
void	PopAll (uint8_t *destination)
	复制并取走队头剩余数据 / Copy and consume the entire front remainder.
template<typename Writer >
size_t	PopWithWriter (size_t limit, Writer &&writer)
	通过回调取走队头前缀 / Consume a front prefix through a callback.
void	FailFront (ErrorCode reason)
	丢弃剩余数据并结束队头 / Discard the remainder and fail the front.

Friends
class	WritePort

Detailed Description

已提交队头的出队接口 / Consumer interface for one released front.

每个对象只对应一个请求的剩余部分，最多调用一次 PopAll、PopWithWriter 或 FailFront。 析构时记录本次进展；整个请求结束后才移除请求并发送完成通知。继续处理须重新获取接口。 Each object covers one request remainder and permits at most one PopAll, PopWithWriter, or FailFront call. Destruction accounts progress and retires and completes the request only when its entire remainder is consumed. Obtain a new interface for further progress.

Precondition

后端须串行化从获取接口到析构及完成回调返回的全过程，不可嵌套出队。 The backend serializes acquisition through destruction and completion callbacks; consumer scopes must not overlap or nest.

Note

接收的数据须在出队方法返回前进入后端可持续持有的存储。析构可能同步执行 用户回调；后端须保留并再次处理回调中新增写入的通知。 Accepted bytes must reach stable backend storage before the consuming method returns. Destruction may invoke user callbacks inline; the backend must retain and recheck progress notifications from callback-generated writes.

Definition at line 153 of file write_port.hpp.

Constructor & Destructor Documentation

~WriteQueue()

WritePort::WriteQueue::~WriteQueue ( )

noexcept

结算出队，使用获取时的上下文 / Settle progress using the captured context.

Definition at line 196 of file write_port.cpp.

{
  port_.SettleWriteQueue(popped_size_, settlement_result_, in_isr_);
}

Member Function Documentation

AvailableSize()

size_t LibXR::WritePort::WriteQueue::AvailableSize ( ) const

inlinenodiscard

获取当前队头的剩余长度 / Get the current front remainder.

Returns

剩余字节数，不含后续请求 / Remaining bytes, excluding later requests.

Definition at line 167 of file write_port.hpp.

    {
      DEV_ASSERT_FROM_CALLBACK(popped_size_ <= front_size_, in_isr_);
      return front_size_ - popped_size_;
    }

Empty()

bool LibXR::WritePort::WriteQueue::Empty ( ) const

inlinenodiscard

检查本接口是否还有数据 / Check whether this interface has remaining data.

Returns

当前剩余长度为零时返回 true，不代表整个端口队列为空。 True for a zero remainder; does not describe the entire port queue.

Definition at line 178 of file write_port.hpp.

{ return AvailableSize() == 0U; }

FailFront()

void WritePort::WriteQueue::FailFront

(

ErrorCode

reason

)

丢弃剩余数据并结束队头 / Discard the remainder and fail the front.

Parameters

reason

请求的完成错误，不可为 OK / Completion error, which must not be OK.

Precondition

队头非空，本接口尚未执行出队操作；后端已确认该请求无法安全继续或重发。 A nonempty front and no previous action; the backend has established that this request cannot safely continue or be replayed.

Note

用于部分传输后发生不可恢复错误的请求。后续请求保留，析构时完成当前请求。 Applies to unrecoverable partial transfers. Later requests remain queued; the current request completes on destruction.

Definition at line 174 of file write_port.cpp.

{
  BeginAction();
  ASSERT_FROM_CALLBACK(reason != ErrorCode::OK, in_isr_);
  DEV_ASSERT_FROM_CALLBACK(front_size_ != 0U, in_isr_);
 
  const size_t remaining = AvailableSize();
  DEV_ASSERT_FROM_CALLBACK(remaining != 0U, in_isr_);
  const size_t accepted = port_.queue_data_->ConsumeWithReader(
      remaining,
      [](const uint8_t* first, size_t first_size, const uint8_t* second,
         size_t second_size) -> size_t
      {
        UNUSED(first);
        UNUSED(second);
        return first_size + second_size;
      });
  DEV_ASSERT_FROM_CALLBACK(accepted == remaining, in_isr_);
  popped_size_ += accepted;
  settlement_result_ = reason;
}

PopAll()

void WritePort::WriteQueue::PopAll

(

uint8_t *

destination

)

复制并取走队头剩余数据 / Copy and consume the entire front remainder.

Parameters

destination

后端接收地址，至少容纳 AvailableSize() 字节。 Backend destination with room for at least AvailableSize() bytes.

Precondition

当前队头非空，地址有效，本接口尚未执行出队操作。 A nonempty front, valid destination, and no previous action are required.

Note

返回时字节已出队；请求在本接口析构时完成。参数和队列一致性由后端保证。 Bytes leave the queue before return; request completion occurs at interface destruction. Arguments and queue consistency are backend invariants.

Definition at line 145 of file write_port.cpp.

{
  BeginAction();
  const size_t remaining = AvailableSize();
  DEV_ASSERT_FROM_CALLBACK(remaining != 0U, in_isr_);
  DEV_ASSERT_FROM_CALLBACK(destination != nullptr, in_isr_);
 
  size_t offset = 0U;
  const size_t accepted = port_.queue_data_->ConsumeWithReader(
      remaining,
      [destination, &offset](const uint8_t* first, size_t first_size,
                             const uint8_t* second, size_t second_size) -> size_t
      {
        if (first_size != 0U)
        {
          std::memcpy(destination + offset, first, first_size);
          offset += first_size;
        }
        if (second_size != 0U)
        {
          std::memcpy(destination + offset, second, second_size);
          offset += second_size;
        }
        return first_size + second_size;
      });
  DEV_ASSERT_FROM_CALLBACK(accepted == remaining, in_isr_);
  popped_size_ += accepted;
}

PopWithWriter()

template<typename Writer >

size_t LibXR::WritePort::WriteQueue::PopWithWriter ( size_t limit, Writer && writer )

inline

通过回调取走队头前缀 / Consume a front prefix through a callback.

Template Parameters

Writer

后端接收函数类型 / Backend writer callback type.

Parameters

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

Returns

实际出队字节数；零表示本次无进展，保留原队头。 Bytes actually consumed; zero leaves the front unchanged.

Precondition

队头非空，本接口尚未执行出队操作；回调不可重入出队路径，返回值不得超过 提供的字节数。只有已复制或转移到稳定后端存储的字节才可计为接收。 Requires a nonempty front and no previous action. The callback must not reenter consumption on this port or return more than offered. Count only bytes copied or transferred to stable backend storage.

Note

提供长度不超过 limit 和当前队头剩余长度。非空时调用一次回调，数据指针 仅在回调内有效。部分出队不完成请求；暂时无法接收时由后端安排后续推进。 The offer is bounded by limit and the front remainder. The callback runs once for a positive offer; pointers expire on return. Partial consumption does not complete the request; the backend arranges later progress.

Definition at line 214 of file write_port.hpp.

    {
      BeginAction();
      const size_t offered = std::min(limit, AvailableSize());
      if (offered == 0U)
      {
        return 0U;
      }
 
      const size_t accepted = port_.queue_data_->ConsumeWithReader(
          offered,
          [&](const uint8_t* first, size_t first_size, const uint8_t* second,
              size_t second_size) -> size_t
          {
            const size_t accepted = writer(first, first_size, second, second_size);
            ASSERT_FROM_CALLBACK(accepted <= first_size + second_size, in_isr_);
            return accepted;
          });
      popped_size_ += accepted;
      return accepted;
    }

Friends And Related Symbol Documentation

WritePort

friend class WritePort

friend

Definition at line 249 of file write_port.hpp.

---

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

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