LibXR::STDIO Class Reference

提供静态全局的输入输出接口绑定与写会话管理 / STDIO interface for read and write ports More...

#include <stdio.hpp>

Collaboration diagram for LibXR::STDIO:

Data Structures
struct	CompiledCall
	一次编译格式 STDIO 调用的模板上下文 / Template context for one compiled-format STDIO call More...
class	CompiledSink
	STDIO 编译格式会话使用的流式截断输出端 / Stream-backed truncating sink used by one STDIO compiled-format session. More...

Static Public Member Functions
template<Print::Text Source, typename... Args>
static int	Print (Args &&... args)
	将一个编译期 brace 字面量打印到当前 STDIO 输出 / Print one compile-time brace literal to the active STDIO output
template<Print::Text Source, typename... Args>
static int	Printf (Args &&... args)
	将一个编译期 printf 字面量打印到当前 STDIO 输出 / Print one compile-time printf literal to the active STDIO output

Static Public Attributes
static ReadPort *	read_ = nullptr
	Read port instance. 读取端口。
static WritePort *	write_ = nullptr
	Write port instance. 写入端口。
static LibXR::Mutex *	write_mutex_
	Write port mutex. 写入端口互斥锁。
static LibXR::WritePort::Stream *	write_stream_
	Optional externally owned write stream. 可选的外部托管写流。

Private Types
using	CompiledWriteFun = ErrorCode (*)(void* context, CompiledSink& sink)

Static Private Member Functions
static int	WriteCompiledToStream (WritePort::Stream &stream, void *context, CompiledWriteFun write_fun)
	在指定 Stream 上执行一次完整的 STDIO 编译格式写入与收尾 / Run one complete STDIO compiled-format write and finalize pass on the given Stream
static int	WriteCompiledSession (void *context, CompiledWriteFun write_fun)
	执行一次完整的 STDIO 编译格式流会话选择、写入与收尾 / Run one complete STDIO compiled-format stream session: stream selection, write, and finalization
template<typename Call >
static int	RunCompiledSession (Call &call)
	执行一次模板已知的 STDIO 编译格式会话 / Run one STDIO compiled-format session whose format and argument types are already known at compile time
template<typename CompiledFormat , typename... Args>
static int	RunCompiled (const CompiledFormat &format, Args &&... args)
	用一份已编译格式和一组运行时参数执行一次完整的 STDIO 写会话 / Run one complete STDIO write session with one compiled format and one runtime argument pack
static bool	BeginWriteSession ()
	获取一个共享的 STDIO 写入会话 / Acquire one shared STDIO write session
static int	FinishWriteSession (WritePort::Stream &stream, size_t retained_size, ErrorCode format_result)
	提交当前编译格式会话的写入流并释放共享会话 / Commit the current compiled-format session stream and release the shared session

Detailed Description

提供静态全局的输入输出接口绑定与写会话管理 / STDIO interface for read and write ports

Definition at line 19 of file stdio.hpp.

Member Typedef Documentation

CompiledWriteFun

using LibXR::STDIO::CompiledWriteFun = ErrorCode (*)(void* context, CompiledSink& sink)

private

Definition at line 70 of file stdio.hpp.

Member Function Documentation

BeginWriteSession()

bool STDIO::BeginWriteSession ( )

staticnodiscardprivate

获取一个共享的 STDIO 写入会话 / Acquire one shared STDIO write session

Returns

成功获取共享写会话返回 true，否则返回 false / Returns true on success, otherwise false

Definition at line 51 of file stdio.cpp.

{
  if (!STDIO::write_ || !STDIO::write_->Writable())
  {
    return false;
  }
 
  if (!write_mutex_)
  {
    write_mutex_ = new LibXR::Mutex();
  }
 
  return write_mutex_->Lock() == ErrorCode::OK;
}

FinishWriteSession()

int STDIO::FinishWriteSession ( WritePort::Stream & stream, size_t retained_size, ErrorCode format_result )

staticnodiscardprivate

提交当前编译格式会话的写入流并释放共享会话 / Commit the current compiled-format session stream and release the shared session

Parameters

stream	当前会话使用的写入流 / Write stream used by the current session
retained_size	当前会话真正保留下来的字节数 / Byte count actually retained by the current session
format_result	本次格式化写出阶段的状态 / Status returned by the formatting write phase

Returns

当前 STDIO 会话最终提交的字节数；失败返回 -1 / Byte count finally committed by the current STDIO session; returns -1 on failure

Definition at line 89 of file stdio.cpp.

{
  ASSERT(write_mutex_ != nullptr);
 
  // Stream-backed STDIO is now explicitly prefix-preserving on formatting
  // failure: any bytes already retained in this session are committed instead
  // of being pseudo-rolled-back.
  // 基于 Stream 的 STDIO 现在明确采用“前缀保留”语义：格式化失败时，
  // 本会话已保留的字节仍然提交，不再尝试伪回滚。
  auto ec = stream.Commit();
 
  write_mutex_->Unlock();
 
  if (format_result != ErrorCode::OK || ec != ErrorCode::OK ||
      retained_size > static_cast<size_t>(std::numeric_limits<int>::max()))
  {
    return -1;
  }
 
  return static_cast<int>(retained_size);
}

Print()

template<Print::Text Source, typename... Args>

static int LibXR::STDIO::Print ( Args &&... args )

inlinestatic

将一个编译期 brace 字面量打印到当前 STDIO 输出 / Print one compile-time brace literal to the active STDIO output

Template Parameters

Source	编译期 brace 格式字面量 / Compile-time brace format literal
Args	调用点运行时参数类型列表 / Call-site runtime argument types

Parameters

args	参与本次打印的运行时参数 / Runtime arguments used by the current print

Returns

返回当前 STDIO 流实际保留并提交的字节数；若会话建立或提交失败则返回 -1 / Returns the byte count actually retained and committed to the current STDIO stream; returns -1 on session or commit failure

Definition at line 196 of file stdio.hpp.

  {
    constexpr LibXR::Format<Source> format{};
    return RunCompiled(format, std::forward<Args>(args)...);
  }

Printf()

template<Print::Text Source, typename... Args>

static int LibXR::STDIO::Printf ( Args &&... args )

inlinestatic

将一个编译期 printf 字面量打印到当前 STDIO 输出 / Print one compile-time printf literal to the active STDIO output

Template Parameters

Source	编译期 printf 格式字面量 / Compile-time printf format literal
Args	调用点运行时参数类型列表 / Call-site runtime argument types

Parameters

args	参与本次打印的运行时参数 / Runtime arguments used by the current print

Returns

返回当前 STDIO 流实际保留并提交的字节数；若会话建立或提交失败则返回 -1 / Returns the byte count actually retained and committed to the current STDIO stream; returns -1 on session or commit failure

Definition at line 210 of file stdio.hpp.

  {
    constexpr auto format = Print::Printf::Build<Source>();
    return RunCompiled(format, std::forward<Args>(args)...);
  }

RunCompiled()

template<typename CompiledFormat , typename... Args>

static int LibXR::STDIO::RunCompiled ( const CompiledFormat & format, Args &&... args )

inlinestaticnodiscardprivate

用一份已编译格式和一组运行时参数执行一次完整的 STDIO 写会话 / Run one complete STDIO write session with one compiled format and one runtime argument pack

Template Parameters

CompiledFormat	编译后的格式类型 / Compiled format type
Args	运行时参数类型列表 / Runtime argument types

Parameters

format	编译后的格式对象 / Compiled format object
args	参与本次写会话的运行时参数 / Runtime arguments used by the current write session

Returns

当前 STDIO 会话最终提交的字节数；失败返回 -1 / Byte count finally committed by the current STDIO session; returns -1 on failure

Definition at line 162 of file stdio.hpp.

  {
    CompiledCall<CompiledFormat, Args...> call{
        format, std::forward_as_tuple(std::forward<Args>(args)...)};
    return RunCompiledSession(call);
  }

RunCompiledSession()

template<typename Call >

static int LibXR::STDIO::RunCompiledSession ( Call & call )

inlinestaticnodiscardprivate

执行一次模板已知的 STDIO 编译格式会话 / Run one STDIO compiled-format session whose format and argument types are already known at compile time

该 helper 只保留模板相关的最薄一层：拿共享会话，再把类型化调用对象交给 WriteCompiledSession()。 This helper keeps only the thinnest template layer: acquire the shared session, then pass the typed call object into WriteCompiledSession().

Template Parameters

Call	类型化编译格式调用对象 / Typed compiled-format call object

Parameters

call	当前会话的类型化调用对象 / Typed call object for the current session

Returns

当前 STDIO 会话最终提交的字节数；失败返回 -1 / Byte count finally committed by the current STDIO session; returns -1 on failure

Definition at line 143 of file stdio.hpp.

  {
    if (!BeginWriteSession())
    {
      return -1;
    }
 
    return WriteCompiledSession(&call, &Call::Write);
  }

WriteCompiledSession()

int STDIO::WriteCompiledSession ( void * context, CompiledWriteFun write_fun )

staticnodiscardprivate

执行一次完整的 STDIO 编译格式流会话选择、写入与收尾 / Run one complete STDIO compiled-format stream session: stream selection, write, and finalization

若当前已存在外部绑定的 write_stream_，则复用它；否则创建一个临时的 WritePort::Stream 供本次会话使用。 Reuses the externally bound write_stream_ when available; otherwise creates one temporary WritePort::Stream for the current session.

Parameters

context	前端桥接函数对应的类型擦除上下文 / Type-erased context consumed by the frontend bridge
write_fun	前端桥接写入函数 / Frontend bridge write function

Returns

当前 STDIO 会话最终提交的字节数；失败返回 -1 / Byte count finally committed by the current STDIO session; returns -1 on failure

Definition at line 74 of file stdio.cpp.

{
  ASSERT(write_mutex_ != nullptr);
  ASSERT(write_fun != nullptr);
 
  if (write_stream_ != nullptr)
  {
    return WriteCompiledToStream(*write_stream_, context, write_fun);
  }
 
  static WriteOperation op;  // NOLINT
  WritePort::Stream stream(write_, op);
  return WriteCompiledToStream(stream, context, write_fun);
}

WriteCompiledToStream()

int STDIO::WriteCompiledToStream ( WritePort::Stream & stream, void * context, CompiledWriteFun write_fun )

staticnodiscardprivate

在指定 Stream 上执行一次完整的 STDIO 编译格式写入与收尾 / Run one complete STDIO compiled-format write and finalize pass on the given Stream

该 helper 统一负责：构造 CompiledSink、调用前端桥接函数、再用 FinishWriteSession() 做最终提交或丢弃。 This helper centralizes: constructing CompiledSink, invoking the frontend bridge, then finalizing through FinishWriteSession().

Parameters

stream	本次会话绑定的写入流 / Write stream bound to the current session
context	前端桥接函数对应的类型擦除上下文 / Type-erased context consumed by the frontend bridge
write_fun	前端桥接写入函数 / Frontend bridge write function

Returns

当前 STDIO 会话最终提交的字节数；失败返回 -1 / Byte count finally committed by the current STDIO session; returns -1 on failure

Definition at line 66 of file stdio.cpp.

{
  CompiledSink sink(stream);
  auto ec = write_fun(context, sink);
  return FinishWriteSession(stream, sink.RetainedSize(), ec);
}

Field Documentation

read_

ReadPort* LibXR::STDIO::read_ = nullptr

inlinestatic

Read port instance. 读取端口。

Definition at line 25 of file stdio.hpp.

write_

WritePort* LibXR::STDIO::write_ = nullptr

inlinestatic

Write port instance. 写入端口。

Definition at line 26 of file stdio.hpp.

write_mutex_

LibXR::Mutex* LibXR::STDIO::write_mutex_

inlinestatic

Initial value:

=
      nullptr

Write port mutex. 写入端口互斥锁。

Definition at line 27 of file stdio.hpp.

write_stream_

LibXR::WritePort::Stream* LibXR::STDIO::write_stream_

inlinestatic

Initial value:

=
      nullptr

Optional externally owned write stream. 可选的外部托管写流。

Definition at line 29 of file stdio.hpp.

---

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

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