LibXR::WritePort::Stream Class Reference

合并多次写入的流接口 / Stream interface for batched writes. More...

#include <write_port.hpp>

Public Member Functions
	Stream (WritePort *port, WriteOperation op)
	构造流并尝试取得写入权 / Construct a stream and try to acquire the port.
	~Stream ()
	提交剩余批次并结束流 / Submit the remaining batch and destroy the stream.
	Stream (const Stream &)=delete
Stream &	operator= (const Stream &)=delete
	Stream (Stream &&)=delete
Stream &	operator= (Stream &&)=delete
ErrorCode	Write (ConstRawData data)
	向当前批次追加数据 / Append data to the current batch.
ErrorCode	Write (std::string_view text)
	向当前批次追加文本 / Append text to the current batch.
Stream &	operator<< (const ConstRawData &data)
	尝试追加数据并返回流引用 / Try to append data and return the stream.
ErrorCode	Commit ()
	提交批次并释放写入权 / Submit the batch and release producer access.
ErrorCode	Acquire ()
	尝试取得端口写入权 / Try to acquire the port's producer access.
size_t	EmptySize () const
	获取当前批次可追加的空间 / Get current free space for appending.

Detailed Description

合并多次写入的流接口 / Stream interface for batched writes.

取得写入权后，各次 Write 直接复制到端口队列；Commit 或析构提交整个批次。 普通后端在提交后才可消费本批次，Pipe 读端可在提交前读到已追加的字节。 Once acquired, each Write copies into the port queue. Commit or destruction submits the batch. Queued backends consume it only after submission; Pipe readers may consume appended bytes before submission.

Precondition

仅在线程中使用。同一 Stream 的成员调用及析构不得并发或重入；BLOCK 与 非 BLOCK 的混用限制同 WritePort。持有写入权期间端口和后端须保持有效。 Task-only. Calls and destruction on one Stream must not overlap or reenter. WritePort's BLOCK/non-BLOCK rules apply. Keep the port and backend alive while the Stream owns producer access, including between member calls.

Note

提交后可再次 Acquire 或 Write 开始新批次；各批次沿用构造时的通知对象， 调用者须保证它在相关操作结束前有效。所有通知使用 in_isr = false。 After submission, Acquire or Write can start a new batch using the same completion targets; keep them valid through the related operations. Notifications use in_isr = false.

Definition at line 294 of file write_port.hpp.

Constructor & Destructor Documentation

Stream()

WritePort::Stream::Stream	(	WritePort *	port,
		WriteOperation	op )

构造流并尝试取得写入权 / Construct a stream and try to acquire the port.

Parameters

port	目标写端口 / Target write port.
op	每个批次使用的完成通知描述符 / Completion descriptor used for each batch.

Note

构造不报告 Acquire 失败；可显式调用 Acquire 检查或重试。 Construction hides acquisition failure; call Acquire to check or retry.

Definition at line 5 of file write_stream.cpp.

                                                          : port_(port), op_(op)
{
  UNUSED(Acquire());
}

~Stream()

WritePort::Stream::~Stream

(

)

提交剩余批次并结束流 / Submit the remaining batch and destroy the stream.

Note

持有写入权时行为同 Commit，包括空批次通知和 BLOCK 等待，但无法返回结果。 尚未取得写入权时不执行操作。 While owning the port, behaves like Commit, including empty completion and BLOCK waits, but discards the result. Does nothing without ownership.

Definition at line 10 of file write_stream.cpp.

{
  if (!owns_port_)
  {
    return;
  }
 
  if (buffered_size_ != 0U)
  {
    UNUSED(SubmitBuffered());
    return;
  }
 
  Release();
  CompleteEmpty();
}

Member Function Documentation

Acquire()

ErrorCode WritePort::Stream::Acquire ( )

nodiscard

尝试取得端口写入权 / Try to acquire the port's producer access.

Returns

成功或已持有返回 OK；端口为空返回 PTR_NULL，不支持写入返回 NOT_SUPPORT， 生产者状态被占用返回 BUSY，请求队列无空位返回 FULL。 OK when acquired or already owned; PTR_NULL for a null port, NOT_SUPPORT when unavailable, BUSY for an occupied phase, FULL for no request slot.

Note

取得后保持独占，直到 Commit 或析构。只检查请求槽，不预留字节空间； 不等待旧超时 BLOCK 请求退出，即使本 Stream 使用 BLOCK 也立即返回。 Holds exclusive access until Commit or destruction. Checks a request slot without reserving byte capacity. Never waits for detached BLOCK retirement, even when this Stream uses a BLOCK operation.

Definition at line 27 of file write_stream.cpp.

{
  if (owns_port_)
  {
    return ErrorCode::OK;
  }
  if (port_ == nullptr)
  {
    return ErrorCode::PTR_NULL;
  }
  if (!port_->Writable())
  {
    return ErrorCode::NOT_SUPPORT;
  }
  if (!port_->TryClaimProducer())
  {
    return ErrorCode::BUSY;
  }
 
  if (!port_->IsAdmissionMode() && port_->queue_requests_->EmptySize() < 1U)
  {
    port_->ReleaseProducer(WritePort::Phase::IDLE, false);
    return ErrorCode::FULL;
  }
 
  owns_port_ = true;
  return ErrorCode::OK;
}

Commit()

ErrorCode WritePort::Stream::Commit ( )

nodiscard

提交批次并释放写入权 / Submit the batch and release producer access.

Returns

非 BLOCK 提交返回 OK；普通后端的 BLOCK 返回完成结果或 TIMEOUT。 Pipe 入队后返回 OK。未持有写入权时返回 OK，不执行操作。 Non-BLOCK submission returns OK; queued BLOCK returns completion or TIMEOUT. Pipe returns OK on admission. Without ownership, returns OK without taking action.

Note

空批次先释放写入权，再完成非 BLOCK 通知；不通知后端，BLOCK 不等待。 非空批次的完成与超时语义同 WritePort::operator()，可能同步调用用户回调。 An empty batch releases ownership before non-BLOCK completion; it does not notify the backend or wait for BLOCK. Nonempty batches follow WritePort::operator() rules and may invoke callbacks inline.

Definition at line 128 of file write_stream.cpp.

{
  if (!owns_port_)
  {
    return ErrorCode::OK;
  }
  if (buffered_size_ != 0U)
  {
    return SubmitBuffered();
  }
 
  Release();
  CompleteEmpty();
  return ErrorCode::OK;
}

EmptySize()

size_t LibXR::WritePort::Stream::EmptySize ( ) const

inlinenodiscard

获取当前批次可追加的空间 / Get current free space for appending.

Returns

持有写入权时返回字节队列当前空闲量，否则为零。 Current free bytes while owning the port, or zero otherwise.

Note

查询不预留空间；后端或 Pipe 读端消费数据后可释放更多空间。 Reserves no space; backend or Pipe reader consumption can free more capacity.

Definition at line 391 of file write_port.hpp.

    {
      return owns_port_ && port_ != nullptr && port_->queue_data_ != nullptr
                 ? port_->queue_data_->EmptySize()
                 : 0U;
    }

operator<<()

WritePort::Stream & WritePort::Stream::operator<<

(

const ConstRawData &

data

)

尝试追加数据并返回流引用 / Try to append data and return the stream.

Parameters

data	待追加的数据 / Data to append.

Returns

当前流，可用于连续追加 / This stream for chained appends.

Note

取得写入权失败或空间不足时不追加，也不报告错误；需要结果时使用 Write。 Skips the input without reporting acquisition or capacity failures; use Write when the result is needed.

Definition at line 119 of file write_stream.cpp.

{
  if (Acquire() == ErrorCode::OK && EmptySize() >= data.size_)
  {
    UNUSED(Write(data));
  }
  return *this;
}

Write() [1/2]

ErrorCode WritePort::Stream::Write ( ConstRawData data )

nodiscard

向当前批次追加数据 / Append data to the current batch.

Parameters

data	数据源和字节数；正长度时地址须有效，返回后即可复用源缓冲区。 Source and byte count; a positive size requires a valid address. The source buffer may be reused after return.

Returns

全部追加返回 OK；空间不足返回 FULL，本次不部分追加，保留已有批次。 无可用端口返回 NOT_SUPPORT；需要取得写入权时也可能返回 BUSY 或 FULL。 OK if fully appended; FULL leaves this input unwritten and prior appends intact. NOT_SUPPORT without a usable port; Acquire may return BUSY or FULL.

Note

必要时先 Acquire。零长度在能力检查后直接返回 OK，不取得写入权或完成操作。 Acquires if needed. Zero size returns OK after the capability check without acquiring producer access or completing an operation.

Definition at line 56 of file write_stream.cpp.

{
  if (port_ == nullptr || !port_->Writable())
  {
    return ErrorCode::NOT_SUPPORT;
  }
 
  if (data.size_ == 0U)
  {
    return ErrorCode::OK;
  }
 
  const ErrorCode acquire_result = Acquire();
  if (acquire_result != ErrorCode::OK)
  {
    return acquire_result;
  }
 
  ASSERT(data.addr_ != nullptr);
 
  if (port_->queue_data_ == nullptr || port_->queue_data_->EmptySize() < data.size_)
  {
    return ErrorCode::FULL;
  }
 
  [[maybe_unused]] const ErrorCode result = port_->queue_data_->PushBatch(
      reinterpret_cast<const uint8_t*>(data.addr_), data.size_);
  DEV_ASSERT(result == ErrorCode::OK);
  buffered_size_ += data.size_;
  return ErrorCode::OK;
}

Write() [2/2]

ErrorCode LibXR::WritePort::Stream::Write ( std::string_view text )

inlinenodiscard

向当前批次追加文本 / Append text to the current batch.

Parameters

text	待复制的文本，不附加结束符 / Text to copy without an added terminator.

Returns

同 Write(ConstRawData) / Same results as Write(ConstRawData).

Definition at line 340 of file write_port.hpp.

    {
      return Write(ConstRawData{text.data(), text.size()});
    }

---

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

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