跳转到内容
标准库Zig 0.17.1官方原文
源码std/Io.zig

第 1 行

抽象所有 I/O 操作与并发的 跨平台接口,包括:

  • 文件系统
  • 网络
  • 进程
  • 时间与休眠
  • 随机性
  • 异步、等待、并发和取消
  • 并发队列
  • 等待组和选择
  • 互斥锁、futex、事件和条件变量
  • 内存映射文件 此接口使程序员在执行这些操作时, 能够编写高效且可复用的代码。

字段

userdata: ?*anyopaque
vtable: *const VTable

std.Io.Alignment

别名

第 23 行

别名目标 std.mem.Alignment

std.Io.Allocator

别名

第 22 行

别名目标 std.mem.Allocator

std.Io.AnyFuture

容器

第 1294 行

std.Io.assert

别名

第 21 行

别名目标 std.debug.assert

std.Io.async

函数

第 2532 行

调用 function,参数为 args,只有调用 await 后才保证能够取得函数返回值。

function 可能在 async 返回前立即调用。其保证比 concurrent 弱,因此更易移植和复用。

此函数返回时,保证 function 要么已经调用并完成,要么已成功分配到一个并发执行单元。

另见:

pub fn async( io: Io, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function)), ) Future(@typeInfo(@TypeOf(function)).@"fn".return_type.?)

参数

io: Io
args: std.meta.ArgsTuple(@TypeOf(function))

std.Io.async.start

函数

第 2540 行

fn start(context: *const anyopaque, result: *anyopaque) void

参数

context: *const anyopaque
result: *anyopaque

std.Io.Batch

容器

第 578 行

一次提交多个操作,无需等待全部操作 完成。

这是基于 Operation 的底层抽象。关于操作 Future 的高层 API,参见 Select 和 Group。

字段

storage: []Operation.Storage
unused: Operation.List
submitted: Operation.List
pending: Operation.List
completed: Operation.List
userdata: ?*anyopaque align(@max(@alignOf(?*anyopaque), 4))

std.Io.Batch.add

函数

第 613 行

添加一个在下次 await 调用时执行的操作。 返回该操作完成后 next 将返回的索引。 断言同时活动的操作不超过 storage.len 个。

pub fn add(batch: *Batch, operation: Operation) u32

参数

batch: *Batch
operation: Operation

std.Io.Batch.addAt

函数

第 622 行

添加一个在下次 await 调用时执行的操作。 操作完成后,next 将返回 index。 断言 index 处的操作未处于活动状态。

pub fn addAt(batch: *Batch, index: u32, operation: Operation) void

参数

batch: *Batch
index: u32
operation: Operation

std.Io.Batch.awaitAsync

函数

第 682 行

等待至少一个已提交操作完成。此函数返回后,可通过 next 迭代已完成操作。

此函数允许实现在批量操作之间引入并发,但与 awaitConcurrent 不同,并不要求一定并发,因此不会因 error.ConcurrencyUnavailable 失败。

pub fn awaitAsync(batch: *Batch, io: Io) Cancelable!void

参数

batch: *Batch
io: Io

错误

Canceled

调用方请求停止异步操作。

std.Io.Batch.awaitConcurrent

函数

第 695 行

等待已提交操作中至少一个完成。 函数返回后,可通过 next 迭代 已完成操作。

与 awaitAsync 不同,此函数要求实现 并发执行操作,因此可能失败并返回 error.ConcurrencyUnavailable。

pub fn awaitConcurrent(batch: *Batch, io: Io, timeout: Timeout) AwaitConcurrentError!void

参数

batch: *Batch
io: Io
timeout: Timeout

错误

Canceled Cancelable

调用方请求停止异步操作。

ConcurrencyUnavailable ConcurrentError

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

Timeout Error

std.Io.Batch.AwaitConcurrentError

错误集合

第 686 行

错误

Canceled Cancelable

调用方请求停止异步操作。

ConcurrencyUnavailable ConcurrentError

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

Timeout Error

std.Io.Batch.cancel

函数

第 705 行

请求中断所有未完成操作,然后等待所有 未完成操作结束。返回后,Batch 处于 定义明确的状态,可通过 next 迭代。成功 取消的操作不会出现在迭代中。某些操作 可能不受取消请求影响而成功完成, 它们会出现在迭代中。

pub fn cancel(batch: *Batch, io: Io) void

参数

batch: *Batch
io: Io

std.Io.Batch.Completion

容器

第 642 行

字段

index: u32

所提供操作存储中已完成的元素。 可使用 addAt,通过此 index 重新启用 Batch。

result: Operation.Result

此操作的返回值。

std.Io.Batch.init

函数

第 590 行

调用后,可以安全地无条件使用 defer 调用 cancel。storage 是预分配、内容未定义的内存缓冲区, 决定可通过 add 和 addAt 提交的 最大活动操作数。

pub fn init(storage: []Operation.Storage) Batch

参数

storage: []Operation.Storage

std.Io.Batch.next

函数

第 655 行

调用 awaitAsync、awaitConcurrent 或 cancel 后, 此函数会遍历已完成的操作。

每次此函数返回一个完成项时,都会将它从 Batch 出队。 再次等待之前无需取出所有完成项。

pub fn next(batch: *Batch) ?Completion

参数

batch: *Batch

std.Io.builtin

常量

第 17 行

std.Io.Cancelable

错误集合

第 815 行

错误

Canceled

调用方请求停止异步操作。

std.Io.CancelProtection

容器

第 1451 行

极少数情况下,需要完全阻止取消通知,使某段 代码可不受打断地运行,然后才可能观察到 error.Canceled。因此,每个 任务都有“取消保护”状态,表示 Io 函数是否可以引入 取消点。

修改任务取消保护状态,参见 swapCancelProtection。

关于取消及取消点的说明,参见 Future.cancel。

字段

unblocked = 0

调用任何错误集合包含 error.Canceled 的 Io 函数,都是取消点。

这是所有任务创建时的默认状态。

blocked = 1

没有 Io 函数引入取消点(永远不会返回 error.Canceled)。

std.Io.checkCancel

函数

第 1485 行

此函数仅作为取消点,受取消保护约束,参见 CancelProtection, 除此之外不执行操作。也就是说,存在未被阻止的待处理取消请求时,返回 error.Canceled, 否则不执行任何操作。

通常无需调用此函数。主要用途是在耗时较长的 CPU 密集型 任务中,在任务完成前响应取消请求。较短的任务,或者 执行其他 Io 操作、因而包含其他取消点的任务,通常已经 能够迅速响应取消请求。

关于取消及取消点的说明,参见 Future.cancel。

pub fn checkCancel(io: Io) Cancelable!void

参数

io: Io

错误

Canceled

调用方请求停止异步操作。

std.Io.Clock

容器

第 836 行

字段

real

可设置的系统全局时钟,用于测量实际时间(即墙上时钟时间)。系统时间的不连续跳变(例如系统管理员手动调整时钟)以及 NTP 等应用程序进行的频率调整,都会影响此时钟。

此时钟通常计算自协调世界时 (UTC) 1970-01-01 00:00:00 起经过的秒数,但忽略闰秒;临近闰秒时,NTP 通常会调整该时钟,使其大致与 UTC 保持同步。

此时钟实现返回的时间戳表示自 POSIX/Unix 纪元 1970-01-01T00:00:00Z 起经过的时间,不计闰秒。通常称为“Unix 时间”。若底层操作系统的原生时间戳使用其他纪元(如 Windows 使用 1601-01-01),则进行相应转换。

awake

不可设置的系统级时钟,表示自过去某个 未指定时间点以来经过的时间。

单调性:保证连续调用返回的时间 不会倒退,但相邻调用可能返回相同 而未增加的时间值。

不受系统时间不连续跳变的影响,例如 管理员手动调整时钟;但可能 受到频率调整的影响。

此时钟的意图是不计入系统 挂起的时间。不过,实现可能无法满足 这一要求,从而将其计入。

  • Linux 上对应 CLOCK_MONOTONIC。
  • macOS 上对应 CLOCK_UPTIME_RAW。
boot

与 awake 相同,但表达出将系统挂起的时间也计入的意图; 不过,由于平台限制,其行为可能与 awake 完全相同。

  • Linux 上对应 CLOCK_BOOTTIME。
  • macOS 上对应 CLOCK_MONOTONIC_RAW。
cpu_process

跟踪调用进程在用户态或内核态使用的 CPU 时间。

cpu_thread

跟踪调用线程在用户模式或内核模式下消耗的 CPU 时间。

std.Io.Clock.Duration

容器

第 1005 行

字段

raw: Io.Duration
clock: Clock

std.Io.Clock.Duration.sleep

函数

第 1015 行

等待 clock 上经过指定时长。

另见:

  • Io.sleep
  • Clock.Timestamp.wait
  • Timeout.sleep
pub fn sleep(duration: Clock.Duration, io: Io) Cancelable!void

参数

duration: Clock.Duration
io: Io

错误

Canceled

调用方请求停止异步操作。

std.Io.Clock.now

函数

第 893 行

此函数不会阻塞,因此不可取消。

分辨率由 resolution 确定; 若不支持此时钟,该值可能为 0。

另见:

  • Clock.Timestamp.now
pub fn now(clock: Clock, io: Io) Io.Timestamp

参数

clock: Clock
io: Io

std.Io.Clock.resolution

函数

第 904 行

提供 clock 的粒度。可能为零,表示时钟不受支持。

pub fn resolution(clock: Clock, io: Io) ResolutionError!Io.Duration

参数

clock: Clock
io: Io

错误

ClockUnavailable
Unexpected

std.Io.Clock.ResolutionError

错误集合

第 897 行

错误

ClockUnavailable
Unexpected

std.Io.Clock.Timestamp

容器

第 908 行

字段

raw: Io.Timestamp
clock: Clock

std.Io.Clock.Timestamp.addDuration

函数

第 944 行

pub fn addDuration(from: Clock.Timestamp, duration: Clock.Duration) Clock.Timestamp

参数

from: Clock.Timestamp
duration: Clock.Duration

std.Io.Clock.Timestamp.compare

函数

第 999 行

pub fn compare(lhs: Clock.Timestamp, op: math.CompareOperator, rhs: Clock.Timestamp) bool

参数

std.Io.Clock.Timestamp.durationFromNow

函数

第 978 行

分辨率由 resolution 决定;若时钟不受支持,其值可能为 0。

pub fn durationFromNow(timestamp: Clock.Timestamp, io: Io) Clock.Duration

参数

timestamp: Clock.Timestamp
io: Io

std.Io.Clock.Timestamp.durationTo

函数

第 936 行

pub fn durationTo(from: Clock.Timestamp, to: Clock.Timestamp) Clock.Duration

参数

std.Io.Clock.Timestamp.fromNow

函数

第 962 行

分辨率由 resolution 决定;若时钟不受支持,其值可能为 0。

pub fn fromNow(io: Io, duration: Clock.Duration) Clock.Timestamp

参数

io: Io
duration: Clock.Duration

std.Io.Clock.Timestamp.now

函数

第 919 行

此函数不会阻塞,因此不可取消。

分辨率由 resolution 决定;若时钟不受支持, 则可能为 0。

另见:

  • Clock.now
pub fn now(io: Io, clock: Clock) Clock.Timestamp

参数

io: Io
clock: Clock

std.Io.Clock.Timestamp.subDuration

函数

第 952 行

pub fn subDuration(from: Clock.Timestamp, duration: Clock.Duration) Clock.Timestamp

参数

from: Clock.Timestamp
duration: Clock.Duration

std.Io.Clock.Timestamp.toClock

函数

第 988 行

分辨率由 resolution 决定;若时钟不受支持,其值可能为 0。

pub fn toClock(t: Clock.Timestamp, io: Io, clock: Clock) Clock.Timestamp

参数

t: Clock.Timestamp
io: Io
clock: Clock

std.Io.Clock.Timestamp.untilNow

函数

第 971 行

分辨率由 resolution 决定;若时钟不受支持,其值可能为 0。

pub fn untilNow(timestamp: Clock.Timestamp, io: Io) Clock.Duration

参数

timestamp: Clock.Timestamp
io: Io

std.Io.Clock.Timestamp.wait

函数

第 932 行

休眠至指定时间戳。

另请参见:

  • Io.sleep
  • Clock.Duration.sleep
  • Timeout.sleep
pub fn wait(t: Clock.Timestamp, io: Io) Cancelable!void

参数

t: Clock.Timestamp
io: Io

错误

Canceled

调用方请求停止异步操作。

std.Io.concurrent

函数

第 2571 行

使用 args 调用 function,函数的返回值 只有在调用 await 后才保证可用,从而允许调用方 在等待 Io 操作时继续执行。

与 async 相比,此操作提供更强保证,因此限制 可支持的 Io 实现类型。改为调用 async,则 可允许有栈、单线程、阻塞式 I/O 等实现。

pub fn concurrent( io: Io, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function)), ) ConcurrentError!Future(@typeInfo(@TypeOf(function)).@"fn".return_type.?)

参数

io: Io
args: std.meta.ArgsTuple(@TypeOf(function))

错误

ConcurrencyUnavailable

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

std.Io.concurrent.start

函数

第 2579 行

fn start(context: *const anyopaque, result: *anyopaque) void

参数

context: *const anyopaque
result: *anyopaque

std.Io.ConcurrentError

错误集合

第 2558 行

错误

ConcurrencyUnavailable

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

std.Io.Condition

容器

第 1782 行

字段

state: std.atomic.Value(State)
epoch: std.atomic.Value(u32)

每当条件被触发时递增

std.Io.Condition.broadcast

函数

第 1945 行

pub fn broadcast(cond: *Condition, io: Io) void

参数

cond: *Condition
io: Io

std.Io.Condition.deregister

函数

第 1908 行

fn deregister(cond: *Condition, io: Io) void

参数

cond: *Condition
io: Io

std.Io.Condition.init

常量

第 1792 行

Condition

std.Io.Condition.signal

函数

第 1926 行

pub fn signal(cond: *Condition, io: Io) void

参数

cond: *Condition
io: Io

std.Io.Condition.State

容器

第 1787 行

字段

waiters: u16
signals: u16

std.Io.Condition.wait

函数

第 1802 行

阻塞,直到条件收到信号或操作被取消。

另请参见:

  • waitUncancelable
  • waitTimeout
pub fn wait(cond: *Condition, io: Io, mutex: *Mutex) Cancelable!void

参数

cond: *Condition
io: Io
mutex: *Mutex

错误

Canceled

调用方请求停止异步操作。

std.Io.Condition.waitTimeout

函数

第 1817 行

阻塞直到条件被通知、被取消,或给定 超时到期。

另请参见:

  • wait
  • waitUncancelable
pub fn waitTimeout(cond: *Condition, io: Io, mutex: *Mutex, timeout: Timeout) WaitTimeoutError!void

参数

cond: *Condition
io: Io
mutex: *Mutex
timeout: Timeout

错误

Canceled Cancelable

调用方请求停止异步操作。

Timeout Error

std.Io.Condition.WaitTimeoutError

错误集合

第 1809 行

错误

Canceled Cancelable

调用方请求停止异步操作。

Timeout Error

std.Io.Condition.waitUncancelable

函数

第 1872 行

与 wait 相同,但不引入取消点。

关于取消点,参见 Future.cancel。

pub fn waitUncancelable(cond: *Condition, io: Io, mutex: *Mutex) void

参数

cond: *Condition
io: Io
mutex: *Mutex

std.Io.Dir

别名

第 44 行

别名目标 std.Io.Dir

std.Io.Dispatch

别名

第 37 行

别名目标 std.Io.Dispatch

std.Io.doOp

函数

第 3631 行

fn doOp() void

std.Io.Duration

容器

第 1087 行

字段

nanoseconds: i96

std.Io.Duration.format

函数

第 1127 行

按有符号数值的大小格式化纳秒数: [#y][#w][#d][#h][#m]#[.###][n|u|m]s

pub fn format(duration: Duration, w: *Writer) Writer.Error!void

参数

duration: Duration
w: *Writer

错误

WriteFailed

详细诊断信息见 Writer 实现。

用法示例

test format {
    try testFormat("0ns", 0);
    try testFormat("1ns", 1);
    try testFormat("-1ns", -(1));
    try testFormat("999ns", std.time.ns_per_us - 1);
    try testFormat("-999ns", -(std.time.ns_per_us - 1));
    try testFormat("1us", std.time.ns_per_us);
    try testFormat("-1us", -(std.time.ns_per_us));
    try testFormat("1.45us", 1450);
    try testFormat("-1.45us", -(1450));
    try testFormat("1.5us", 3 * std.time.ns_per_us / 2);
    try testFormat("-1.5us", -(3 * std.time.ns_per_us / 2));
    try testFormat("14.5us", 14500);
    try testFormat("-14.5us", -(14500));
    try testFormat("145us", 145000);
    try testFormat("-145us", -(145000));
    try testFormat("999.999us", std.time.ns_per_ms - 1);
    try testFormat("-999.999us", -(std.time.ns_per_ms - 1));
    try testFormat("1ms", std.time.ns_per_ms + 1);
    try testFormat("-1ms", -(std.time.ns_per_ms + 1));
    try testFormat("1.5ms", 3 * std.time.ns_per_ms / 2);
    try testFormat("-1.5ms", -(3 * std.time.ns_per_ms / 2));
    try testFormat("1.11ms", 1110000);
    try testFormat("-1.11ms", -(1110000));
    try testFormat("1.111ms", 1111000);
    try testFormat("-1.111ms", -(1111000));
    try testFormat("1.111ms", 1111100);
    try testFormat("-1.111ms", -(1111100));
    try testFormat("999.999ms", std.time.ns_per_s - 1);
    try testFormat("-999.999ms", -(std.time.ns_per_s - 1));
    try testFormat("1s", std.time.ns_per_s);
    try testFormat("-1s", -(std.time.ns_per_s));
    try testFormat("59.999s", std.time.ns_per_min - 1);
    try testFormat("-59.999s", -(std.time.ns_per_min - 1));
    try testFormat("1m", std.time.ns_per_min);
    try testFormat("-1m", -(std.time.ns_per_min));
    try testFormat("1h", std.time.ns_per_hour);
    try testFormat("-1h", -(std.time.ns_per_hour));
    try testFormat("1d", std.time.ns_per_day);
    try testFormat("-1d", -(std.time.ns_per_day));
    try testFormat("1w", std.time.ns_per_week);
    try testFormat("-1w", -(std.time.ns_per_week));
    try testFormat("1y", 365 * std.time.ns_per_day);
    try testFormat("-1y", -(365 * std.time.ns_per_day));
    try testFormat("1y52w23h59m59.999s", 730 * std.time.ns_per_day - 1); // 365d = 52w1d
    try testFormat("-1y52w23h59m59.999s", -(730 * std.time.ns_per_day - 1)); // 365d = 52w1d
    try testFormat("1y1h1.001s", 365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_s + std.time.ns_per_ms);
    try testFormat("-1y1h1.001s", -(365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_s + std.time.ns_per_ms));
    try testFormat("1y1h1s", 365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_s + 999 * std.time.ns_per_us);
    try testFormat("-1y1h1s", -(365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_s + 999 * std.time.ns_per_us));
    try testFormat("1y1h999.999us", 365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_ms - 1);
    try testFormat("-1y1h999.999us", -(365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_ms - 1));
    try testFormat("1y1h1ms", 365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_ms);
    try testFormat("-1y1h1ms", -(365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_ms));
    try testFormat("1y1h1ms", 365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_ms + 1);
    try testFormat("-1y1h1ms", -(365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_ms + 1));
    try testFormat("1y1m999ns", 365 * std.time.ns_per_day + std.time.ns_per_min + 999);
    try testFormat("-1y1m999ns", -(365 * std.time.ns_per_day + std.time.ns_per_min + 999));
    try testFormat("292y24w3d23h47m16.854s", std.math.maxInt(i64));
    try testFormat("-292y24w3d23h47m16.854s", std.math.minInt(i64) + 1);
    try testFormat("-292y24w3d23h47m16.854s", std.math.minInt(i64));
}

std.Io.Duration.formatUnsigned

函数

第 1132 行

fn formatUnsigned(w: *Writer, ns: u96) Writer.Error!void

参数

w: *Writer
ns: u96

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.Duration.fromMicroseconds

函数

第 1097 行

pub fn fromMicroseconds(x: i64) Duration

参数

x: i64

std.Io.Duration.fromMilliseconds

函数

第 1101 行

pub fn fromMilliseconds(x: i64) Duration

参数

x: i64

std.Io.Duration.fromNanoseconds

函数

第 1093 行

pub fn fromNanoseconds(x: i96) Duration

参数

x: i96

std.Io.Duration.fromSeconds

函数

第 1105 行

pub fn fromSeconds(x: i64) Duration

参数

x: i64

std.Io.Duration.max

常量

第 1091 行

Duration

std.Io.Duration.testFormat

函数

第 1241 行

fn testFormat(expected: []const u8, input: i96) !void

参数

expected: []const u8
input: i96

std.Io.Duration.toMicroseconds

函数

第 1109 行

pub fn toMicroseconds(d: Duration) i64

参数

std.Io.Duration.toMilliseconds

函数

第 1113 行

pub fn toMilliseconds(d: Duration) i64

参数

std.Io.Duration.toNanoseconds

函数

第 1121 行

pub fn toNanoseconds(d: Duration) i96

参数

std.Io.Duration.toSeconds

函数

第 1117 行

pub fn toSeconds(d: Duration) i64

参数

std.Io.Duration.zero

常量

第 1090 行

Duration

std.Io.Event

容器

第 1966 行

可设置及清除的逻辑布尔标志,支持“等待直到被设置”操作。

字段

unset
waiting
is_set

std.Io.Event.isSet

函数

第 1972 行

返回逻辑布尔值是否为 true。

pub fn isSet(event: *const Event) bool

参数

event: *const Event

std.Io.Event.reset

函数

第 2073 行

将逻辑布尔值设为 false。

假定没有尚未完成的 wait 或 waitUncancelable 调用。

但允许并发调用 isSet、set 和 reset。

pub fn reset(e: *Event) void

参数

e: *Event

std.Io.Event.set

函数

第 2061 行

将逻辑布尔值设为 true,从而解除所有待处理的 wait 调用的阻塞。逻辑布尔值在调用 reset 之前始终保持 true,因此后续调用 set 没有语义上的影响。

set 调用之前的所有内存访问都被“释放”,因此,若该 set 调用导致 isSet 返回 true 或等待结束,这些任务就能够观察到之前的内存访问。

pub fn set(e: *Event, io: Io) void

参数

e: *Event
io: Io

std.Io.Event.wait

函数

第 1980 行

阻塞直到逻辑布尔值为 true。

pub fn wait(event: *Event, io: Io) Cancelable!void

参数

event: *Event
io: Io

错误

Canceled

调用方请求停止异步操作。

std.Io.Event.waitTimeout

函数

第 2025 行

阻塞调用线程,直到逻辑布尔值被设置或超时。

pub fn waitTimeout(event: *Event, io: Io, timeout: Timeout) WaitTimeoutError!void

参数

event: *Event
io: Io
timeout: Timeout

错误

Canceled Cancelable

调用方请求停止异步操作。

Timeout

std.Io.Event.WaitTimeoutError

错误集合

第 2022 行

错误

Canceled Cancelable

调用方请求停止异步操作。

Timeout

std.Io.Event.waitUncancelable

函数

第 2006 行

与 wait 相同,但不会引入取消点。

关于取消和取消点的说明,参见 Future.cancel。

pub fn waitUncancelable(event: *Event, io: Io) void

参数

event: *Event
io: Io

std.Io.Evented

类型

第 31 行

std.Io.failing

常量

第 2718 行

模拟不支持任何 Io 操作的系统的 Io 实现。

该系统具有以下属性:

  • 无法并发执行。
  • 标准输入输出句柄是远端已关闭的管道。
  • 文件系统完全为空,包括当前工作目录也已不存在。
  • 文件系统已满,因此尝试创建条目始终返回 error.NoSpaceLeft。
  • 不支持熵源,因此 randomSecure 始终返回 error.EntropyUnavailable,random 始终返回 0(以 0 填充缓冲区)。
  • 不支持时钟,因此 now 和 sleep 始终返回 error.UnsupportedClock。
  • 未连接网络,因此网络操作始终返回 error.NetworkDown。
std.Io

std.Io.failingClockResolution

函数

第 3519 行

pub fn failingClockResolution(userdata: ?*anyopaque, clock: Clock) Clock.ResolutionError!Duration

参数

userdata: ?*anyopaque
clock: Clock

错误

ClockUnavailable
Unexpected

std.Io.failingConcurrent

函数

第 2855 行

pub fn failingConcurrent( userdata: ?*anyopaque, result_len: usize, result_alignment: std.mem.Alignment, context: []const u8, context_alignment: std.mem.Alignment, start: *const fn (context: *const anyopaque, result: *anyopaque) void, ) ConcurrentError!*AnyFuture

参数

userdata: ?*anyopaque
result_len: usize
result_alignment: std.mem.Alignment
context: []const u8
context_alignment: std.mem.Alignment
start: *const fn (context: *const anyopaque, result: *anyopaque) void

错误

ConcurrencyUnavailable

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

std.Io.failingDirAccess

函数

第 3052 行

pub fn failingDirAccess(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.AccessOptions) Dir.AccessError!void

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
options: Dir.AccessOptions

错误

AccessDenied

文件不允许请求的 AccessOptions,或路径前缀中的 某个目录不允许搜索。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

FileBusy
FileNotFound
InputOutput
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

PermissionDenied

请求了写入权限,但文件不可变。

ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingDirCreateDir

函数

第 3005 行

pub fn failingDirCreateDir(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions) Dir.CreateDirError!void

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
permissions: Dir.Permissions

错误

AccessDenied

在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

DiskQuota
FileNotFound
LinkQuotaExceeded
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice
NoSpaceLeft
NotDir
PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingDirCreateDirPath

函数

第 3013 行

pub fn failingDirCreateDirPath(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions) Dir.CreateDirPathError!Dir.CreatePathStatus

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
permissions: Dir.Permissions

错误

AccessDenied CreateDirError

在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。

AntivirusInterference OpenError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy OpenError
DiskQuota CreateDirError
FileBusy OpenError

以下三种情况之一:

  • pathname 指向正在执行的可执行映像, 且请求写访问。
  • pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
  • pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
FileLocksUnsupported OpenError
FileNotFound OpenError

以下任一情况:

  • 某个路径分量不存在。
  • 使用了当前工作目录,但该目录已被删除。
  • 已打开目录句柄所关联的路径已被删除。
  • macOS 上,多个进程或线程将 O.EXCL 设为 false,并发争相创建同一文件。
FileTooBig OpenError

文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。

IsDir OpenError

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
LinkQuotaExceeded CreateDirError
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound CreateDirError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice CreateDirError
NoSpaceLeft OpenError

设备没有空间容纳新文件,无法创建新路径。 仅在提供 CREAT 标志时才可能出现此错误。

NotDir OpenError

路径中用作目录的某个部分实际上不是目录, 或者指定了 DIRECTORY,但路径不是目录。

PathAlreadyExists OpenError

路径已存在,且提供了 CREAT 和 EXCL 标志。

PermissionDenied CreateDirError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem CreateDirError
Streaming StatError

尝试对非文件流调用 stat。

SymLinkLoop CreateDirError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

路径超过 max_path_bytes 字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock OpenError

已请求非阻塞模式,但该操作无法立即返回。

std.Io.failingDirCreateDirPathOpen

函数

第 3021 行

pub fn failingDirCreateDirPathOpen(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions, options: Dir.OpenOptions) Dir.CreateDirPathOpenError!Dir

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
permissions: Dir.Permissions
options: Dir.OpenOptions

错误

AccessDenied CreateDirError

在 WASI 中,当文件描述符不具备相对于自身 创建新目录所需的权限时,可能发生此错误。

AntivirusInterference OpenError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy OpenError
DiskQuota CreateDirError
FileBusy OpenError

以下三种情况之一:

  • pathname 指向正在执行的可执行映像, 且请求写访问。
  • pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
  • pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
FileLocksUnsupported OpenError
FileNotFound OpenError

以下任一情况:

  • 某个路径分量不存在。
  • 使用了当前工作目录,但该目录已被删除。
  • 已打开目录句柄所关联的路径已被删除。
  • macOS 上,多个进程或线程将 O.EXCL 设为 false,并发争相创建同一文件。
FileTooBig OpenError

文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。

IsDir OpenError

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
LinkQuotaExceeded CreateDirError
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound CreateDirError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice CreateDirError
NoSpaceLeft OpenError

设备没有空间容纳新文件,无法创建新路径。 仅在提供 CREAT 标志时才可能出现此错误。

NotDir OpenError

路径中用作目录的某个部分实际上不是目录, 或者指定了 DIRECTORY,但路径不是目录。

PathAlreadyExists OpenError

路径已存在,且提供了 CREAT 和 EXCL 标志。

PermissionDenied CreateDirError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem CreateDirError
Streaming StatError

尝试对非文件流调用 stat。

SymLinkLoop CreateDirError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

路径超过 max_path_bytes 字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock OpenError

已请求非阻塞模式,但该操作无法立即返回。

std.Io.failingDirCreateFile

函数

第 3060 行

pub fn failingDirCreateFile(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.CreateFileOptions) File.OpenError!File

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
options: Dir.CreateFileOptions

错误

AccessDenied

在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。

AntivirusInterference

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy
FileBusy

以下三种情况之一:

  • pathname 指向正在执行的可执行映像, 且请求写访问。
  • pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
  • pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
FileLocksUnsupported
FileNotFound

以下任一情况:

  • 某个路径分量不存在。
  • 使用了当前工作目录,但该目录已被删除。
  • 已打开目录句柄所关联的路径已被删除。
  • macOS 上,多个进程或线程将 O.EXCL 设为 false,并发争相创建同一文件。
FileTooBig

文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。

IsDir

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice
NoSpaceLeft

设备没有空间容纳新文件,无法创建新路径。 仅在提供 CREAT 标志时才可能出现此错误。

NotDir

路径中用作目录的某个部分实际上不是目录, 或者指定了 DIRECTORY,但路径不是目录。

PathAlreadyExists

路径已存在,且提供了 CREAT 和 EXCL 标志。

PermissionDenied
PipeBusy
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources

路径超过 max_path_bytes 字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock

已请求非阻塞模式,但该操作无法立即返回。

std.Io.failingDirCreateFileAtomic

函数

第 3068 行

pub fn failingDirCreateFileAtomic(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.CreateFileAtomicOptions) Dir.CreateFileAtomicError!File.Atomic

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
options: Dir.CreateFileAtomicOptions

错误

AccessDenied

在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。

AntivirusInterference

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

FileBusy

尝试创建的文件是正在运行的可执行文件。

FileNotFound

以下情况之一:

  • 某个路径分量不存在。
  • 使用了 Cwd,但当前工作目录已被删除。
  • 与已打开目录句柄关联的路径已被删除。
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice
NoSpaceLeft

设备没有空间容纳新文件,无法创建新路径。

NotDir

路径中作为目录使用的某个组成部分实际上不是目录。

PermissionDenied
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources

可用内核内存不足。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock

std.Io.failingDirDeleteDir

函数

第 3119 行

pub fn failingDirDeleteDir(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteDirError!void

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8

错误

AccessDenied
BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

DirNotEmpty
FileBusy
FileNotFound
FileSystem
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound

在 Windows 上,未找到 \\server 或 \\server\share。

NotDir
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingDirDeleteFile

函数

第 3112 行

pub fn failingDirDeleteFile(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteFileError!void

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8

错误

AccessDenied

在 WASI 中,若文件描述符不具有通过相对于它的路径 解除资源链接所需的权限,可能发生此错误。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

FileBusy
FileNotFound
FileSystem
IsDir
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound

在 Windows 上,未找到 \\server 或 \\server\share。

NotDir
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingDirHardLink

函数

第 3203 行

pub fn failingDirHardLink(userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, options: Dir.HardLinkOptions) Dir.HardLinkError!void

参数

userdata: ?*anyopaque
old_dir: Dir
old_sub_path: []const u8
new_dir: Dir
new_sub_path: []const u8
options: Dir.HardLinkOptions

错误

AccessDenied HardLinkError
BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

CrossDevice HardLinkError
DiskQuota HardLinkError
FileNotFound HardLinkError
HardwareFailure HardLinkError
LinkQuotaExceeded HardLinkError
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NoSpaceLeft HardLinkError
NotDir HardLinkError
OperationUnsupported HardLinkError

操作系统或文件系统不支持硬链接。

PathAlreadyExists HardLinkError
PermissionDenied HardLinkError
ReadOnlyFileSystem HardLinkError
SymLinkLoop HardLinkError
SystemResources HardLinkError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingDirOpenDir

函数

第 3030 行

pub fn failingDirOpenDir(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.OpenOptions) Dir.OpenError!Dir

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
options: Dir.OpenOptions

错误

AccessDenied
BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

FileNotFound
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice
NotDir
PermissionDenied
ProcessFdQuotaExceeded
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingDirOpenFile

函数

第 3076 行

pub fn failingDirOpenFile(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, flags: Dir.OpenFileOptions) File.OpenError!File

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
flags: Dir.OpenFileOptions

错误

AccessDenied

在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。

AntivirusInterference

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy
FileBusy

以下三种情况之一:

  • pathname 指向正在执行的可执行映像, 且请求写访问。
  • pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
  • pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
FileLocksUnsupported
FileNotFound

以下任一情况:

  • 某个路径分量不存在。
  • 使用了当前工作目录,但该目录已被删除。
  • 已打开目录句柄所关联的路径已被删除。
  • macOS 上,多个进程或线程将 O.EXCL 设为 false,并发争相创建同一文件。
FileTooBig

文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。

IsDir

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice
NoSpaceLeft

设备没有空间容纳新文件,无法创建新路径。 仅在提供 CREAT 标志时才可能出现此错误。

NotDir

路径中用作目录的某个部分实际上不是目录, 或者指定了 DIRECTORY,但路径不是目录。

PathAlreadyExists

路径已存在,且提供了 CREAT 和 EXCL 标志。

PermissionDenied
PipeBusy
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources

路径超过 max_path_bytes 字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock

已请求非阻塞模式,但该操作无法立即返回。

std.Io.failingDirReadLink

函数

第 3153 行

pub fn failingDirReadLink(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, buffer: []u8) Dir.ReadLinkError!usize

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
buffer: []u8

错误

AccessDenied

在 WASI 中,若文件描述符不具有相对于该描述符读取符号链接值所需的权限,可能发生此错误。

AntivirusInterference

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

FileBusy

尝试打开的文件是正在运行的可执行文件。

FileNotFound
FileSystem
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound

在 Windows 上,未找到 \\server 或 \\server\share。

NotDir
NotLink
PermissionDenied
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnsupportedReparsePointType

仅限 Windows。如果打开的重解析点类型不受支持, 可能发生此错误。

std.Io.failingDirRealPath

函数

第 3097 行

pub fn failingDirRealPath(userdata: ?*anyopaque, dir: Dir, out_buffer: []u8) Dir.RealPathError!usize

参数

userdata: ?*anyopaque
dir: Dir
out_buffer: []u8

错误

AccessDenied RealPathError
AntivirusInterference RealPathError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy RealPathError
FileBusy RealPathError
FileNotFound RealPathError
FileSystem RealPathError
FileTooBig RealPathError
InputOutput RealPathError
IsDir RealPathError
NameTooLong RealPathError

完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。

NetworkNotFound RealPathError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice RealPathError
NoSpaceLeft RealPathError
NotDir RealPathError
OperationUnsupported RealPathError

此操作系统、文件系统或 Io 实现 不支持 realpath 操作。

PathAlreadyExists RealPathError
PermissionDenied RealPathError
PipeBusy RealPathError
ProcessFdQuotaExceeded RealPathError
SymLinkLoop RealPathError
SystemFdQuotaExceeded RealPathError
SystemResources RealPathError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnrecognizedVolume RealPathError

在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。

std.Io.failingDirRealPathFile

函数

第 3104 行

pub fn failingDirRealPathFile(userdata: ?*anyopaque, dir: Dir, path_name: []const u8, out_buffer: []u8) Dir.RealPathFileError!usize

参数

userdata: ?*anyopaque
dir: Dir
path_name: []const u8
out_buffer: []u8

错误

AccessDenied RealPathError
AntivirusInterference RealPathError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy RealPathError
FileBusy RealPathError
FileNotFound RealPathError
FileSystem RealPathError
FileTooBig RealPathError
InputOutput RealPathError
IsDir RealPathError
NameTooLong RealPathError

完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。

NetworkNotFound RealPathError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice RealPathError
NoSpaceLeft RealPathError
NotDir RealPathError
OperationUnsupported RealPathError

此操作系统、文件系统或 Io 实现 不支持 realpath 操作。

PathAlreadyExists RealPathError
PermissionDenied RealPathError
PipeBusy RealPathError
ProcessFdQuotaExceeded RealPathError
SymLinkLoop RealPathError
SystemFdQuotaExceeded RealPathError
SystemResources RealPathError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnrecognizedVolume RealPathError

在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。

std.Io.failingDirRename

函数

第 3126 行

pub fn failingDirRename(userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8) Dir.RenameError!void

参数

userdata: ?*anyopaque
old_dir: Dir
old_sub_path: []const u8
new_dir: Dir
new_sub_path: []const u8

错误

AccessDenied

在 WASI 中,当文件描述符不具备相对于自身 按路径重命名资源所需的权限时,可能发生此错误。

AntivirusInterference

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

CrossDevice
DirNotEmpty

试图替换非空目录。

DiskQuota
FileBusy

尝试移动或替换的文件是正在运行的可执行文件。

FileNotFound
HardwareFailure
IsDir
LinkQuotaExceeded
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice
NoSpaceLeft
NotDir
PermissionDenied
PipeBusy
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingDirRenamePreserve

函数

第 3135 行

pub fn failingDirRenamePreserve(userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8) Dir.RenamePreserveError!void

参数

userdata: ?*anyopaque
old_dir: Dir
old_sub_path: []const u8
new_dir: Dir
new_sub_path: []const u8

错误

AccessDenied

在 WASI 中,当文件描述符不具有 按相对于该描述符的路径重命名资源所需的权限时,可能发生此错误。

在 Windows 上,将目录重命名并覆盖已有目录时, 可能返回此错误,而不是 PathAlreadyExists。

在 Darwin 上,如果任一路径中的分量指向需要实体化的 “无数据”目录,而当前线程或进程的 I/O 策略不允许无数据目录实体化,则可能返回此错误。

AntivirusInterference RenameError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

CrossDevice RenameError
DirNotEmpty RenameError

试图替换非空目录。

DiskQuota RenameError
FileBusy RenameError

尝试移动或替换的文件是正在运行的可执行文件。

FileNotFound RenameError
HardwareFailure RenameError
IsDir RenameError
LinkQuotaExceeded RenameError
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound RenameError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice RenameError
NoSpaceLeft RenameError
NotDir RenameError
OperationUnsupported

操作系统或文件系统不支持原子地执行不替换目标的重命名。

PathAlreadyExists
PermissionDenied RenameError
PipeBusy RenameError
ReadOnlyFileSystem RenameError
SymLinkLoop RenameError
SystemResources RenameError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingDirSetFileOwner

函数

第 3169 行

pub fn failingDirSetFileOwner(userdata: ?*anyopaque, dir: std.Io.Dir, sub_path: []const u8, owner: ?File.Uid, group: ?File.Gid, options: Dir.SetFileOwnerOptions) Dir.SetFileOwnerError!void

参数

userdata: ?*anyopaque
dir: std.Io.Dir
sub_path: []const u8
owner: ?File.Uid
group: ?File.Gid
options: Dir.SetFileOwnerOptions

错误

AccessDenied SetOwnerError
BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

FileNotFound SetOwnerError
InputOutput SetOwnerError
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

PermissionDenied SetOwnerError
ReadOnlyFileSystem SetOwnerError
SymLinkLoop SetOwnerError
SystemResources SetOwnerError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingDirSetFilePermissions

函数

第 3186 行

pub fn failingDirSetFilePermissions(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: File.Permissions, options: Dir.SetFilePermissionsOptions) Dir.SetFilePermissionsError!void

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
permissions: File.Permissions
options: Dir.SetFilePermissionsOptions

错误

AccessDenied SetPermissionsError
BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

FileNotFound SetPermissionsError
InputOutput SetPermissionsError
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

OperationUnsupported

SetFilePermissionsOptions.follow_symlinks 被设为 false,但文件系统或操作系统不允许。

PermissionDenied SetPermissionsError
ProcessFdQuotaExceeded
ReadOnlyFileSystem SetPermissionsError
SymLinkLoop SetPermissionsError
SystemFdQuotaExceeded
SystemResources SetPermissionsError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingDirSetOwner

函数

第 3161 行

pub fn failingDirSetOwner(userdata: ?*anyopaque, dir: Dir, owner: ?File.Uid, group: ?File.Gid) Dir.SetOwnerError!void

参数

userdata: ?*anyopaque
dir: Dir
owner: ?File.Uid
group: ?File.Gid

错误

AccessDenied SetOwnerError
Canceled Cancelable

调用方请求停止异步操作。

FileNotFound SetOwnerError
InputOutput SetOwnerError
PermissionDenied SetOwnerError
ReadOnlyFileSystem SetOwnerError
SymLinkLoop SetOwnerError
SystemResources SetOwnerError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingDirSetPermissions

函数

第 3179 行

pub fn failingDirSetPermissions(userdata: ?*anyopaque, dir: Dir, permissions: Dir.Permissions) Dir.SetPermissionsError!void

参数

userdata: ?*anyopaque
dir: Dir
permissions: Dir.Permissions

错误

AccessDenied SetPermissionsError
Canceled Cancelable

调用方请求停止异步操作。

FileNotFound SetPermissionsError
InputOutput SetPermissionsError
PermissionDenied SetPermissionsError
ReadOnlyFileSystem SetPermissionsError
SymLinkLoop SetPermissionsError
SystemResources SetPermissionsError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingDirStat

函数

第 3038 行

pub fn failingDirStat(userdata: ?*anyopaque, dir: Dir) Dir.StatError!Dir.Stat

参数

userdata: ?*anyopaque
dir: Dir

错误

AccessDenied StatError

在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

PermissionDenied StatError
Streaming StatError

尝试对非文件流调用 stat。

SystemResources StatError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingDirStatFile

函数

第 3044 行

pub fn failingDirStatFile(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.StatFileOptions) Dir.StatFileError!File.Stat

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
options: Dir.StatFileOptions

错误

AccessDenied OpenError

在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。

AntivirusInterference OpenError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy OpenError
FileBusy OpenError

以下三种情况之一:

  • pathname 指向正在执行的可执行映像, 且请求写访问。
  • pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
  • pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
FileLocksUnsupported OpenError
FileNotFound OpenError

以下任一情况:

  • 某个路径分量不存在。
  • 使用了当前工作目录,但该目录已被删除。
  • 已打开目录句柄所关联的路径已被删除。
  • macOS 上,多个进程或线程将 O.EXCL 设为 false,并发争相创建同一文件。
FileTooBig OpenError

文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。

IsDir OpenError

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound OpenError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice OpenError
NoSpaceLeft OpenError

设备没有空间容纳新文件,无法创建新路径。 仅在提供 CREAT 标志时才可能出现此错误。

NotDir OpenError

路径中用作目录的某个部分实际上不是目录, 或者指定了 DIRECTORY,但路径不是目录。

PathAlreadyExists OpenError

路径已存在,且提供了 CREAT 和 EXCL 标志。

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ReadOnlyFileSystem OpenError
Streaming StatError

尝试对非文件流调用 stat。

SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

路径超过 max_path_bytes 字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock OpenError

已请求非阻塞模式,但该操作无法立即返回。

std.Io.failingDirSymLink

函数

第 3144 行

pub fn failingDirSymLink(userdata: ?*anyopaque, dir: Dir, target_path: []const u8, sym_link_path: []const u8, flags: Dir.SymLinkFlags) Dir.SymLinkError!void

参数

userdata: ?*anyopaque
dir: Dir
target_path: []const u8
sym_link_path: []const u8
flags: Dir.SymLinkFlags

错误

AccessDenied

在 WASI 中,当文件描述符不具备相对于自身 创建新符号链接所需的权限时,可能发生此错误。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

DiskQuota
FileNotFound
FileSystem
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound

在 Windows 上,未找到 \\server 或 \\server\share。

NoSpaceLeft
NotDir
PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingFileDowngradeLock

函数

第 3359 行

pub fn failingFileDowngradeLock(userdata: ?*anyopaque, file: File) File.DowngradeLockError!void

参数

userdata: ?*anyopaque
file: File

错误

Canceled Cancelable

调用方请求停止异步操作。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingFileHardLink

函数

第 3372 行

pub fn failingFileHardLink(userdata: ?*anyopaque, file: File, new_dir: Dir, new_sub_path: []const u8, options: File.HardLinkOptions) File.HardLinkError!void

参数

userdata: ?*anyopaque
file: File
new_dir: Dir
new_sub_path: []const u8
options: File.HardLinkOptions

错误

AccessDenied
BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

CrossDevice
DiskQuota
FileNotFound
HardwareFailure
LinkQuotaExceeded
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NoSpaceLeft
NotDir
OperationUnsupported

操作系统或文件系统不支持硬链接。

PathAlreadyExists
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingFileLength

函数

第 3219 行

pub fn failingFileLength(userdata: ?*anyopaque, file: File) File.LengthError!u64

参数

userdata: ?*anyopaque
file: File

错误

AccessDenied StatError

在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

PermissionDenied StatError
Streaming StatError

尝试对非文件流调用 stat。

SystemResources StatError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingFileLock

函数

第 3339 行

pub fn failingFileLock(userdata: ?*anyopaque, file: File, lock: File.Lock) File.LockError!void

参数

userdata: ?*anyopaque
file: File
lock: File.Lock

错误

Canceled Cancelable

调用方请求停止异步操作。

FileLocksUnsupported
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingFileMemoryMapCreate

函数

第 3381 行

pub fn failingFileMemoryMapCreate(userdata: ?*anyopaque, file: File, options: File.MemoryMap.CreateOptions) File.MemoryMap.CreateError!File.MemoryMap

参数

userdata: ?*anyopaque
file: File
options: File.MemoryMap.CreateOptions

错误

AccessDenied

以下任一情况:

  • File.Kind 不是 file。
  • 文件未以读取方式打开,且启用了读取访问保护。
  • 文件未以写入方式打开,且启用了写入访问保护。
Canceled Cancelable

调用方请求停止异步操作。

InputOutput ReadPositionalError
IsDir ReadPositionalError

尝试将目录文件描述符当作普通文件读取。

LockViolation ReadPositionalError

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

LockedMemoryLimitExceeded
NotOpenForReading ReadPositionalError

打开文件时未授予读取能力。

OutOfMemory Error
PermissionDenied

prot 参数请求 PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。

ProcessFdQuotaExceeded
SystemFdQuotaExceeded
SystemResources ReadPositionalError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable ReadPositionalError

此文件不支持按位置读取。

WouldBlock ReadPositionalError

已启用非阻塞模式,且从该文件描述符读取会阻塞。

std.Io.failingFileReadPositional

函数

第 3262 行

pub fn failingFileReadPositional(userdata: ?*anyopaque, file: File, data: []const []u8, offset: u64) File.ReadPositionalError!usize

参数

userdata: ?*anyopaque
file: File
data: []const []u8
offset: u64

错误

AccessDenied

在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

InputOutput
IsDir

尝试将目录文件描述符当作普通文件读取。

LockViolation

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading

打开文件时未授予读取能力。

SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable

此文件不支持按位置读取。

WouldBlock

已启用非阻塞模式,且从该文件描述符读取会阻塞。

std.Io.failingFileRealPath

函数

第 3365 行

pub fn failingFileRealPath(userdata: ?*anyopaque, file: File, out_buffer: []u8) File.RealPathError!usize

参数

userdata: ?*anyopaque
file: File
out_buffer: []u8

错误

AccessDenied
AntivirusInterference

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy
FileBusy
FileNotFound
FileSystem
FileTooBig
InputOutput
IsDir
NameTooLong

完整文件系统路径无法放入所提供的缓冲区,或 由于路径过长,无论提供多大的缓冲区, 均无法通过 realpath 函数获取。

NetworkNotFound

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice
NoSpaceLeft
NotDir
OperationUnsupported

此操作系统、文件系统或 Io 实现 不支持 realpath 操作。

PathAlreadyExists
PermissionDenied
PipeBusy
ProcessFdQuotaExceeded
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnrecognizedVolume

在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。

std.Io.failingFileSeekBy

函数

第 3272 行

pub fn failingFileSeekBy(userdata: ?*anyopaque, file: File, relative_offset: i64) File.SeekError!void

参数

userdata: ?*anyopaque
file: File
relative_offset: i64

错误

AccessDenied

文件描述符不具备执行定位所需的权限。

Canceled Cancelable

调用方请求停止异步操作。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable

std.Io.failingFileSeekTo

函数

第 3279 行

pub fn failingFileSeekTo(userdata: ?*anyopaque, file: File, absolute_offset: u64) File.SeekError!void

参数

userdata: ?*anyopaque
file: File
absolute_offset: u64

错误

AccessDenied

文件描述符不具备执行定位所需的权限。

Canceled Cancelable

调用方请求停止异步操作。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable

std.Io.failingFileSetLength

函数

第 3310 行

pub fn failingFileSetLength(userdata: ?*anyopaque, file: File, length: u64) File.SetLengthError!void

参数

userdata: ?*anyopaque
file: File
length: u64

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

FileBusy
FileTooBig
InputOutput
NonResizable
PermissionDenied
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingFileSetOwner

函数

第 3317 行

pub fn failingFileSetOwner(userdata: ?*anyopaque, file: File, owner: ?File.Uid, group: ?File.Gid) File.SetOwnerError!void

参数

userdata: ?*anyopaque
file: File
owner: ?File.Uid
group: ?File.Gid

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

FileNotFound
InputOutput
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingFileSetPermissions

函数

第 3325 行

pub fn failingFileSetPermissions(userdata: ?*anyopaque, file: File, permissions: File.Permissions) File.SetPermissionsError!void

参数

userdata: ?*anyopaque
file: File
permissions: File.Permissions

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

FileNotFound
InputOutput
PermissionDenied
ReadOnlyFileSystem
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingFileStat

函数

第 3213 行

pub fn failingFileStat(userdata: ?*anyopaque, file: File) File.StatError!File.Stat

参数

userdata: ?*anyopaque
file: File

错误

AccessDenied

在 WASI 中,当文件描述符不具备获取自身 filestat 信息所需的权限时,可能发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

PermissionDenied
Streaming

尝试对非文件流调用 stat。

SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingFileSync

函数

第 3286 行

pub fn failingFileSync(userdata: ?*anyopaque, file: File) File.SyncError!void

参数

userdata: ?*anyopaque
file: File

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

DiskQuota
InputOutput
NoSpaceLeft
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingFileTryLock

函数

第 3346 行

pub fn failingFileTryLock(userdata: ?*anyopaque, file: File, lock: File.Lock) File.LockError!bool

参数

userdata: ?*anyopaque
file: File
lock: File.Lock

错误

Canceled Cancelable

调用方请求停止异步操作。

FileLocksUnsupported
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingFileWritePositional

函数

第 3231 行

pub fn failingFileWritePositional(userdata: ?*anyopaque, file: File, header: []const u8, data: []const []const u8, splat: usize, offset: u64) File.WritePositionalError!usize

参数

userdata: ?*anyopaque
file: File
header: []const u8
data: []const []const u8
splat: usize
offset: u64

错误

AccessDenied

文件描述符没有写入所需的权限。

BrokenPipe

文件为未连接的套接字,或其读取端已关闭。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy
DiskQuota
FileBusy
FileTooBig
InputOutput
LockViolation

进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。

NoDevice

写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。

NoSpaceLeft
NotOpenForWriting

文件打开时没有写入能力。

PermissionDenied
SystemResources

内核内存不足,无法从 in_fd 读取。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable

无法对该文件按指定位置写入。

WouldBlock

已启用非阻塞模式,而此操作将阻塞。

std.Io.failingGroupConcurrent

函数

第 2911 行

pub fn failingGroupConcurrent( userdata: ?*anyopaque, group: *Group, context: []const u8, context_alignment: std.mem.Alignment, start: *const fn (context: *const anyopaque) void, ) ConcurrentError!void

参数

userdata: ?*anyopaque
group: *Group
context: []const u8
context_alignment: std.mem.Alignment
start: *const fn (context: *const anyopaque) void

错误

ConcurrencyUnavailable

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

std.Io.failingInheritParentDir

函数

第 3489 行

pub fn failingInheritParentDir(userdata: ?*anyopaque, handle: Dir.Handle) InheritParentHandleError!Dir

参数

userdata: ?*anyopaque
handle: Dir.Handle

错误

Canceled Cancelable

调用方请求停止异步操作。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnsupportedOperation

std.Io.failingInheritParentFile

函数

第 3495 行

pub fn failingInheritParentFile(userdata: ?*anyopaque, handle: File.Handle, flags: File.Flags) InheritParentHandleError!File

参数

userdata: ?*anyopaque
handle: File.Handle
flags: File.Flags

错误

Canceled Cancelable

调用方请求停止异步操作。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnsupportedOperation

std.Io.failingNetAccept

函数

第 3537 行

pub fn failingNetAccept(userdata: ?*anyopaque, listen_fd: net.Socket.Handle, options: net.Server.AcceptOptions) net.Server.AcceptError!net.Socket

参数

userdata: ?*anyopaque
listen_fd: net.Socket.Handle
options: net.Server.AcceptOptions

错误

BlockedByFirewall

防火墙规则禁止连接。

Canceled Cancelable

调用方请求停止异步操作。

ConnectionAborted

曾有传入连接,但在接受调用之前, 远端对等方已将其终止。

NetworkDown

网络子系统已失败。

ProcessFdQuotaExceeded

已达到每个进程可打开的文件描述符数量限制。

ProtocolFailure
SocketNotListening

从未调用 listen,或已调用 shutdown,后者可能发生于 本调用阻塞期间。因此,可将 shutdown 用作 并发取消机制。

SystemFdQuotaExceeded

已达到系统范围内打开文件总数的上限。

SystemResources

可用内存不足。这通常意味着内存分配受限于 套接字缓冲区上限,而非系统内存。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock

没有已排队且可立即接受的连接, 而套接字配置为非阻塞模式。

std.Io.failingNetBindIp

函数

第 3544 行

pub fn failingNetBindIp(userdata: ?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.BindOptions) net.IpAddress.BindError!net.Socket

参数

userdata: ?*anyopaque
address: *const net.IpAddress
options: net.IpAddress.BindOptions

错误

AccessDenied

该地址受到保护,当前用户没有绑定它的权限。

AddressFamilyUnsupported

该地址对于套接字的地址族无效。

AddressInUse

地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。

AddressUnavailable

请求了不存在的接口,或请求的地址不是本地地址。

Canceled Cancelable

调用方请求停止异步操作。

NetworkDown

用于到达目标的本地网络接口已离线。

OptionUnsupported

Io 实现不支持某个 BindOptions。

ProcessFdQuotaExceeded

已达到每进程可打开文件描述符数量上限。

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

已达到系统范围内已打开文件的总数上限。

SystemResources

操作系统内部内存或其他资源不足。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingNetConnectIp

函数

第 3551 行

pub fn failingNetConnectIp(userdata: ?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.ConnectOptions) net.IpAddress.ConnectError!net.Socket

参数

userdata: ?*anyopaque
address: *const net.IpAddress
options: net.IpAddress.ConnectOptions

错误

AccessDenied

用户尝试连接广播地址,但未启用套接字广播标志;或 连接请求因本地防火墙规则而失败。

AddressFamilyUnsupported
AddressUnavailable
Canceled Cancelable

调用方请求停止异步操作。

ConnectionPending
ConnectionRefused
ConnectionResetByPeer
HostUnreachable
NetworkDown
NetworkUnreachable
OptionUnsupported

Io 实现不支持某个 ConnectOptions 选项。

ProcessFdQuotaExceeded

已达到每进程可打开文件描述符数量上限。

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

已达到系统范围内已打开文件的总数上限。

SystemResources

操作系统内部内存或其他资源不足。

Timeout
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock

已请求非阻塞模式,但该操作无法立即返回。

std.Io.failingNetConnectUnix

函数

第 3565 行

pub fn failingNetConnectUnix(userdata: ?*anyopaque, address: *const net.UnixAddress) net.UnixAddress.ConnectError!net.Socket.Handle

参数

userdata: ?*anyopaque
address: *const net.UnixAddress

错误

AccessDenied
AddressFamilyUnsupported
Canceled Cancelable

调用方请求停止异步操作。

ConnectionRefused
FileNotFound
NetworkDown
NotDir
PermissionDenied
ProcessFdQuotaExceeded
ProtocolUnsupportedBySystem
ReadOnlyFileSystem
SocketModeUnsupported
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock

std.Io.failingNetInterfaceNameResolve

函数

第 3599 行

pub fn failingNetInterfaceNameResolve(userdata: ?*anyopaque, name: *const net.Interface.Name) net.Interface.Name.ResolveError!net.Interface

参数

userdata: ?*anyopaque
name: *const net.Interface.Name

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

InterfaceNotFound
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingNetListenIp

函数

第 3530 行

pub fn failingNetListenIp(userdata: ?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.ListenOptions) net.IpAddress.ListenError!net.Socket

参数

userdata: ?*anyopaque
address: *const net.IpAddress
options: net.IpAddress.ListenOptions

错误

AccessDenied

该地址受到保护,当前用户没有绑定它的权限。

AddressFamilyUnsupported

操作系统不支持请求的地址族(IPv4 或 IPv6)。

AddressInUse

地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。

AddressUnavailable

请求了不存在的接口,或请求的地址不是本地地址。

Canceled Cancelable

调用方请求停止异步操作。

NetworkDown

用于到达目标的本地网络接口已离线。

OptionUnsupported

Io 实现不支持某个 ListenOptions。

ProcessFdQuotaExceeded

已达到每进程可打开文件描述符数量上限。

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

已达到系统范围内已打开文件的总数上限。

SystemResources

操作系统内部内存或其他资源不足。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingNetListenUnix

函数

第 3558 行

pub fn failingNetListenUnix(userdata: ?*anyopaque, address: *const net.UnixAddress, options: net.UnixAddress.ListenOptions) net.UnixAddress.ListenError!net.Socket.Handle

参数

userdata: ?*anyopaque
address: *const net.UnixAddress
options: net.UnixAddress.ListenOptions

错误

AccessDenied
AddressFamilyUnsupported
AddressInUse
AddressUnavailable
Canceled Cancelable

调用方请求停止异步操作。

FileNotFound
NetworkDown
NotDir
PermissionDenied
ProcessFdQuotaExceeded
ReadOnlyFileSystem
SymLinkLoop
SystemFdQuotaExceeded
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingNetLookup

函数

第 3611 行

pub fn failingNetLookup(userdata: ?*anyopaque, host_name: net.HostName, resolved: *Queue(net.HostName.LookupResult), options: net.HostName.LookupOptions) net.HostName.LookupError!void

参数

userdata: ?*anyopaque
host_name: net.HostName
resolved: *Queue(net.HostName.LookupResult)
options: net.HostName.LookupOptions

错误

AccessDenied BindError

该地址受到保护,当前用户没有绑定它的权限。

AddressFamilyUnsupported BindError

该地址对于套接字的地址族无效。

AddressInUse BindError

地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。

AddressUnavailable BindError

请求了不存在的接口,或请求的地址不是本地地址。

Canceled Cancelable

调用方请求停止异步操作。

DetectingNetworkConfigurationFailed

无法打开或读取 "/etc/hosts" 或 "/etc/resolv.conf"。

InvalidDnsAAAARecord
InvalidDnsARecord
InvalidDnsCnameRecord
NameServerFailure
NetworkDown BindError

用于到达目标的本地网络接口已离线。

NoAddressReturned
OptionUnsupported BindError

Io 实现不支持某个 BindOptions。

ProcessFdQuotaExceeded BindError

已达到每进程可打开文件描述符数量上限。

ProtocolUnsupportedByAddressFamily BindError
ProtocolUnsupportedBySystem BindError
ResolvConfParseFailed
SocketModeUnsupported BindError
SystemFdQuotaExceeded BindError

已达到系统范围内已打开文件的总数上限。

SystemResources BindError

操作系统内部内存或其他资源不足。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnknownHostName

std.Io.failingNetShutdown

函数

第 3592 行

pub fn failingNetShutdown(userdata: ?*anyopaque, handle: net.Socket.Handle, how: net.ShutdownHow) net.ShutdownError!void

参数

userdata: ?*anyopaque
handle: net.Socket.Handle
how: net.ShutdownHow

错误

Canceled Cancelable

调用方请求停止异步操作。

ConnectionAborted
ConnectionResetByPeer
NetworkDown
SocketUnconnected
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingNetSocketCreatePair

函数

第 3571 行

pub fn failingNetSocketCreatePair(userdata: ?*anyopaque, options: net.Socket.CreatePairOptions) net.Socket.CreatePairError![2]net.Socket

参数

userdata: ?*anyopaque
options: net.Socket.CreatePairOptions

错误

AccessDenied
AddressFamilyUnsupported
Canceled Cancelable

调用方请求停止异步操作。

OperationUnsupported
ProcessFdQuotaExceeded

已达到每个进程可打开的文件描述符数量限制。

ProtocolUnsupportedByAddressFamily
ProtocolUnsupportedBySystem
SocketModeUnsupported
SystemFdQuotaExceeded

已达到系统范围内打开文件总数的上限。

SystemResources

可用内存不足。在释放足够资源前, 无法创建套接字。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingNetWriteFile

函数

第 3577 行

pub fn failingNetWriteFile(userdata: ?*anyopaque, handle: net.Socket.Handle, header: []const u8, file_reader: *Io.File.Reader, limit: Io.Limit) net.Stream.Writer.WriteFileError!usize

参数

userdata: ?*anyopaque
handle: net.Socket.Handle
header: []const u8
file_reader: *Io.File.Reader
limit: Io.Limit

错误

AddressFamilyUnsupported Error

传入地址的 sa_family 字段未包含正确的地址族。

Canceled Cancelable

调用方请求停止异步操作。

ConnectionRefused Error

目标地址未在监听。

ConnectionResetByPeer Error

网络会话被接收方意外关闭。

ConnectionTimedOut Error

远端对等方未响应正在进行的通信,导致 操作系统中止连接。

EndOfStream

已到达正在读取的文件末尾。

FastOpenAlreadyInProgress Error

另一个 TCP 快速打开已在进行。

HostUnreachable Error

可到达网络,但没有到主机的路由。

NetworkDown Error

用于到达目标的本地网络接口已关闭。

NetworkUnreachable Error

没有到网络的路由。

ReadFailed

源 File.Reader 失败; 详细诊断信息见该结构体。

SocketNotBound Error
SocketUnconnected Error

面向连接的套接字的本地端已关闭,或 该套接字从未连接。

SystemResources Error

网络接口的输出队列已满。这通常表示 接口已停止发送,但也可能由短暂拥塞导致。通常, Linux 不会发生此错误;设备队列溢出时只会 静默丢弃分组。

可用内核内存不足时也会发生此错误。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unimplemented

Io 实现无法提供更高效的文件到套接字传输路径; 调用者应退回基于读取的复制。参见 Io.Writer.sendFile。

std.Io.failingOperate

函数

第 2973 行

pub fn failingOperate(userdata: ?*anyopaque, operation: Operation) Cancelable!Operation.Result

参数

userdata: ?*anyopaque
operation: Operation

错误

Canceled

调用方请求停止异步操作。

std.Io.failingProcessCurrentPath

函数

第 3442 行

pub fn failingProcessCurrentPath(userdata: ?*anyopaque, buffer: []u8) std.process.CurrentPathError!usize

参数

userdata: ?*anyopaque
buffer: []u8

错误

Canceled Cancelable

调用方请求停止异步操作。

CurrentDirUnlinked

在 Windows 上不可能发生。在 WASI 上始终返回。

NameTooLong

缓冲区过小,无法容纳当前路径。

PathExceedsLimit

受底层 libc 或系统调用实现限制,无法获取当前路径。换用更大缓冲区重试也不会成功。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingProcessExecutableOpen

函数

第 3413 行

pub fn failingProcessExecutableOpen(userdata: ?*anyopaque, flags: Dir.OpenFileOptions) std.process.OpenExecutableError!File

参数

userdata: ?*anyopaque
flags: Dir.OpenFileOptions

错误

AccessDenied OpenError

在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。

AntivirusInterference OpenError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy OpenError
FileBusy OpenError

以下三种情况之一:

  • pathname 指向正在执行的可执行映像, 且请求写访问。
  • pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
  • pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
FileLocksUnsupported OpenError
FileNotFound OpenError

以下任一情况:

  • 某个路径分量不存在。
  • 使用了当前工作目录,但该目录已被删除。
  • 已打开目录句柄所关联的路径已被删除。
  • macOS 上,多个进程或线程将 O.EXCL 设为 false,并发争相创建同一文件。
FileSystem ExecutablePathBaseError
FileTooBig OpenError

文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。

InputOutput ExecutablePathBaseError
IsDir OpenError

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound OpenError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice OpenError
NoSpaceLeft OpenError

设备没有空间容纳新文件,无法创建新路径。 仅在提供 CREAT 标志时才可能出现此错误。

NotDir OpenError

路径中用作目录的某个部分实际上不是目录, 或者指定了 DIRECTORY,但路径不是目录。

NotLink ExecutablePathBaseError
OperationUnsupported ExecutablePathBaseError

操作系统不支持可执行文件获取自身 路径。

PathAlreadyExists OpenError

路径已存在,且提供了 CREAT 和 EXCL 标志。

PermissionDenied OpenError
PipeBusy OpenError
ProcessFdQuotaExceeded OpenError
ProcessNotFound ExecutablePathBaseError
ReadOnlyFileSystem OpenError
SymLinkLoop OpenError
SystemFdQuotaExceeded OpenError
SystemResources OpenError

路径超过 max_path_bytes 字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnrecognizedVolume ExecutablePathBaseError

在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。

WouldBlock OpenError

已请求非阻塞模式,但该操作无法立即返回。

std.Io.failingProcessExecutablePath

函数

第 3419 行

pub fn failingProcessExecutablePath(userdata: ?*anyopaque, buffer: []u8) std.process.ExecutablePathError!usize

参数

userdata: ?*anyopaque
buffer: []u8

错误

AccessDenied ExecutablePathBaseError
AntivirusInterference ExecutablePathBaseError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName ExecutablePathBaseError
Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy ExecutablePathBaseError
FileNotFound ExecutablePathBaseError
FileSystem ExecutablePathBaseError
FileTooBig ExecutablePathBaseError
InputOutput ExecutablePathBaseError
IsDir ExecutablePathBaseError
NameTooLong
NetworkNotFound ExecutablePathBaseError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice ExecutablePathBaseError
NoSpaceLeft ExecutablePathBaseError
NotDir ExecutablePathBaseError
NotLink ExecutablePathBaseError
OperationUnsupported ExecutablePathBaseError

操作系统不支持可执行文件获取自身 路径。

PathAlreadyExists ExecutablePathBaseError
PermissionDenied ExecutablePathBaseError
PipeBusy ExecutablePathBaseError
ProcessFdQuotaExceeded ExecutablePathBaseError
ProcessNotFound ExecutablePathBaseError
SymLinkLoop ExecutablePathBaseError
SystemFdQuotaExceeded ExecutablePathBaseError
SystemResources ExecutablePathBaseError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnrecognizedVolume ExecutablePathBaseError

在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。

std.Io.failingProcessReplace

函数

第 3460 行

pub fn failingProcessReplace(userdata: ?*anyopaque, options: std.process.ReplaceOptions) std.process.ReplaceError

参数

userdata: ?*anyopaque
options: std.process.ReplaceOptions

std.Io.failingProcessSetCurrentDir

函数

第 3448 行

pub fn failingProcessSetCurrentDir(userdata: ?*anyopaque, dir: Dir) std.process.SetCurrentDirError!void

参数

userdata: ?*anyopaque
dir: Dir

错误

AccessDenied
BadPathName
Canceled Cancelable

调用方请求停止异步操作。

FileNotFound
FileSystem
NameTooLong
NoDevice
NotDir
OperationUnsupported
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnrecognizedVolume

std.Io.failingProcessSetCurrentPath

函数

第 3454 行

pub fn failingProcessSetCurrentPath(userdata: ?*anyopaque, path: []const u8) std.process.SetCurrentPathError!void

参数

userdata: ?*anyopaque
path: []const u8

错误

AccessDenied
BadPathName
Canceled Cancelable

调用方请求停止异步操作。

FileNotFound
FileSystem
InvalidWtf8

仅限 Windows。路径不是有效的 WTF-8。 https://wtf-8.codeberg.page/

NameTooLong
NoDevice
NotDir
OperationUnsupported
SymLinkLoop
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.failingProcessSpawn

函数

第 3466 行

pub fn failingProcessSpawn(userdata: ?*anyopaque, options: std.process.SpawnOptions) std.process.SpawnError!std.process.Child

参数

userdata: ?*anyopaque
options: std.process.SpawnOptions

错误

AccessDenied OpenError

在 WASI 中,若文件描述符不具有相对于它 打开新资源所需的权限,可能发生此错误。

AntivirusInterference OpenError

Windows 默认启用杀毒软件。虽然可以禁用,但 Windows Update 有时会忽略用户偏好并重新启用。 启用时,Windows 上的杀毒软件会拦截文件系统操作,使其显著变慢,也可能导致操作因该错误码失败。

BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy OpenError
FileBusy OpenError

以下三种情况之一:

  • pathname 指向正在执行的可执行映像, 且请求写访问。
  • pathname 指向当前用作交换 文件的文件,且指定了 O_TRUNC 标志。
  • pathname 指向内核正在读取的文件, 例如用于加载模块或固件,且请求 写访问。
FileLocksUnsupported OpenError
FileNotFound OpenError

以下任一情况:

  • 某个路径分量不存在。
  • 使用了当前工作目录,但该目录已被删除。
  • 已打开目录句柄所关联的路径已被删除。
  • macOS 上,多个进程或线程将 O.EXCL 设为 false,并发争相创建同一文件。
FileSystem
FileTooBig OpenError

文件过大,无法打开。对于 64 位目标及打开目录的情况,此错误不可达。

InvalidBatchScriptArg

仅限 Windows。执行 .bat 或 .cmd 脚本时,参数中不允许 NUL(U+0000)、LF(U+000A)和 CR(U+000D)。

  • NUL 与 LF 表示参数结束,其后的内容在执行后会丢失。
  • CR 会被 cmd.exe 移除,因此执行后所有 CR 码点都会丢失。
InvalidExe
InvalidName
InvalidProcessGroupId
InvalidUserId
InvalidWtf8

仅限 Windows。提供的 cwd 或 argv 为无效 WTF-8。 https://wtf-8.codeberg.page/

IsDir OpenError

以下任一情况:

  • 路径指向目录,但请求了写权限。
  • 路径指向目录,但 allow_directory 被设为 false。
NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

NetworkNotFound OpenError

在 Windows 上,未找到 \\server 或 \\server\share。

NoDevice

仅限 POSIX。选择了 StdIo.ignore,且打开 /dev/null 时返回 ENODEV。

NoSpaceLeft OpenError

设备没有空间容纳新文件,无法创建新路径。 仅在提供 CREAT 标志时才可能出现此错误。

NotDir OpenError

路径中用作目录的某个部分实际上不是目录, 或者指定了 DIRECTORY,但路径不是目录。

OperationUnsupported

操作系统不支持创建子进程。

OutOfMemory
PathAlreadyExists OpenError

路径已存在,且提供了 CREAT 和 EXCL 标志。

PermissionDenied
PipeBusy OpenError
ProcessAlreadyExec

尝试更改调用进程某个子进程的 进程组 ID,但该子进程已经执行 映像替换。

ProcessFdQuotaExceeded
ReadOnlyFileSystem OpenError
ResourceLimitReached
SymLinkLoop
SystemFdQuotaExceeded
SystemResources OpenError

路径超过 max_path_bytes 字节。 可用内核内存不足;或者 指定文件为 FIFO,且达到每用户 管道内存分配的硬限制。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnrecognizedVolume

在 Windows 上,卷不包含可识别的文件系统。文件 系统驱动可能未加载,或卷可能已损坏。

WouldBlock OpenError

已请求非阻塞模式,但该操作无法立即返回。

std.Io.failingProgressParentFile

函数

第 3484 行

pub fn failingProgressParentFile(userdata: ?*anyopaque) std.Progress.ParentFileError!File

参数

userdata: ?*anyopaque

错误

EnvironmentVariableMissing
UnrecognizedFormat
UnsupportedOperation

std.Io.failingRandomSecure

函数

第 3507 行

pub fn failingRandomSecure(userdata: ?*anyopaque, buffer: []u8) RandomSecureError!void

参数

userdata: ?*anyopaque
buffer: []u8

错误

Canceled Cancelable

调用方请求停止异步操作。

EntropyUnavailable

std.Io.fiber

别名

第 30 行

别名目标 std.Io.fiber

std.Io.File

别名

第 45 行

别名目标 std.Io.File

std.Io.foo

变量

第 3630 行

usize

std.Io.futexWait

函数

第 1681 行

原子检查 ptr 处的值是否等于 expected;如果相等,则阻塞,直到:

  • 发生匹配的、即 ptr 参数相同的 futexWake 调用;或
  • 发生伪唤醒,即“随机”唤醒。

通常应在更新 ptr.* 处的值后立即调用 futexWake, 以解除使用 futexWait 等待该值变化的任务的阻塞。

必要时由调用方负责识别伪唤醒,通常通过检查 ptr.* 处的值来完成。

断言 T 的长度为 4 字节,且布局明确、不含填充位。

pub fn futexWait(io: Io, comptime T: type, ptr: *align(@alignOf(u32)) const T, expected: T) Cancelable!void

参数

io: Io
T: type
ptr: *align(@alignOf(u32)) const T
expected: T

错误

Canceled

调用方请求停止异步操作。

std.Io.futexWaitTimeout

函数

第 1687 行

与 futexWait 相同,但 timeout 到期时也会解除阻塞。与 futexWait 一样, 可能发生伪唤醒。若有必要,调用者仍负责区分这三种 可能的唤醒原因。

pub fn futexWaitTimeout(io: Io, comptime T: type, ptr: *align(@alignOf(u32)) const T, expected: T, timeout: Timeout) Cancelable!void

参数

io: Io
T: type
ptr: *align(@alignOf(u32)) const T
expected: T
timeout: Timeout

错误

Canceled

调用方请求停止异步操作。

std.Io.futexWaitUncancelable

函数

第 1697 行

与 futexWait 相同,但不引入取消点。

取消及取消点的说明见 Future.cancel。

pub fn futexWaitUncancelable(io: Io, comptime T: type, ptr: *align(@alignOf(u32)) const T, expected: T) void

参数

io: Io
T: type
ptr: *align(@alignOf(u32)) const T
expected: T

std.Io.futexWake

函数

第 1705 行

解除对 ptr 的待处理 futex 等待,最多解除 max_waiters 个调用。

pub fn futexWake(io: Io, comptime T: type, ptr: *align(@alignOf(u32)) const T, max_waiters: u32) void

参数

io: Io
T: type
ptr: *align(@alignOf(u32)) const T
max_waiters: u32

std.Io.Future

类型函数

第 1296 行

pub fn Future(Result: type) type

参数

Result: type

字段

any_future: ?*AnyFuture
result: Result

std.Io.Future.await

函数

第 1319 行

幂等。非线程安全。

pub fn await(f: *@This(), io: Io) Result

参数

f: *@This()
io: Io

std.Io.Future.cancel

函数

第 1311 行

等同于 await,但会发出取消请求。这使任务在下一个 “取消点”(若存在)收到 error.Canceled。取消点是 对 Io 中可返回 error.Canceled 的函数的调用。

请求取消任务后,仅该任务的下一个取消点 返回 error.Canceled,后续取消点不会再次发出取消信号。因此, 忽略 error.Canceled 通常是错误。若要推迟处理取消 请求,另请参见 recancel 和 CancelProtection。

幂等。非线程安全。

pub fn cancel(f: *@This(), io: Io) Result

参数

f: *@This()
io: Io

std.Io.Group

容器

第 1338 行

无序任务集合,只能整体等待或取消。 通过 Group.async 和 Group.concurrent 在组中生成任务。

保证每个任务关联的资源会在 该任务返回时释放,而不必等整个组完成或 被等待。因此,对于长时间存在且不断加入 并发任务的组,这不属于资源泄漏。但异步 任务只有在调用 Group.await 或 Group.cancel 后才保证 运行,因此不断加入异步任务却从不等待该组,可能 泄漏资源。

字段

token: std.atomic.Value(?*anyopaque)

此值表示组中是否有待处理任务。null 表示没有待处理任务,也没有与组关联的资源, 因此 await 和 cancel 会直接返回, 不调用具体实现。这意味着必须原子访问 token, 以免与 await 和 cancel 中的检查产生竞态条件。

state: usize

实现可以自由使用此值。

std.Io.Group.async

函数

第 1363 行

等同于 Io.async,但任务生成于此 Group 中, 而非与 Future 关联。

function 的返回类型必须可强制转换为 Cancelable!void。 function 返回 error.Canceled 不会产生任何作用,因为这里是 取消传播的边界。

一旦调用此函数,就会有资源关联到 该组。为释放这些资源,最终必须调用 await 或 cancel。

function 只有在调用 await 或 cancel 后才保证已被调用。

pub fn async(g: *Group, io: Io, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function))) void

参数

g: *Group
io: Io
args: std.meta.ArgsTuple(@TypeOf(function))

std.Io.Group.async.start

函数

第 1366 行

fn start(context: *const anyopaque) void

参数

context: *const anyopaque

std.Io.Group.await

函数

第 1408 行

阻塞至组内所有任务结束。此期间, 取消请求会传播至组内所有成员, 并使组最终完成时 返回 error.Canceled。

此函数返回后,保证 Group 中所有通过 async 或 concurrent 创建的任务均已运行。

幂等。不保证线程安全。

可以安全地与 Group.async 或 Group.concurrent 并发调用,但必须确保该组直到 Group.async 或 Group.concurrent 调用返回后才完成。

pub fn await(g: *Group, io: Io) Cancelable!void

参数

g: *Group
io: Io

错误

Canceled

调用方请求停止异步操作。

std.Io.Group.cancel

函数

第 1427 行

等同于 await,但立即请求取消组内 全部成员。

此函数返回后,保证 Group 中所有通过 async 或 concurrent 创建的任务均已运行。

取消及取消点的说明参见 Future.cancel。

幂等。不保证线程安全。

可以安全地与 Group.async 或 Group.concurrent 并发调用,但必须确保该组直到 Group.async 或 Group.concurrent 调用返回后才完成。

pub fn cancel(g: *Group, io: Io) void

参数

g: *Group
io: Io

std.Io.Group.concurrent

函数

第 1384 行

等同于 Io.concurrent,但任务创建在此 Group 中,而不是与 Future 关联。

function 的返回类型必须可强制转换为 Cancelable!void。 function 返回 error.Canceled 不会执行额外操作,因为这里是 取消传播边界。

调用此函数后,就有资源与该组 关联。要释放这些资源,最终必须 调用 Group.await 或 Group.cancel。

pub fn concurrent(g: *Group, io: Io, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function))) ConcurrentError!void

参数

g: *Group
io: Io
args: std.meta.ArgsTuple(@TypeOf(function))

错误

ConcurrencyUnavailable

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

std.Io.Group.concurrent.start

函数

第 1387 行

fn start(context: *const anyopaque) void

参数

context: *const anyopaque

std.Io.Group.init

常量

第 1348 行

Group

std.Io.InheritParentHandleError

错误集合

第 832 行

错误

Canceled Cancelable

调用方请求停止异步操作。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

UnsupportedOperation

std.Io.Io

别名

第 15 行

别名目标 std.Io

std.Io.Kqueue

别名

第 38 行

别名目标 std.Io.Kqueue

std.Io.Limit

容器

第 730 行

字段

nothing = 0
unlimited = math.maxInt(usize)
_

std.Io.Limit.countVec

函数

第 746 行

pub fn countVec(data: []const []const u8) Limit

参数

data: []const []const u8

std.Io.Limit.limited

函数

第 736 行

math.maxInt(usize) 被解释为 .unlimited。

pub fn limited(n: usize) Limit

参数

n: usize

std.Io.Limit.limited64

函数

第 742 行

大于 math.maxInt(usize) 的任何值均被解释为 .unlimited。

pub fn limited64(n: u64) Limit

参数

n: u64

std.Io.Limit.max

函数

第 756 行

pub fn max(a: Limit, b: Limit) Limit

参数

a: Limit
b: Limit

std.Io.Limit.min

函数

第 752 行

pub fn min(a: Limit, b: Limit) Limit

参数

a: Limit
b: Limit

std.Io.Limit.minInt

函数

第 764 行

pub fn minInt(l: Limit, n: usize) usize

参数

l: Limit
n: usize

std.Io.Limit.minInt64

函数

第 768 行

pub fn minInt64(l: Limit, n: u64) usize

参数

l: Limit
n: u64

std.Io.Limit.nonzero

函数

第 802 行

pub fn nonzero(l: Limit) bool

参数

l: Limit

std.Io.Limit.slice

函数

第 772 行

pub fn slice(l: Limit, s: []u8) []u8

参数

l: Limit
s: []u8

std.Io.Limit.slice1

函数

第 797 行

根据限制缩短切片,但在限制之外额外保留 一个字节的空间,以便区分 到达流末尾与达到限制这两种情况。

pub fn slice1(l: Limit, non_empty_buffer: []u8) []u8

参数

l: Limit
non_empty_buffer: []u8

std.Io.Limit.sliceConst

函数

第 776 行

pub fn sliceConst(l: Limit, s: []const u8) []const u8

参数

l: Limit
s: []const u8

std.Io.Limit.subtract

函数

第 808 行

返回减去 amount 后的新限制, 或返回 null 表示将超出限制。

pub fn subtract(l: Limit, amount: usize) ?Limit

参数

l: Limit
amount: usize

std.Io.Limit.toInt

函数

第 780 行

pub fn toInt(l: Limit) ?usize

参数

l: Limit

std.Io.Limit.toInt64

函数

第 787 行

pub fn toInt64(l: Limit) ?u64

参数

l: Limit

std.Io.LockedStderr

容器

第 2610 行

字段

file_writer: *File.Writer
terminal_mode: Terminal.Mode

std.Io.LockedStderr.clear

函数

第 2621 行

pub fn clear(ls: LockedStderr, buffer: []u8) Cancelable!void

参数

ls: LockedStderr
buffer: []u8

错误

Canceled

调用方请求停止异步操作。

std.Io.LockedStderr.terminal

函数

第 2614 行

pub fn terminal(ls: LockedStderr) Terminal

参数

std.Io.lockStderr

函数

第 2645 行

用于在应用层向标准错误流写入。 也会与不了解 Io 接口及其实现的 调试层写入操作协调。

另见:

pub fn lockStderr(io: Io, buffer: []u8, terminal_mode: ?Terminal.Mode) Cancelable!LockedStderr

参数

io: Io
buffer: []u8
terminal_mode: ?Terminal.Mode

错误

Canceled

调用方请求停止异步操作。

std.Io.math

别名

第 20 行

别名目标 std.math

std.Io.Mutex

容器

第 1716 行

Mutex 是一种同步原语,确保对称为“临界区”的 共享代码区域进行原子访问。

Mutex 是 extern 结构体,因此可用作另一个 extern 结构体的字段。

字段

state: std.atomic.Value(State)

std.Io.Mutex.init

常量

第 1719 行

Mutex

std.Io.Mutex.lock

函数

第 1731 行

pub fn lock(m: *Mutex, io: Io) Cancelable!void

参数

m: *Mutex
io: Io

错误

Canceled

调用方请求停止异步操作。

std.Io.Mutex.lockUncancelable

函数

第 1752 行

与 lock 相同,但不引入取消点。

取消及取消点的说明见 Future.cancel。

pub fn lockUncancelable(m: *Mutex, io: Io) void

参数

m: *Mutex
io: Io

std.Io.Mutex.State

容器

第 1721 行

字段

unlocked
locked_once
contended

std.Io.Mutex.tryLock

函数

第 1727 行

pub fn tryLock(m: *Mutex) bool

参数

m: *Mutex

std.Io.Mutex.unlock

函数

第 1770 行

pub fn unlock(m: *Mutex, io: Io) void

参数

m: *Mutex
io: Io

std.Io.net

别名

第 43 行

别名目标 std.Io.net

std.Io.noAsync

函数

第 2847 行

pub fn noAsync(userdata: ?*anyopaque, result: []u8, result_alignment: std.mem.Alignment, context: []const u8, context_alignment: std.mem.Alignment, start: *const fn (context: *const anyopaque, result: *anyopaque) void) ?*AnyFuture

参数

userdata: ?*anyopaque
result: []u8
result_alignment: std.mem.Alignment
context: []const u8
context_alignment: std.mem.Alignment
start: *const fn (context: *const anyopaque, result: *anyopaque) void

std.Io.noCrashHandler

函数

第 2843 行

pub fn noCrashHandler(userdata: ?*anyopaque) void

参数

userdata: ?*anyopaque

std.Io.noDirRead

函数

第 3090 行

pub fn noDirRead(userdata: ?*anyopaque, dir_reader: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize

参数

userdata: ?*anyopaque
dir_reader: *Dir.Reader
buffer: []Dir.Entry

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

PermissionDenied
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.noDirSetTimestamps

函数

第 3195 行

pub fn noDirSetTimestamps(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.SetTimestampsOptions) Dir.SetTimestampsError!void

参数

userdata: ?*anyopaque
dir: Dir
sub_path: []const u8
options: Dir.SetTimestampsOptions

错误

AccessDenied SetTimestampsError

times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:

  • 调用方的有效用户标识符与文件 所有者不匹配,调用方不具有该文件的 写入权限,且调用方不具有特权;Linux 上即不具备 CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力; 或者,
  • 文件被标记为不可变,参见 chattr(1)。
BadPathName PathNameError

文件系统无法编码请求的文件名字节。 原因可能是 Windows 上无效的 WTF-8、WASI 上无效的 UTF-8、 Windows 上的无效字符等,具体取决于文件系统与操作系统。

Canceled Cancelable

调用方请求停止异步操作。

NameTooLong PathNameError

提供的缓冲区过小, 无法容纳路径名时返回。

PermissionDenied SetTimestampsError

调用方尝试将一个或两个时间戳设置为当前时间 以外的值,或将一个时间戳 设为当前时间而保持另一个不变, 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW, 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:

  • 调用方的有效用户 ID 不等于文件 所有者,且调用方无特权;Linux 上 指不具备 CAP_FOWNER 能力。
  • 文件被标记为仅追加或不可变,参见 chattr(1)。
ReadOnlyFileSystem SetTimestampsError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.noFileSetTimestamps

函数

第 3332 行

pub fn noFileSetTimestamps(userdata: ?*anyopaque, file: File, options: File.SetTimestampsOptions) File.SetTimestampsError!void

参数

userdata: ?*anyopaque
file: File
options: File.SetTimestampsOptions

错误

AccessDenied

times 为 NULL,或两个 nsec 值均为 UTIME_NOW,且满足以下之一:

  • 调用方的有效用户标识符与文件 所有者不匹配,调用方不具有该文件的 写入权限,且调用方不具有特权;Linux 上即不具备 CAP_FOWNER 或 CAP_DAC_OVERRIDE 任一能力; 或者,
  • 文件被标记为不可变,参见 chattr(1)。
Canceled Cancelable

调用方请求停止异步操作。

PermissionDenied

调用方尝试将一个或两个时间戳设置为当前时间 以外的值,或将一个时间戳 设为当前时间而保持另一个不变, 即 times 非 NULL,两个 nsec 字段均非 UTIME_NOW, 且两个 nsec 字段均非 UTIME_OMIT,同时满足以下任一条件:

  • 调用方的有效用户 ID 不等于文件 所有者,且调用方无特权;Linux 上 指不具备 CAP_FOWNER 能力。
  • 文件被标记为仅追加或不可变,参见 chattr(1)。
ReadOnlyFileSystem
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.noFileWriteFilePositional

函数

第 3252 行

pub fn noFileWriteFilePositional(userdata: ?*anyopaque, file: File, header: []const u8, file_reader: *Io.File.Reader, limit: Io.Limit, offset: u64) File.WriteFilePositionalError!usize

参数

userdata: ?*anyopaque
file: File
header: []const u8
file_reader: *Io.File.Reader
limit: Io.Limit
offset: u64

错误

AccessDenied Error

文件描述符没有写入所需的权限。

BrokenPipe Error

文件为未连接的套接字,或其读取端已关闭。

Canceled Cancelable

调用方请求停止异步操作。

CorruptedData WriteFileError

在 FreeBSD 上使用 copy_file_range 时可能发生。

DeviceBusy Error
DiskQuota Error
EndOfStream WriteFileError
FileBusy Error
FileTooBig Error
InputOutput Error
LockViolation Error

进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。

NoDevice Error

写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
ReadFailed WriteFileError
SystemResources Error

内核内存不足,无法从 in_fd 读取。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unimplemented WriteFileError

描述符无效或已锁定,或 in_fd 不支持类似 mmap(2) 的操作。

Unseekable
WouldBlock Error

已启用非阻塞模式,而此操作将阻塞。

std.Io.noFileWriteFileStreaming

函数

第 3243 行

pub fn noFileWriteFileStreaming(userdata: ?*anyopaque, file: File, header: []const u8, file_reader: *Io.File.Reader, limit: Io.Limit) File.Writer.WriteFileError!usize

参数

userdata: ?*anyopaque
file: File
header: []const u8
file_reader: *Io.File.Reader
limit: Io.Limit

错误

AccessDenied Error

文件描述符没有写入所需的权限。

BrokenPipe Error

文件为未连接的套接字,或其读取端已关闭。

Canceled Cancelable

调用方请求停止异步操作。

CorruptedData

在 FreeBSD 上使用 copy_file_range 时可能发生。

DeviceBusy Error
DiskQuota Error
EndOfStream
FileBusy Error
FileTooBig Error
InputOutput Error
LockViolation Error

进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。

NoDevice Error

写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。

NoSpaceLeft Error
NotOpenForWriting Error
PermissionDenied Error
ReadFailed
SystemResources Error

内核内存不足,无法从 in_fd 读取。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unimplemented

描述符无效或已锁定,或 in_fd 不支持类似 mmap(2) 的操作。

WouldBlock Error

已启用非阻塞模式,而此操作将阻塞。

std.Io.noFutexWait

函数

第 2956 行

pub fn noFutexWait(userdata: ?*anyopaque, ptr: *const u32, expected: u32, timeout: Timeout) Cancelable!void

参数

userdata: ?*anyopaque
ptr: *const u32
expected: u32
timeout: Timeout

错误

Canceled

调用方请求停止异步操作。

std.Io.noFutexWaitUncancelable

函数

第 2961 行

pub fn noFutexWaitUncancelable(userdata: ?*anyopaque, ptr: *const u32, expected: u32) void

参数

userdata: ?*anyopaque
ptr: *const u32
expected: u32

std.Io.noFutexWake

函数

第 2966 行

pub fn noFutexWake(userdata: ?*anyopaque, ptr: *const u32, max_waiters: u32) void

参数

userdata: ?*anyopaque
ptr: *const u32
max_waiters: u32

std.Io.noGroupAsync

函数

第 2898 行

pub fn noGroupAsync( userdata: ?*anyopaque, group: *Group, context: []const u8, context_alignment: std.mem.Alignment, start: *const fn (context: *const anyopaque) void, ) void

参数

userdata: ?*anyopaque
group: *Group
context: []const u8
context_alignment: std.mem.Alignment
start: *const fn (context: *const anyopaque) void

std.Io.noNow

函数

第 3513 行

pub fn noNow(userdata: ?*anyopaque, clock: Clock) Timestamp

参数

userdata: ?*anyopaque
clock: Clock

std.Io.noRandom

函数

第 3502 行

pub fn noRandom(userdata: ?*anyopaque, buffer: []u8) void

参数

userdata: ?*anyopaque
buffer: []u8

std.Io.noSleep

函数

第 3525 行

pub fn noSleep(userdata: ?*anyopaque, clock: Timeout) Cancelable!void

参数

userdata: ?*anyopaque
clock: Timeout

错误

Canceled

调用方请求停止异步操作。

std.Io.noTryLockStderr

函数

第 3431 行

pub fn noTryLockStderr(userdata: ?*anyopaque, terminal_mode: ?Terminal.Mode) Cancelable!?LockedStderr

参数

userdata: ?*anyopaque
terminal_mode: ?Terminal.Mode

错误

Canceled

调用方请求停止异步操作。

std.Io.operate

函数

第 555 行

执行一个 Operation。

pub fn operate(io: Io, operation: Operation) Cancelable!Operation.Result

参数

io: Io
operation: Operation

错误

Canceled

调用方请求停止异步操作。

std.Io.operateTimeout

函数

第 562 行

使用给定 timeout 执行一个 Operation。

pub fn operateTimeout(io: Io, operation: Operation, timeout: Timeout) OperateTimeoutError!Operation.Result

参数

io: Io
operation: Operation
timeout: Timeout

错误

Canceled Cancelable

调用方请求停止异步操作。

ConcurrencyUnavailable ConcurrentError

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

Timeout Error

std.Io.OperateTimeoutError

错误集合

第 559 行

错误

Canceled Cancelable

调用方请求停止异步操作。

ConcurrencyUnavailable ConcurrentError

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

Timeout Error

std.Io.Operation

容器

第 246 行

字段

file_read_streaming: FileReadStreaming
file_write_streaming: FileWriteStreaming
device_io_control: DeviceIoControl

Windows 上为 NtDeviceIoControlFile,POSIX 上为 ioctl。 其他系统上此标签不可达。

net_receive: NetReceive
net_send: NetSend
net_read: NetRead
net_write: NetWrite

std.Io.Operation.DeviceIoControl

类型

第 323 行

std.Io.Operation.DeviceIoControl.Result

别名

第 331 行

别名目标 std.os.windows.IO_STATUS_BLOCK

std.Io.Operation.DeviceIoControl.Result

类型

第 341 行

取决于设备及操作的结果。负值是 取负的 errno。

std.Io.Operation.FileReadStreaming

容器

第 260 行

读取可能返回 0,这与 error.EndOfStream 不同。

字段

file: File
data: []const []u8

std.Io.Operation.FileReadStreaming.Error

错误集合

第 264 行

错误

AccessDenied UnendingError

在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。

ConnectionResetByPeer UnendingError
EndOfStream
InputOutput UnendingError
IsDir UnendingError

尝试将目录文件描述符当作普通文件读取。

LockViolation UnendingError

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading UnendingError

打开文件时未授予读取能力。

SocketUnconnected UnendingError
SystemResources UnendingError
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock UnendingError

已启用非阻塞模式,且从该文件描述符读取会阻塞。

std.Io.Operation.FileReadStreaming.Result

常量

第 286 行

std.Io.Operation.FileReadStreaming.UnendingError

错误集合

第 265 行

错误

AccessDenied

在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。

ConnectionResetByPeer
InputOutput
IsDir

尝试将目录文件描述符当作普通文件读取。

LockViolation

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading

打开文件时未授予读取能力。

SocketUnconnected
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock

已启用非阻塞模式,且从该文件描述符读取会阻塞。

std.Io.Operation.FileWriteStreaming

容器

第 289 行

字段

file: File
header: []const u8 = &.{}
data: []const []const u8
splat: usize = 1

std.Io.Operation.FileWriteStreaming.Error

错误集合

第 295 行

错误

AccessDenied

文件描述符没有写入所需的权限。

BrokenPipe

文件为未连接的套接字,或其读取端已关闭。

DeviceBusy
DiskQuota
FileBusy
FileTooBig
InputOutput
LockViolation

进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。

NoDevice

写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。

NoSpaceLeft
NotOpenForWriting
PermissionDenied
SystemResources

内核内存不足,无法从 in_fd 读取。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

WouldBlock

已启用非阻塞模式,而此操作将阻塞。

std.Io.Operation.FileWriteStreaming.Result

常量

第 320 行

std.Io.Operation.List

容器

第 543 行

字段

std.Io.Operation.List.DoubleNode

容器

第 550 行

字段

std.Io.Operation.List.empty

常量

第 547 行

List

std.Io.Operation.List.SingleNode

容器

第 549 行

字段

std.Io.Operation.NetRead

容器

第 430 行

字段

socket_handle: net.Socket.Handle
data: [][]u8
control: []u8 = &.{}

std.Io.Operation.NetRead.Error

错误集合

第 435 行

错误

AccessDenied

文件描述符不具有读取所需权限。

ConnectionResetByPeer
ConnectionTimedOut

远端对等方未响应正在进行的通信,导致 操作系统中止连接。

NetworkDown
SocketUnconnected
SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.Operation.NetRead.Result

常量

第 447 行

std.Io.Operation.NetReceive

容器

第 345 行

字段

socket_handle: net.Socket.Handle
message_buffer: []net.IncomingMessage
data_buffer: []u8
flags: net.ReceiveFlags

std.Io.Operation.NetReceive.Error

错误集合

第 351 行

错误

ConnectionResetByPeer

发送方意外关闭了网络连接。

ConnectionTimedOut

远端对等方未响应正在进行的通信,导致 操作系统中止连接。

MessageOversize

此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。

NetworkDown

用于到达目标的本地网络接口已离线。

PortUnreachable

此前成功发送了无连接数据包,但远端系统的传输目标端口上没有运行任何服务,因此数据包未被接收。 这使得操作系统收到 ICMP 端口不可达数据包,并将其排队,以便下次在该绑定套接字上调用发送或接收操作时报告。

ProcessFdQuotaExceeded

已达到每进程可打开文件描述符数量上限。

SocketUnconnected

面向连接的套接字的本地端已关闭,或 该套接字从未连接。

SystemFdQuotaExceeded

已达到系统范围内已打开文件的总数上限。

SystemResources

操作系统内部内存或其他资源不足。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.Operation.NetReceive.Result

容器

第 381 行

字段

std.Io.Operation.NetSend

容器

第 384 行

字段

socket_handle: net.Socket.Handle
messages: []net.OutgoingMessage
flags: net.SendFlags

std.Io.Operation.NetSend.Error

错误集合

第 389 行

错误

AccessDenied

尝试向网络/广播地址发送数据, 却将其当作单播地址。

AddressFamilyUnsupported

操作系统或协议不支持该地址族。

ConnectionRefused

目标地址未在侦听;对于无连接消息也可能发生此情况。

ConnectionResetByPeer

网络会话被接收方意外关闭。

ConnectionTimedOut

远端对等方未响应正在进行的通信,导致 操作系统中止连接。

FastOpenAlreadyInProgress

另一个 TCP 快速打开已在进行。

HostUnreachable

可到达网络,但没有到主机的路由。

MessageOversize

此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。

NetworkDown

用于到达目标的本地网络接口已离线。

NetworkUnreachable

没有到网络的路由。

SocketUnconnected

面向连接的套接字的本地端已关闭,或 该套接字从未连接。

SystemResources

网络接口的输出队列已满。这通常表示 接口已停止发送,但也可能由短暂拥塞导致。通常, Linux 不会发生此错误;设备队列溢出时只会 静默丢弃分组。

可用内核内存不足时也会发生此错误。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.Operation.NetSend.Result

容器

第 427 行

字段

std.Io.Operation.NetWrite

容器

第 450 行

字段

socket_handle: net.Socket.Handle
header: []const u8 = &.{}
data: []const []const u8
splat: usize = 1
control: []const u8 = &.{}

std.Io.Operation.NetWrite.Error

错误集合

第 457 行

错误

AddressFamilyUnsupported

传入地址的 sa_family 字段未包含正确的地址族。

ConnectionRefused

目标地址未在监听。

ConnectionResetByPeer

网络会话被接收方意外关闭。

ConnectionTimedOut

远端对等方未响应正在进行的通信,导致 操作系统中止连接。

FastOpenAlreadyInProgress

另一个 TCP 快速打开已在进行。

HostUnreachable

可到达网络,但没有到主机的路由。

NetworkDown

用于到达目标的本地网络接口已关闭。

NetworkUnreachable

没有到网络的路由。

SocketNotBound
SocketUnconnected

面向连接的套接字的本地端已关闭,或 该套接字从未连接。

SystemResources

网络接口的输出队列已满。这通常表示 接口已停止发送,但也可能由短暂拥塞导致。通常, Linux 不会发生此错误;设备队列溢出时只会 静默丢弃分组。

可用内核内存不足时也会发生此错误。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.Operation.NetWrite.Result

常量

第 488 行

std.Io.Operation.OptionalIndex

容器

第 528 行

字段

none = std.math.maxInt(u32)
_

std.Io.Operation.OptionalIndex.fromIndex

函数

第 532 行

pub fn fromIndex(i: usize) OptionalIndex

参数

i: usize

std.Io.Operation.OptionalIndex.toIndex

函数

第 538 行

pub fn toIndex(oi: OptionalIndex) u32

参数

std.Io.Operation.Result

常量

第 491 行

std.Io.Operation.Storage

容器

第 503 行

字段

unused: List.DoubleNode
submission: Submission
pending: Pending
completion: Completion

std.Io.Operation.Storage.Completion

容器

第 522 行

字段

node: List.SingleNode
result: Result

std.Io.Operation.Storage.Pending

容器

第 514 行

字段

node: List.DoubleNode
tag: Tag
userdata: Userdata align(@max(@alignOf(usize), 4))

std.Io.Operation.Storage.Pending.Userdata

类型

第 519 行

std.Io.Operation.Storage.Submission

容器

第 509 行

字段

node: List.SingleNode
operation: Operation

std.Io.Operation.Tag

常量

第 257 行

std.Io.Queue

类型函数

第 2390 行

多生产者、多消费者、线程安全、缓冲区大小可在运行时配置。 缓冲区为空时,消费者挂起,由生产者恢复。 缓冲区满时,生产者挂起,由消费者恢复。

pub fn Queue(Elem: type) type

参数

Elem: type

字段

type_erased: TypeErasedQueue

std.Io.Queue.capacity

函数

第 2514 行

返回以 Elem 为单位的缓冲区长度。

pub fn capacity(q: *const @This()) usize

参数

q: *const @This()

std.Io.Queue.close

函数

第 2404 行

调用后,队列进入“已关闭”状态。已关闭的 队列在尝试放入元素时始终返回 error.Closed,即使 缓冲区中仍有空间。但在返回 error.Closed 之前,仍可取出队列中已有的元素。

线程安全。

pub fn close(q: *@This(), io: Io) void

参数

q: *@This()
io: Io

std.Io.Queue.get

函数

第 2486 行

从队列头部接收元素,当前元素不足时可能阻塞。满足以下任一条件时返回:

  • 至少从队列接收到 min 个元素。
  • 队列已关闭,且没有缓冲的元素。
  • 当前任务被取消。

返回 buffer 中已填入的元素数量;若未填入任何元素则为零。 若返回错误,则没有填入任何元素。

若队列已关闭或任务已取消,但关闭或取消之前已接收到部分元素,则 get 可能返回小于 min 的数量;此时保证后续调用会返回 error.Canceled 或 error.Closed。

仅当 min 为 0 时才可能返回 0;此时保证在不阻塞的前提下,尽可能填充 buffer。

断言 buffer.len >= min。

pub fn get(q: *@This(), io: Io, buffer: []Elem, min: usize) (QueueClosedError || Cancelable)!usize

参数

q: *@This()
io: Io
buffer: []Elem
min: usize

std.Io.Queue.getOne

函数

第 2498 行

从队首接收一个元素;如果队列为空,则阻塞。

pub fn getOne(q: *@This(), io: Io) (QueueClosedError || Cancelable)!Elem

参数

q: *@This()
io: Io

std.Io.Queue.getOneUncancelable

函数

第 2507 行

与 getOne 相同,但不引入取消点。

取消及取消点的说明见 Future.cancel。

pub fn getOneUncancelable(q: *@This(), io: Io) QueueClosedError!Elem

参数

q: *@This()
io: Io

错误

Closed

std.Io.Queue.getUncancelable

函数

第 2493 行

与 get 相同,但不会引入取消点。

关于取消和取消点的说明,参见 Future.cancel。

pub fn getUncancelable(q: *@This(), io: Io, buffer: []Elem, min: usize) QueueClosedError!usize

参数

q: *@This()
io: Io
buffer: []Elem
min: usize

错误

Closed

std.Io.Queue.init

函数

第 2394 行

pub fn init(buffer: []Elem) @This()

参数

buffer: []Elem

std.Io.Queue.put

函数

第 2429 行

将元素追加到队列末尾;容量不足时可能阻塞。 满足以下任一 条件即返回:

  • 至少已向队列加入 min 个元素;
  • 队列关闭;
  • 当前任务被取消。

返回已加入队列的 elements 元素数量,可以为零。 若返回错误,则没有加入任何元素。

如果队列关闭或任务取消之前 已加入部分元素,put 可能 返回小于 min 的数量;此时保证后续调用 返回 error.Canceled 或 error.Closed。

只有 min 为 0 时,返回值才可能为 0;此时 保证在不阻塞的情况下, 尽可能将 elements 加入队列。

断言 elements.len >= min。

pub fn put(q: *@This(), io: Io, elements: []const Elem, min: usize) (QueueClosedError || Cancelable)!usize

参数

q: *@This()
io: Io
elements: []const Elem
min: usize

std.Io.Queue.putAll

函数

第 2438 行

与 put 相同,但会阻塞,直到所有元素都已加入队列。

如果队列已关闭或操作取消,则返回 error.Closed 或 error.Canceled; 不保证取消或关闭之前,有多少个 elements 已加入队列,也可能一个都没有。

pub fn putAll(q: *@This(), io: Io, elements: []const Elem) (QueueClosedError || Cancelable)!void

参数

q: *@This()
io: Io
elements: []const Elem

std.Io.Queue.putOne

函数

第 2454 行

将 item 追加到队尾;队列满时阻塞。

pub fn putOne(q: *@This(), io: Io, item: Elem) (QueueClosedError || Cancelable)!void

参数

q: *@This()
io: Io
item: Elem

std.Io.Queue.putOneUncancelable

函数

第 2461 行

与 putOne 相同,但不会引入取消点。

关于取消和取消点的说明,参见 Future.cancel。

pub fn putOneUncancelable(q: *@This(), io: Io, item: Elem) QueueClosedError!void

参数

q: *@This()
io: Io
item: Elem

错误

Closed

std.Io.Queue.putUncancelable

函数

第 2449 行

与 put 相同,但不引入取消点。

关于取消和取消点,参见 Future.cancel。

pub fn putUncancelable(q: *@This(), io: Io, elements: []const Elem, min: usize) QueueClosedError!usize

参数

q: *@This()
io: Io
elements: []const Elem
min: usize

错误

Closed

std.Io.QueueClosedError

错误集合

第 2078 行

错误

Closed

std.Io.random

函数

第 2674 行

从密码学安全的伪随机数生成器获取熵。

实现可能在进程内存中存储随机数生成器状态,并用它填充 buffer。

随机种子来自 randomSecure;若失败,则使用安全性较低的机制。

线程安全。

另见 randomSecure。

pub fn random(io: Io, buffer: []u8) void

参数

io: Io
buffer: []u8

std.Io.randomSecure

函数

第 2691 行

从进程外部获取密码学安全的熵。

始终发起系统调用,或通过其他方式避免依赖进程内存, 以获取新鲜的随机性。不依赖已保存的随机数生成器状态。

不提供任何后备机制;出现任何问题时均返回 error.EntropyUnavailable。

线程安全。

另见 random。

pub fn randomSecure(io: Io, buffer: []u8) RandomSecureError!void

参数

io: Io
buffer: []u8

错误

Canceled Cancelable

调用方请求停止异步操作。

EntropyUnavailable

std.Io.RandomSecureError

错误集合

第 2678 行

错误

Canceled Cancelable

调用方请求停止异步操作。

EntropyUnavailable

std.Io.Reader

别名

第 41 行

别名目标 std.Io.Reader

std.Io.recancel

函数

第 1439 行

断言此前的取消点返回了 error.Canceled,并重新激活 取消请求,使下一个取消点再次返回 error.Canceled。

关于取消及取消点的说明,参见 Future.cancel。

pub fn recancel(io: Io) void

参数

io: Io

std.Io.RwLock

别名

第 48 行

别名目标 std.Io.RwLock

std.Io.Select

类型函数

第 1496 行

共同执行任务,并提供等待一个或多个任务完成的机制。类似 Batch,但工作在更高层的任务抽象层,而不是较底层的 Operation 抽象层。

给定的带标签联合体用作等待函数的返回类型。调用异步或并发接口时,需要指定被调用函数完成后的结果放入哪个联合体字段。

pub fn Select(comptime U: type) type

参数

U: type

字段

io: Io
group: Group
queue: Queue(U)

std.Io.Select.async

函数

第 1535 行

异步调用 function,参数为 args。所创建资源由此选择器拥有。

function 的返回类型必须与 field 字段匹配,该字段属于 Union。

function 可能在 async 返回之前立即调用。

此函数返回时,保证 function 要么已调用并完成,要么已成功分配到一个并发执行单元。

调用此函数后,必须在选择器反初始化之前调用 await 或 cancel。

线程安全。

相关接口:

  • Io.async
  • Group.async
pub fn async( s: *S, comptime field: Field, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function)), ) void

参数

s: *S
field: Field
args: std.meta.ArgsTuple(@TypeOf(function))

std.Io.Select.async.start

函数

第 1544 行

fn start(type_erased_context: *const anyopaque) void

参数

type_erased_context: *const anyopaque

std.Io.Select.await

函数

第 1599 行

阻塞直到 select 中另一个任务完成。

此后仍可合法调用 async 和 concurrent。

线程安全。

pub fn await(s: *S) Cancelable!U

参数

s: *S

错误

Canceled

调用方请求停止异步操作。

std.Io.Select.awaitMany

函数

第 1614 行

阻塞直到至少有 min 个结果被复制 到 buffer。

断言 buffer.len >= min。

此后可以合法调用 async 和 concurrent。

线程安全。

pub fn awaitMany(s: *S, buffer: []U, min: usize) Cancelable!usize

参数

s: *S
buffer: []U
min: usize

错误

Canceled

调用方请求停止异步操作。

std.Io.Select.cancel

函数

第 1638 行

请求取消此选择器拥有的全部剩余任务,然后阻塞,直到这些任务全部结束。若初始化选择器时,缓冲区空间不足以容纳所有剩余任务的完成结果,则会死锁。

若任一选择任务分配了资源,该任务可能已经完成,因此必须循环调用此函数,直至返回 null,才能释放这些资源。若不存在资源泄漏的可能,则优先使用 cancelDiscard。

此后调用 await 或 awaitMany 属于非法操作。

可安全地多次调用此函数,即使此前已返回 null。

线程安全。

pub fn cancel(s: *S) ?U

参数

s: *S

std.Io.Select.cancelDiscard

函数

第 1659 行

请求取消此 select 拥有的所有剩余任务, 然后阻塞至它们全部结束。

丢弃所有未完成任务的返回值。因此, 任务可能返回已分配资源时,不适合调用 此函数。此场景请参见 cancel。

此后调用 await 或 awaitMany 属于非法行为。

可以安全地多次调用。

线程安全。

pub fn cancelDiscard(s: *S) void

参数

s: *S

std.Io.Select.concurrent

函数

第 1572 行

并发调用 function,参数为 args。所创建资源由此选择器拥有。

function 的返回类型必须与 field 字段匹配,该字段属于 Union。

此函数成功返回后,保证 function 已分配到一个并发执行单元,并且必须在选择器反初始化前调用 await 或 cancel。

线程安全。

相关接口:

  • Io.concurrent
  • Group.concurrent
pub fn concurrent( s: *S, comptime field: Field, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function)), ) ConcurrentError!void

参数

s: *S
field: Field
args: std.meta.ArgsTuple(@TypeOf(function))

错误

ConcurrencyUnavailable

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

std.Io.Select.concurrent.start

函数

第 1581 行

fn start(type_erased_context: *const anyopaque) void

参数

type_erased_context: *const anyopaque

std.Io.Select.Field

类型

第 1506 行

std.Io.Select.init

函数

第 1508 行

pub fn init(io: Io, buffer: []U) S

参数

io: Io
buffer: []U

std.Io.Select.S

别名

第 1502 行

别名目标 std.Io.Select

std.Io.Select.Union

常量

第 1504 行

std.Io.Semaphore

别名

第 49 行

别名目标 std.Io.Semaphore

std.Io.sleep

函数

第 2603 行

等待 clock 上经过指定时间。

另见:

pub fn sleep(io: Io, duration: Duration, clock: Clock) Cancelable!void

参数

io: Io
duration: Duration
clock: Clock

错误

Canceled

调用方请求停止异步操作。

std.Io.std

别名

第 19 行

别名目标 std

std.Io.swapCancelProtection

函数

第 1471 行

更新当前任务的取消保护状态,参见 CancelProtection。

典型用法是保护一段代码,使其不被取消:

const old_cancel_protect = io.swapCancelProtection(.blocked);
defer _ = io.swapCancelProtection(old_cancel_protect);
doSomeWork() catch |err| switch (err) {
    error.Canceled => unreachable,
};

取消及取消点的说明参见 Future.cancel。

pub fn swapCancelProtection(io: Io, new: CancelProtection) CancelProtection

参数

io: Io
new: CancelProtection

std.Io.Terminal

别名

第 46 行

别名目标 std.Io.Terminal

std.Io.Threaded

别名

第 28 行

别名目标 std.Io.Threaded

std.Io.Timeout

容器

第 1251 行

声明操作应在何种条件下返回 error.Timeout。

字段

none

.none 将无限等待

duration: Clock.Duration
deadline: Clock.Timestamp

std.Io.Timeout.Error

错误集合

第 1257 行

错误

Timeout

std.Io.Timeout.sleep

函数

第 1289 行

等待至超时期限经过。

另请参见:

  • Io.sleep
  • Clock.Duration.sleep
  • Clock.Timestamp.wait
pub fn sleep(timeout: Timeout, io: Io) Cancelable!void

参数

timeout: Timeout
io: Io

错误

Canceled

调用方请求停止异步操作。

std.Io.Timeout.toDeadline

函数

第 1267 行

pub fn toDeadline(t: Timeout, io: Io) Timeout

参数

t: Timeout
io: Io

std.Io.Timeout.toDurationFromNow

函数

第 1275 行

pub fn toDurationFromNow(t: Timeout, io: Io) ?Clock.Duration

参数

t: Timeout
io: Io

std.Io.Timeout.toTimestamp

函数

第 1259 行

pub fn toTimestamp(t: Timeout, io: Io) ?Clock.Timestamp

参数

t: Timeout
io: Io

std.Io.Timestamp

容器

第 1021 行

字段

nanoseconds: i96

std.Io.Timestamp.addDuration

函数

第 1034 行

pub fn addDuration(from: Timestamp, duration: Duration) Timestamp

参数

from: Timestamp
duration: Duration

std.Io.Timestamp.compare

函数

第 1082 行

pub fn compare(lhs: Timestamp, op: math.CompareOperator, rhs: Timestamp) bool

参数

std.Io.Timestamp.durationTo

函数

第 1030 行

pub fn durationTo(from: Timestamp, to: Timestamp) Duration

参数

from: Timestamp
to: Timestamp

std.Io.Timestamp.formatNumber

函数

第 1066 行

pub fn formatNumber(t: Timestamp, w: *std.Io.Writer, n: std.fmt.Number) std.Io.Writer.Error!void

参数

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.Io.Timestamp.fromNanoseconds

函数

第 1046 行

pub fn fromNanoseconds(x: i96) Timestamp

参数

x: i96

std.Io.Timestamp.now

函数

第 1024 行

pub fn now(io: Io, clock: Clock) Io.Timestamp

参数

io: Io
clock: Clock

std.Io.Timestamp.subDuration

函数

第 1038 行

pub fn subDuration(from: Timestamp, duration: Duration) Timestamp

参数

from: Timestamp
duration: Duration

std.Io.Timestamp.toMicroseconds

函数

第 1050 行

pub fn toMicroseconds(t: Timestamp) i64

参数

std.Io.Timestamp.toMilliseconds

函数

第 1054 行

pub fn toMilliseconds(t: Timestamp) i64

参数

std.Io.Timestamp.toNanoseconds

函数

第 1062 行

pub fn toNanoseconds(t: Timestamp) i96

参数

std.Io.Timestamp.toSeconds

函数

第 1058 行

pub fn toSeconds(t: Timestamp) i64

参数

std.Io.Timestamp.untilNow

函数

第 1077 行

分辨率由 Clock.resolution 决定;若不支持该时钟, 其值可能为 0。

pub fn untilNow(t: Timestamp, io: Io, clock: Clock) Duration

参数

t: Timestamp
io: Io
clock: Clock

std.Io.Timestamp.withClock

函数

第 1042 行

pub fn withClock(t: Timestamp, clock: Clock) Clock.Timestamp

参数

t: Timestamp
clock: Clock

std.Io.Timestamp.zero

常量

第 1028 行

Timestamp

std.Io.tryLockStderr

函数

第 2652 行

与 lockStderr 相同,但不阻塞。

pub fn tryLockStderr(io: Io, buffer: []u8, terminal_mode: ?Terminal.Mode) Cancelable!?LockedStderr

参数

io: Io
buffer: []u8
terminal_mode: ?Terminal.Mode

错误

Canceled

调用方请求停止异步操作。

std.Io.TypeErasedQueue

容器

第 2080 行

字段

mutex: Mutex
closed: bool
buffer: []u8

环形缓冲区。此数据在逻辑上位于已排队获取者之后。

start: usize
len: usize
putters: std.DoublyLinkedList
getters: std.DoublyLinkedList

std.Io.TypeErasedQueue.close

函数

第 2124 行

调用后,队列进入“已关闭”状态。已关闭的 队列在尝试放入元素时始终返回 error.Closed,即使 缓冲区中仍有空间。但在返回 error.Closed 之前,仍可取出队列中已有的元素。

幂等。线程安全。

pub fn close(q: *TypeErasedQueue, io: Io) void

参数

std.Io.TypeErasedQueue.fillRingBufferFromPutters

函数

第 2365 行

环形缓冲区存在非零可用空间,且可能有等待中的写入方时调用。 此时已持有互斥锁;任务是将写入方数据复制到 环形缓冲区,并通知那些缓冲区数据 已全部复制完成的写入方。

fn fillRingBufferFromPutters(q: *TypeErasedQueue, io: Io) void

参数

std.Io.TypeErasedQueue.get

函数

第 2248 行

pub fn get(q: *TypeErasedQueue, io: Io, buffer: []u8, min: usize) (QueueClosedError || Cancelable)!usize

参数

q: *TypeErasedQueue
io: Io
buffer: []u8
min: usize

std.Io.TypeErasedQueue.Get

容器

第 2099 行

字段

remaining: []u8
needed: usize
condition: Condition
node: std.DoublyLinkedList.Node

std.Io.TypeErasedQueue.getLocked

函数

第 2276 行

fn getLocked(q: *TypeErasedQueue, io: Io, buffer: []u8, min: usize, uncancelable: bool) (QueueClosedError || Cancelable)!usize

参数

q: *TypeErasedQueue
io: Io
buffer: []u8
min: usize
uncancelable: bool

std.Io.TypeErasedQueue.gettableSlice

函数

第 2270 行

fn gettableSlice(q: *const TypeErasedQueue) ?[]const u8

参数

q: *const TypeErasedQueue

std.Io.TypeErasedQueue.getUncancelable

函数

第 2259 行

与 get 相同,但不会引入取消点。

关于取消和取消点的说明,参见 Future.cancel。

pub fn getUncancelable(q: *TypeErasedQueue, io: Io, buffer: []u8, min: usize) QueueClosedError!usize

参数

q: *TypeErasedQueue
io: Io
buffer: []u8
min: usize

错误

Closed

std.Io.TypeErasedQueue.init

函数

第 2106 行

pub fn init(buffer: []u8) TypeErasedQueue

参数

buffer: []u8

std.Io.TypeErasedQueue.put

函数

第 2144 行

pub fn put(q: *TypeErasedQueue, io: Io, elements: []const u8, min: usize) (QueueClosedError || Cancelable)!usize

参数

q: *TypeErasedQueue
io: Io
elements: []const u8
min: usize

std.Io.TypeErasedQueue.Put

容器

第 2092 行

字段

remaining: []const u8
needed: usize
condition: Condition
node: std.DoublyLinkedList.Node

std.Io.TypeErasedQueue.putLocked

函数

第 2176 行

fn putLocked(q: *TypeErasedQueue, io: Io, elements: []const u8, min: usize, uncancelable: bool) (QueueClosedError || Cancelable)!usize

参数

q: *TypeErasedQueue
io: Io
elements: []const u8
min: usize
uncancelable: bool

std.Io.TypeErasedQueue.puttableSlice

函数

第 2166 行

fn puttableSlice(q: *const TypeErasedQueue) ?[]u8

参数

q: *const TypeErasedQueue

std.Io.TypeErasedQueue.putUncancelable

函数

第 2155 行

与 put 相同,但不引入取消点。

关于取消和取消点,参见 Future.cancel。

pub fn putUncancelable(q: *TypeErasedQueue, io: Io, elements: []const u8, min: usize) QueueClosedError!usize

参数

q: *TypeErasedQueue
io: Io
elements: []const u8
min: usize

错误

Closed

std.Io.UnexpectedError

错误集合

第 820 行

错误

Unexpected

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.unlockStderr

函数

第 2658 行

pub fn unlockStderr(io: Io) void

参数

io: Io

std.Io.unreachableAwait

函数

第 2872 行

pub fn unreachableAwait( userdata: ?*anyopaque, any_future: *AnyFuture, result: []u8, result_alignment: std.mem.Alignment, ) void

参数

userdata: ?*anyopaque
any_future: *AnyFuture
result: []u8
result_alignment: std.mem.Alignment

std.Io.unreachableBatchAwaitAsync

函数

第 2986 行

pub fn unreachableBatchAwaitAsync(userdata: ?*anyopaque, b: *Batch) Cancelable!void

参数

userdata: ?*anyopaque
b: *Batch

错误

Canceled

调用方请求停止异步操作。

std.Io.unreachableBatchAwaitConcurrent

函数

第 2992 行

pub fn unreachableBatchAwaitConcurrent(userdata: ?*anyopaque, b: *Batch, timeout: Timeout) Batch.AwaitConcurrentError!void

参数

userdata: ?*anyopaque
b: *Batch
timeout: Timeout

错误

Canceled Cancelable

调用方请求停止异步操作。

ConcurrencyUnavailable ConcurrentError

可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。

Timeout Error

std.Io.unreachableBatchCancel

函数

第 2999 行

pub fn unreachableBatchCancel(userdata: ?*anyopaque, b: *Batch) void

参数

userdata: ?*anyopaque
b: *Batch

std.Io.unreachableCancel

函数

第 2885 行

pub fn unreachableCancel( userdata: ?*anyopaque, any_future: *AnyFuture, result: []u8, result_alignment: std.mem.Alignment, ) void

参数

userdata: ?*anyopaque
any_future: *AnyFuture
result: []u8
result_alignment: std.mem.Alignment

std.Io.unreachableCheckCancel

函数

第 2951 行

pub fn unreachableCheckCancel(userdata: ?*anyopaque) Cancelable!void

参数

userdata: ?*anyopaque

错误

Canceled

调用方请求停止异步操作。

std.Io.unreachableChildKill

函数

第 3478 行

pub fn unreachableChildKill(userdata: ?*anyopaque, child: *std.process.Child) void

参数

userdata: ?*anyopaque
child: *std.process.Child

std.Io.unreachableChildWait

函数

第 3472 行

pub fn unreachableChildWait(userdata: ?*anyopaque, child: *std.process.Child) std.process.Child.WaitError!std.process.Child.Term

参数

userdata: ?*anyopaque
child: *std.process.Child

错误

AccessDenied
Canceled Cancelable

调用方请求停止异步操作。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.unreachableDirClose

函数

第 3084 行

pub fn unreachableDirClose(userdata: ?*anyopaque, dirs: []const Dir) void

参数

userdata: ?*anyopaque
dirs: []const Dir

std.Io.unreachableFileClose

函数

第 3225 行

pub fn unreachableFileClose(userdata: ?*anyopaque, files: []const File) void

参数

userdata: ?*anyopaque
files: []const File

std.Io.unreachableFileEnableAnsiEscapeCodes

函数

第 3298 行

pub fn unreachableFileEnableAnsiEscapeCodes(userdata: ?*anyopaque, file: File) File.EnableAnsiEscapeCodesError!void

参数

userdata: ?*anyopaque
file: File

错误

Canceled Cancelable

调用方请求停止异步操作。

NotTerminalDevice
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.unreachableFileIsTty

函数

第 3292 行

pub fn unreachableFileIsTty(userdata: ?*anyopaque, file: File) Cancelable!bool

参数

userdata: ?*anyopaque
file: File

错误

Canceled

调用方请求停止异步操作。

std.Io.unreachableFileMemoryMapDestroy

函数

第 3388 行

pub fn unreachableFileMemoryMapDestroy(userdata: ?*anyopaque, mm: *File.MemoryMap) void

参数

userdata: ?*anyopaque
mm: *File.MemoryMap

std.Io.unreachableFileMemoryMapRead

函数

第 3401 行

pub fn unreachableFileMemoryMapRead(userdata: ?*anyopaque, mm: *File.MemoryMap) File.ReadPositionalError!void

参数

userdata: ?*anyopaque
mm: *File.MemoryMap

错误

AccessDenied

在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。

Canceled Cancelable

调用方请求停止异步操作。

InputOutput
IsDir

尝试将目录文件描述符当作普通文件读取。

LockViolation

由于锁定而无法读取文件。根据 Io 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。

NotOpenForReading

打开文件时未授予读取能力。

SystemResources
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable

此文件不支持按位置读取。

WouldBlock

已启用非阻塞模式,且从该文件描述符读取会阻塞。

std.Io.unreachableFileMemoryMapSetLength

函数

第 3394 行

pub fn unreachableFileMemoryMapSetLength(userdata: ?*anyopaque, mm: *File.MemoryMap, new_len: usize) File.MemoryMap.SetLengthError!void

参数

userdata: ?*anyopaque
mm: *File.MemoryMap
new_len: usize

错误

AccessDenied

以下任一情况:

  • File.Kind 不是 file。
  • 文件未以读取方式打开,且启用了读取访问保护。
  • 文件未以写入方式打开,且启用了写入访问保护。
Canceled Cancelable

调用方请求停止异步操作。

FileBusy SetLengthError
FileTooBig SetLengthError
InputOutput SetLengthError
LockedMemoryLimitExceeded
NonResizable SetLengthError
OperationUnsupported

无法原子地更改映射长度。调用方必须 使用 destroy 和 create 调整映射大小。

OutOfMemory Error
PermissionDenied

prot 参数请求 PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。

ProcessFdQuotaExceeded
SystemFdQuotaExceeded
Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.unreachableFileMemoryMapWrite

函数

第 3407 行

pub fn unreachableFileMemoryMapWrite(userdata: ?*anyopaque, mm: *File.MemoryMap) File.WritePositionalError!void

参数

userdata: ?*anyopaque
mm: *File.MemoryMap

错误

AccessDenied

文件描述符没有写入所需的权限。

BrokenPipe

文件为未连接的套接字,或其读取端已关闭。

Canceled Cancelable

调用方请求停止异步操作。

DeviceBusy
DiskQuota
FileBusy
FileTooBig
InputOutput
LockViolation

进程无法访问文件,因为另一进程已锁定 文件的一部分。仅限 Windows。

NoDevice

写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。

NoSpaceLeft
NotOpenForWriting

文件打开时没有写入能力。

PermissionDenied
SystemResources

内核内存不足,无法从 in_fd 读取。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

Unseekable

无法对该文件按指定位置写入。

WouldBlock

已启用非阻塞模式,而此操作将阻塞。

std.Io.unreachableFileSupportsAnsiEscapeCodes

函数

第 3304 行

pub fn unreachableFileSupportsAnsiEscapeCodes(userdata: ?*anyopaque, file: File) Cancelable!bool

参数

userdata: ?*anyopaque
file: File

错误

Canceled

调用方请求停止异步操作。

std.Io.unreachableFileUnlock

函数

第 3353 行

pub fn unreachableFileUnlock(userdata: ?*anyopaque, file: File) void

参数

userdata: ?*anyopaque
file: File

std.Io.unreachableGroupAwait

函数

第 2926 行

pub fn unreachableGroupAwait(userdata: ?*anyopaque, group: *Group, token: *anyopaque) Cancelable!void

参数

userdata: ?*anyopaque
group: *Group
token: *anyopaque

错误

Canceled

调用方请求停止异步操作。

std.Io.unreachableGroupCancel

函数

第 2933 行

pub fn unreachableGroupCancel(userdata: ?*anyopaque, group: *Group, token: *anyopaque) void

参数

userdata: ?*anyopaque
group: *Group
token: *anyopaque

std.Io.unreachableLockStderr

函数

第 3425 行

pub fn unreachableLockStderr(userdata: ?*anyopaque, terminal_mode: ?Terminal.Mode) Cancelable!LockedStderr

参数

userdata: ?*anyopaque
terminal_mode: ?Terminal.Mode

错误

Canceled

调用方请求停止异步操作。

std.Io.unreachableNetClose

函数

第 3586 行

pub fn unreachableNetClose(userdata: ?*anyopaque, sockets: []const net.Socket) void

参数

userdata: ?*anyopaque
sockets: []const net.Socket

std.Io.unreachableNetInterfaceName

函数

第 3605 行

pub fn unreachableNetInterfaceName(userdata: ?*anyopaque, interface: net.Interface) net.Interface.NameError!net.Interface.Name

参数

userdata: ?*anyopaque
interface: net.Interface

错误

Canceled Cancelable

调用方请求停止异步操作。

InterfaceNotFound

index 超出范围。

NameTooLong

接口名称长于 Name.max_len。

Unexpected UnexpectedError

操作系统返回了未记录在文档中的错误码。

理论上不可能出现此错误,但处理 此错误优于触发未定义行为。

观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。

std.Io.unreachableRecancel

函数

第 2940 行

pub fn unreachableRecancel(userdata: ?*anyopaque) void

参数

userdata: ?*anyopaque

std.Io.unreachableSwapCancelProtection

函数

第 2945 行

pub fn unreachableSwapCancelProtection(userdata: ?*anyopaque, new: CancelProtection) CancelProtection

参数

userdata: ?*anyopaque
new: CancelProtection

std.Io.unreachableUnlockStderr

函数

第 3437 行

pub fn unreachableUnlockStderr(userdata: ?*anyopaque) void

参数

userdata: ?*anyopaque

std.Io.Uring

别名

第 39 行

别名目标 std.Io.Uring

std.Io.VTable

容器

第 51 行

字段

crashHandler: *const fn (?*anyopaque) void
async: *const fn (
    /// 对应 `Io.userdata`。
    userdata: ?*anyopaque,
    /// 此切片的指针是一个“立即求值”的结果值。
    /// 长度为结果类型的字节大小。
    /// 此函数调用结束后,该指针的生命周期立即终止。
    result: []u8,
    result_alignment: std.mem.Alignment,
    /// 复制后传给 `start`。
    context: []const u8,
    context_alignment: std.mem.Alignment,
    start: *const fn (context: *const anyopaque, result: *anyopaque) void,
) ?*AnyFuture

若返回 null,表示 result 已填充, await 将为空操作。

线程安全。

concurrent: *const fn (
    /// 对应 `Io.userdata`。
    userdata: ?*anyopaque,
    result_len: usize,
    result_alignment: std.mem.Alignment,
    /// 复制后传给 `start`。
    context: []const u8,
    context_alignment: std.mem.Alignment,
    start: *const fn (context: *const anyopaque, result: *anyopaque) void,
) ConcurrentError!*AnyFuture

线程安全。

await: *const fn (
    /// 对应 `Io.userdata`。
    userdata: ?*anyopaque,
    /// 与 `async` 返回的值相同。
    any_future: *AnyFuture,
    /// 指向写入结果的缓冲区。
    /// 长度等于结果类型的字节大小。
    result: []u8,
    result_alignment: std.mem.Alignment,
) void

仅当 async 返回非 null 值时调用此函数。

线程安全。

cancel: *const fn (
    /// 对应 `Io.userdata`。
    userdata: ?*anyopaque,
    /// 与 `async` 返回的值相同。
    any_future: *AnyFuture,
    /// 指向写入结果的缓冲区。
    /// 长度等于结果类型的字节大小。
    result: []u8,
    result_alignment: std.mem.Alignment,
) void

等价于 await,但会发起取消请求。

仅当 async 返回非 null 值时调用此函数。

线程安全。

groupAsync: *const fn (
    /// 对应 `Io.userdata`。
    userdata: ?*anyopaque,
    /// 已生成异步任务的所有者。
    group: *Group,
    /// 复制后传给 `start`。
    context: []const u8,
    context_alignment: std.mem.Alignment,
    start: *const fn (context: *const anyopaque) void,
) void

线程安全。

groupConcurrent: *const fn (
    /// 对应 `Io.userdata`。
    userdata: ?*anyopaque,
    /// 已生成异步任务的所有者。
    group: *Group,
    /// 复制后传给 `start`。
    context: []const u8,
    context_alignment: std.mem.Alignment,
    start: *const fn (context: *const anyopaque) void,
) ConcurrentError!void

线程安全。

groupAwait: *const fn (?*anyopaque, *Group, token: *anyopaque) Cancelable!void
groupCancel: *const fn (?*anyopaque, *Group, token: *anyopaque) void
recancel: *const fn (?*anyopaque) void
swapCancelProtection: *const fn (?*anyopaque, new: CancelProtection) CancelProtection
checkCancel: *const fn (?*anyopaque) Cancelable!void
futexWait: *const fn (?*anyopaque, ptr: *const u32, expected: u32, Timeout) Cancelable!void
futexWaitUncancelable: *const fn (?*anyopaque, ptr: *const u32, expected: u32) void
futexWake: *const fn (?*anyopaque, ptr: *const u32, max_waiters: u32) void
operate: *const fn (?*anyopaque, Operation) Cancelable!Operation.Result
batchAwaitAsync: *const fn (?*anyopaque, *Batch) Cancelable!void
batchAwaitConcurrent: *const fn (?*anyopaque, *Batch, Timeout) Batch.AwaitConcurrentError!void
batchCancel: *const fn (?*anyopaque, *Batch) void
dirCreateDir: *const fn (?*anyopaque, Dir, []const u8, Dir.Permissions) Dir.CreateDirError!void
dirCreateDirPath: *const fn (?*anyopaque, Dir, []const u8, Dir.Permissions) Dir.CreateDirPathError!Dir.CreatePathStatus
dirCreateDirPathOpen: *const fn (?*anyopaque, Dir, []const u8, Dir.Permissions, Dir.OpenOptions) Dir.CreateDirPathOpenError!Dir
dirOpenDir: *const fn (?*anyopaque, Dir, []const u8, Dir.OpenOptions) Dir.OpenError!Dir
dirStat: *const fn (?*anyopaque, Dir) Dir.StatError!Dir.Stat
dirStatFile: *const fn (?*anyopaque, Dir, []const u8, Dir.StatFileOptions) Dir.StatFileError!File.Stat
dirAccess: *const fn (?*anyopaque, Dir, []const u8, Dir.AccessOptions) Dir.AccessError!void
dirCreateFile: *const fn (?*anyopaque, Dir, []const u8, Dir.CreateFileOptions) File.OpenError!File
dirCreateFileAtomic: *const fn (?*anyopaque, Dir, []const u8, Dir.CreateFileAtomicOptions) Dir.CreateFileAtomicError!File.Atomic
dirOpenFile: *const fn (?*anyopaque, Dir, []const u8, Dir.OpenFileOptions) File.OpenError!File
dirClose: *const fn (?*anyopaque, []const Dir) void
dirRead: *const fn (?*anyopaque, *Dir.Reader, []Dir.Entry) Dir.Reader.Error!usize
dirRealPath: *const fn (?*anyopaque, Dir, out_buffer: []u8) Dir.RealPathError!usize
dirRealPathFile: *const fn (?*anyopaque, Dir, path_name: []const u8, out_buffer: []u8) Dir.RealPathFileError!usize
dirDeleteFile: *const fn (?*anyopaque, Dir, []const u8) Dir.DeleteFileError!void
dirDeleteDir: *const fn (?*anyopaque, Dir, []const u8) Dir.DeleteDirError!void
dirRename: *const fn (?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8) Dir.RenameError!void
dirRenamePreserve: *const fn (?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8) Dir.RenamePreserveError!void
dirSymLink: *const fn (?*anyopaque, Dir, target_path: []const u8, sym_link_path: []const u8, Dir.SymLinkFlags) Dir.SymLinkError!void
dirReadLink: *const fn (?*anyopaque, Dir, sub_path: []const u8, buffer: []u8) Dir.ReadLinkError!usize
dirSetOwner: *const fn (?*anyopaque, Dir, ?File.Uid, ?File.Gid) Dir.SetOwnerError!void
dirSetFileOwner: *const fn (?*anyopaque, Dir, []const u8, ?File.Uid, ?File.Gid, Dir.SetFileOwnerOptions) Dir.SetFileOwnerError!void
dirSetPermissions: *const fn (?*anyopaque, Dir, Dir.Permissions) Dir.SetPermissionsError!void
dirSetFilePermissions: *const fn (?*anyopaque, Dir, []const u8, File.Permissions, Dir.SetFilePermissionsOptions) Dir.SetFilePermissionsError!void
dirSetTimestamps: *const fn (?*anyopaque, Dir, []const u8, Dir.SetTimestampsOptions) Dir.SetTimestampsError!void
dirHardLink: *const fn (?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, Dir.HardLinkOptions) Dir.HardLinkError!void
fileStat: *const fn (?*anyopaque, File) File.StatError!File.Stat
fileLength: *const fn (?*anyopaque, File) File.LengthError!u64
fileClose: *const fn (?*anyopaque, []const File) void
fileWritePositional: *const fn (?*anyopaque, File, header: []const u8, data: []const []const u8, splat: usize, offset: u64) File.WritePositionalError!usize
fileWriteFileStreaming: *const fn (?*anyopaque, File, header: []const u8, *Io.File.Reader, Io.Limit) File.Writer.WriteFileError!usize
fileWriteFilePositional: *const fn (?*anyopaque, File, header: []const u8, *Io.File.Reader, Io.Limit, offset: u64) File.WriteFilePositionalError!usize
fileReadPositional: *const fn (?*anyopaque, File, data: []const []u8, offset: u64) File.ReadPositionalError!usize

在末尾或超过末尾读取时返回 0。

fileSeekBy: *const fn (?*anyopaque, File, relative_offset: i64) File.SeekError!void
fileSeekTo: *const fn (?*anyopaque, File, absolute_offset: u64) File.SeekError!void
fileSync: *const fn (?*anyopaque, File) File.SyncError!void
fileIsTty: *const fn (?*anyopaque, File) Cancelable!bool
fileEnableAnsiEscapeCodes: *const fn (?*anyopaque, File) File.EnableAnsiEscapeCodesError!void
fileSupportsAnsiEscapeCodes: *const fn (?*anyopaque, File) Cancelable!bool
fileSetLength: *const fn (?*anyopaque, File, u64) File.SetLengthError!void
fileSetOwner: *const fn (?*anyopaque, File, ?File.Uid, ?File.Gid) File.SetOwnerError!void
fileSetPermissions: *const fn (?*anyopaque, File, File.Permissions) File.SetPermissionsError!void
fileSetTimestamps: *const fn (?*anyopaque, File, File.SetTimestampsOptions) File.SetTimestampsError!void
fileLock: *const fn (?*anyopaque, File, File.Lock) File.LockError!void
fileTryLock: *const fn (?*anyopaque, File, File.Lock) File.LockError!bool
fileUnlock: *const fn (?*anyopaque, File) void
fileDowngradeLock: *const fn (?*anyopaque, File) File.DowngradeLockError!void
fileRealPath: *const fn (?*anyopaque, File, out_buffer: []u8) File.RealPathError!usize
fileHardLink: *const fn (?*anyopaque, File, Dir, []const u8, File.HardLinkOptions) File.HardLinkError!void
fileMemoryMapCreate: *const fn (?*anyopaque, File, File.MemoryMap.CreateOptions) File.MemoryMap.CreateError!File.MemoryMap
fileMemoryMapDestroy: *const fn (?*anyopaque, *File.MemoryMap) void
fileMemoryMapSetLength: *const fn (?*anyopaque, *File.MemoryMap, usize) File.MemoryMap.SetLengthError!void
fileMemoryMapRead: *const fn (?*anyopaque, *File.MemoryMap) File.ReadPositionalError!void
fileMemoryMapWrite: *const fn (?*anyopaque, *File.MemoryMap) File.WritePositionalError!void
processExecutableOpen: *const fn (?*anyopaque, Dir.OpenFileOptions) std.process.OpenExecutableError!File
processExecutablePath: *const fn (?*anyopaque, buffer: []u8) std.process.ExecutablePathError!usize
lockStderr: *const fn (?*anyopaque, ?Terminal.Mode) Cancelable!LockedStderr
tryLockStderr: *const fn (?*anyopaque, ?Terminal.Mode) Cancelable!?LockedStderr
unlockStderr: *const fn (?*anyopaque) void
processCurrentPath: *const fn (?*anyopaque, buffer: []u8) std.process.CurrentPathError!usize
processSetCurrentDir: *const fn (?*anyopaque, Dir) std.process.SetCurrentDirError!void
processSetCurrentPath: *const fn (?*anyopaque, []const u8) std.process.SetCurrentPathError!void
processReplace: *const fn (?*anyopaque, std.process.ReplaceOptions) std.process.ReplaceError
processSpawn: *const fn (?*anyopaque, std.process.SpawnOptions) std.process.SpawnError!std.process.Child
childWait: *const fn (?*anyopaque, *std.process.Child) std.process.Child.WaitError!std.process.Child.Term
childKill: *const fn (?*anyopaque, *std.process.Child) void
progressParentFile: *const fn (?*anyopaque) std.Progress.ParentFileError!File
inheritParentDir: *const fn (?*anyopaque, handle: Dir.Handle) InheritParentHandleError!Dir
inheritParentFile: *const fn (?*anyopaque, handle: File.Handle, flags: File.Flags) InheritParentHandleError!File
now: *const fn (?*anyopaque, Clock) Timestamp
clockResolution: *const fn (?*anyopaque, Clock) Clock.ResolutionError!Duration
sleep: *const fn (?*anyopaque, Timeout) Cancelable!void
random: *const fn (?*anyopaque, buffer: []u8) void
randomSecure: *const fn (?*anyopaque, buffer: []u8) RandomSecureError!void
netListenIp: *const fn (?*anyopaque, address: *const net.IpAddress, net.IpAddress.ListenOptions) net.IpAddress.ListenError!net.Socket
netAccept: *const fn (?*anyopaque, server: net.Socket.Handle, options: net.Server.AcceptOptions) net.Server.AcceptError!net.Socket
netBindIp: *const fn (?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.BindOptions) net.IpAddress.BindError!net.Socket
netConnectIp: *const fn (?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.ConnectOptions) net.IpAddress.ConnectError!net.Socket
netListenUnix: *const fn (?*anyopaque, *const net.UnixAddress, net.UnixAddress.ListenOptions) net.UnixAddress.ListenError!net.Socket.Handle
netConnectUnix: *const fn (?*anyopaque, *const net.UnixAddress) net.UnixAddress.ConnectError!net.Socket.Handle
netSocketCreatePair: *const fn (?*anyopaque, net.Socket.CreatePairOptions) net.Socket.CreatePairError![2]net.Socket
netWriteFile: *const fn (?*anyopaque, net.Socket.Handle, header: []const u8, *Io.File.Reader, Io.Limit) net.Stream.Writer.WriteFileError!usize
netClose: *const fn (?*anyopaque, sockets: []const net.Socket) void
netShutdown: *const fn (?*anyopaque, handle: net.Socket.Handle, how: net.ShutdownHow) net.ShutdownError!void
netInterfaceNameResolve: *const fn (?*anyopaque, *const net.Interface.Name) net.Interface.Name.ResolveError!net.Interface
netInterfaceName: *const fn (?*anyopaque, net.Interface) net.Interface.NameError!net.Interface.Name
netLookup: *const fn (?*anyopaque, net.HostName, *Queue(net.HostName.LookupResult), net.HostName.LookupOptions) net.HostName.LookupError!void

std.Io.Writer

别名

第 42 行

别名目标 std.Io.Writer

源码

std/Io.zig

//! 抽象所有 I/O 操作与并发的
//! 跨平台接口,包括:
//! * 文件系统
//! * 网络
//! * 进程
//! * 时间与休眠
//! * 随机性
//! * 异步、等待、并发和取消
//! * 并发队列
//! * 等待组和选择
//! * 互斥锁、futex、事件和条件变量
//! * 内存映射文件
//! 此接口使程序员在执行这些操作时,
//! 能够编写高效且可复用的代码。
const Io = @This();

const builtin = @import("builtin");

const std = @import("std.zig");
const math = std.math;
const assert = std.debug.assert;
const Allocator = std.mem.Allocator;
const Alignment = std.mem.Alignment;

userdata: ?*anyopaque,
vtable: *const VTable,

pub const Threaded = @import("Io/Threaded.zig");

pub const fiber = @import("Io/fiber.zig");
pub const Evented = if (fiber.supported) switch (builtin.os.tag) {
    .linux => Uring,
    .dragonfly, .freebsd, .netbsd, .openbsd => Kqueue,
    .driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos => Dispatch,
    else => void,
} else void; // 上下文切换代码尚未实现
pub const Dispatch = @import("Io/Dispatch.zig");
pub const Kqueue = @import("Io/Kqueue.zig");
pub const Uring = @import("Io/Uring.zig");

pub const Reader = @import("Io/Reader.zig");
pub const Writer = @import("Io/Writer.zig");
pub const net = @import("Io/net.zig");
pub const Dir = @import("Io/Dir.zig");
pub const File = @import("Io/File.zig");
pub const Terminal = @import("Io/Terminal.zig");

pub const RwLock = @import("Io/RwLock.zig");
pub const Semaphore = @import("Io/Semaphore.zig");

pub const VTable = struct {
    crashHandler: *const fn (?*anyopaque) void,

    /// 若返回 `null`,表示 `result` 已填充,
    /// `await` 将为空操作。
    ///
    /// 线程安全。
    async: *const fn (
        /// 对应 `Io.userdata`。
        userdata: ?*anyopaque,
        /// 此切片的指针是一个“立即求值”的结果值。
        /// 长度为结果类型的字节大小。
        /// 此函数调用结束后,该指针的生命周期立即终止。
        result: []u8,
        result_alignment: std.mem.Alignment,
        /// 复制后传给 `start`。
        context: []const u8,
        context_alignment: std.mem.Alignment,
        start: *const fn (context: *const anyopaque, result: *anyopaque) void,
    ) ?*AnyFuture,
    /// 线程安全。
    concurrent: *const fn (
        /// 对应 `Io.userdata`。
        userdata: ?*anyopaque,
        result_len: usize,
        result_alignment: std.mem.Alignment,
        /// 复制后传给 `start`。
        context: []const u8,
        context_alignment: std.mem.Alignment,
        start: *const fn (context: *const anyopaque, result: *anyopaque) void,
    ) ConcurrentError!*AnyFuture,
    /// 仅当 `async` 返回非 null 值时调用此函数。
    ///
    /// 线程安全。
    await: *const fn (
        /// 对应 `Io.userdata`。
        userdata: ?*anyopaque,
        /// 与 `async` 返回的值相同。
        any_future: *AnyFuture,
        /// 指向写入结果的缓冲区。
        /// 长度等于结果类型的字节大小。
        result: []u8,
        result_alignment: std.mem.Alignment,
    ) void,
    /// 等价于 `await`,但会发起取消请求。
    ///
    /// 仅当 `async` 返回非 null 值时调用此函数。
    ///
    /// 线程安全。
    cancel: *const fn (
        /// 对应 `Io.userdata`。
        userdata: ?*anyopaque,
        /// 与 `async` 返回的值相同。
        any_future: *AnyFuture,
        /// 指向写入结果的缓冲区。
        /// 长度等于结果类型的字节大小。
        result: []u8,
        result_alignment: std.mem.Alignment,
    ) void,

    /// 线程安全。
    groupAsync: *const fn (
        /// 对应 `Io.userdata`。
        userdata: ?*anyopaque,
        /// 已生成异步任务的所有者。
        group: *Group,
        /// 复制后传给 `start`。
        context: []const u8,
        context_alignment: std.mem.Alignment,
        start: *const fn (context: *const anyopaque) void,
    ) void,
    /// 线程安全。
    groupConcurrent: *const fn (
        /// 对应 `Io.userdata`。
        userdata: ?*anyopaque,
        /// 已生成异步任务的所有者。
        group: *Group,
        /// 复制后传给 `start`。
        context: []const u8,
        context_alignment: std.mem.Alignment,
        start: *const fn (context: *const anyopaque) void,
    ) ConcurrentError!void,
    groupAwait: *const fn (?*anyopaque, *Group, token: *anyopaque) Cancelable!void,
    groupCancel: *const fn (?*anyopaque, *Group, token: *anyopaque) void,

    recancel: *const fn (?*anyopaque) void,
    swapCancelProtection: *const fn (?*anyopaque, new: CancelProtection) CancelProtection,
    checkCancel: *const fn (?*anyopaque) Cancelable!void,

    futexWait: *const fn (?*anyopaque, ptr: *const u32, expected: u32, Timeout) Cancelable!void,
    futexWaitUncancelable: *const fn (?*anyopaque, ptr: *const u32, expected: u32) void,
    futexWake: *const fn (?*anyopaque, ptr: *const u32, max_waiters: u32) void,

    operate: *const fn (?*anyopaque, Operation) Cancelable!Operation.Result,
    batchAwaitAsync: *const fn (?*anyopaque, *Batch) Cancelable!void,
    batchAwaitConcurrent: *const fn (?*anyopaque, *Batch, Timeout) Batch.AwaitConcurrentError!void,
    batchCancel: *const fn (?*anyopaque, *Batch) void,

    dirCreateDir: *const fn (?*anyopaque, Dir, []const u8, Dir.Permissions) Dir.CreateDirError!void,
    dirCreateDirPath: *const fn (?*anyopaque, Dir, []const u8, Dir.Permissions) Dir.CreateDirPathError!Dir.CreatePathStatus,
    dirCreateDirPathOpen: *const fn (?*anyopaque, Dir, []const u8, Dir.Permissions, Dir.OpenOptions) Dir.CreateDirPathOpenError!Dir,
    dirOpenDir: *const fn (?*anyopaque, Dir, []const u8, Dir.OpenOptions) Dir.OpenError!Dir,
    dirStat: *const fn (?*anyopaque, Dir) Dir.StatError!Dir.Stat,
    dirStatFile: *const fn (?*anyopaque, Dir, []const u8, Dir.StatFileOptions) Dir.StatFileError!File.Stat,
    dirAccess: *const fn (?*anyopaque, Dir, []const u8, Dir.AccessOptions) Dir.AccessError!void,
    dirCreateFile: *const fn (?*anyopaque, Dir, []const u8, Dir.CreateFileOptions) File.OpenError!File,
    dirCreateFileAtomic: *const fn (?*anyopaque, Dir, []const u8, Dir.CreateFileAtomicOptions) Dir.CreateFileAtomicError!File.Atomic,
    dirOpenFile: *const fn (?*anyopaque, Dir, []const u8, Dir.OpenFileOptions) File.OpenError!File,
    dirClose: *const fn (?*anyopaque, []const Dir) void,
    dirRead: *const fn (?*anyopaque, *Dir.Reader, []Dir.Entry) Dir.Reader.Error!usize,
    dirRealPath: *const fn (?*anyopaque, Dir, out_buffer: []u8) Dir.RealPathError!usize,
    dirRealPathFile: *const fn (?*anyopaque, Dir, path_name: []const u8, out_buffer: []u8) Dir.RealPathFileError!usize,
    dirDeleteFile: *const fn (?*anyopaque, Dir, []const u8) Dir.DeleteFileError!void,
    dirDeleteDir: *const fn (?*anyopaque, Dir, []const u8) Dir.DeleteDirError!void,
    dirRename: *const fn (?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8) Dir.RenameError!void,
    dirRenamePreserve: *const fn (?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8) Dir.RenamePreserveError!void,
    dirSymLink: *const fn (?*anyopaque, Dir, target_path: []const u8, sym_link_path: []const u8, Dir.SymLinkFlags) Dir.SymLinkError!void,
    dirReadLink: *const fn (?*anyopaque, Dir, sub_path: []const u8, buffer: []u8) Dir.ReadLinkError!usize,
    dirSetOwner: *const fn (?*anyopaque, Dir, ?File.Uid, ?File.Gid) Dir.SetOwnerError!void,
    dirSetFileOwner: *const fn (?*anyopaque, Dir, []const u8, ?File.Uid, ?File.Gid, Dir.SetFileOwnerOptions) Dir.SetFileOwnerError!void,
    dirSetPermissions: *const fn (?*anyopaque, Dir, Dir.Permissions) Dir.SetPermissionsError!void,
    dirSetFilePermissions: *const fn (?*anyopaque, Dir, []const u8, File.Permissions, Dir.SetFilePermissionsOptions) Dir.SetFilePermissionsError!void,
    dirSetTimestamps: *const fn (?*anyopaque, Dir, []const u8, Dir.SetTimestampsOptions) Dir.SetTimestampsError!void,
    dirHardLink: *const fn (?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, Dir.HardLinkOptions) Dir.HardLinkError!void,

    fileStat: *const fn (?*anyopaque, File) File.StatError!File.Stat,
    fileLength: *const fn (?*anyopaque, File) File.LengthError!u64,
    fileClose: *const fn (?*anyopaque, []const File) void,
    fileWritePositional: *const fn (?*anyopaque, File, header: []const u8, data: []const []const u8, splat: usize, offset: u64) File.WritePositionalError!usize,
    fileWriteFileStreaming: *const fn (?*anyopaque, File, header: []const u8, *Io.File.Reader, Io.Limit) File.Writer.WriteFileError!usize,
    fileWriteFilePositional: *const fn (?*anyopaque, File, header: []const u8, *Io.File.Reader, Io.Limit, offset: u64) File.WriteFilePositionalError!usize,
    /// 在末尾或超过末尾读取时返回 0。
    fileReadPositional: *const fn (?*anyopaque, File, data: []const []u8, offset: u64) File.ReadPositionalError!usize,
    fileSeekBy: *const fn (?*anyopaque, File, relative_offset: i64) File.SeekError!void,
    fileSeekTo: *const fn (?*anyopaque, File, absolute_offset: u64) File.SeekError!void,
    fileSync: *const fn (?*anyopaque, File) File.SyncError!void,
    fileIsTty: *const fn (?*anyopaque, File) Cancelable!bool,
    fileEnableAnsiEscapeCodes: *const fn (?*anyopaque, File) File.EnableAnsiEscapeCodesError!void,
    fileSupportsAnsiEscapeCodes: *const fn (?*anyopaque, File) Cancelable!bool,
    fileSetLength: *const fn (?*anyopaque, File, u64) File.SetLengthError!void,
    fileSetOwner: *const fn (?*anyopaque, File, ?File.Uid, ?File.Gid) File.SetOwnerError!void,
    fileSetPermissions: *const fn (?*anyopaque, File, File.Permissions) File.SetPermissionsError!void,
    fileSetTimestamps: *const fn (?*anyopaque, File, File.SetTimestampsOptions) File.SetTimestampsError!void,
    fileLock: *const fn (?*anyopaque, File, File.Lock) File.LockError!void,
    fileTryLock: *const fn (?*anyopaque, File, File.Lock) File.LockError!bool,
    fileUnlock: *const fn (?*anyopaque, File) void,
    fileDowngradeLock: *const fn (?*anyopaque, File) File.DowngradeLockError!void,
    fileRealPath: *const fn (?*anyopaque, File, out_buffer: []u8) File.RealPathError!usize,
    fileHardLink: *const fn (?*anyopaque, File, Dir, []const u8, File.HardLinkOptions) File.HardLinkError!void,

    fileMemoryMapCreate: *const fn (?*anyopaque, File, File.MemoryMap.CreateOptions) File.MemoryMap.CreateError!File.MemoryMap,
    fileMemoryMapDestroy: *const fn (?*anyopaque, *File.MemoryMap) void,
    fileMemoryMapSetLength: *const fn (?*anyopaque, *File.MemoryMap, usize) File.MemoryMap.SetLengthError!void,
    fileMemoryMapRead: *const fn (?*anyopaque, *File.MemoryMap) File.ReadPositionalError!void,
    fileMemoryMapWrite: *const fn (?*anyopaque, *File.MemoryMap) File.WritePositionalError!void,

    processExecutableOpen: *const fn (?*anyopaque, Dir.OpenFileOptions) std.process.OpenExecutableError!File,
    processExecutablePath: *const fn (?*anyopaque, buffer: []u8) std.process.ExecutablePathError!usize,
    lockStderr: *const fn (?*anyopaque, ?Terminal.Mode) Cancelable!LockedStderr,
    tryLockStderr: *const fn (?*anyopaque, ?Terminal.Mode) Cancelable!?LockedStderr,
    unlockStderr: *const fn (?*anyopaque) void,
    processCurrentPath: *const fn (?*anyopaque, buffer: []u8) std.process.CurrentPathError!usize,
    processSetCurrentDir: *const fn (?*anyopaque, Dir) std.process.SetCurrentDirError!void,
    processSetCurrentPath: *const fn (?*anyopaque, []const u8) std.process.SetCurrentPathError!void,
    processReplace: *const fn (?*anyopaque, std.process.ReplaceOptions) std.process.ReplaceError,
    processSpawn: *const fn (?*anyopaque, std.process.SpawnOptions) std.process.SpawnError!std.process.Child,
    childWait: *const fn (?*anyopaque, *std.process.Child) std.process.Child.WaitError!std.process.Child.Term,
    childKill: *const fn (?*anyopaque, *std.process.Child) void,

    progressParentFile: *const fn (?*anyopaque) std.Progress.ParentFileError!File,
    inheritParentDir: *const fn (?*anyopaque, handle: Dir.Handle) InheritParentHandleError!Dir,
    inheritParentFile: *const fn (?*anyopaque, handle: File.Handle, flags: File.Flags) InheritParentHandleError!File,

    now: *const fn (?*anyopaque, Clock) Timestamp,
    clockResolution: *const fn (?*anyopaque, Clock) Clock.ResolutionError!Duration,
    sleep: *const fn (?*anyopaque, Timeout) Cancelable!void,

    random: *const fn (?*anyopaque, buffer: []u8) void,
    randomSecure: *const fn (?*anyopaque, buffer: []u8) RandomSecureError!void,

    netListenIp: *const fn (?*anyopaque, address: *const net.IpAddress, net.IpAddress.ListenOptions) net.IpAddress.ListenError!net.Socket,
    netAccept: *const fn (?*anyopaque, server: net.Socket.Handle, options: net.Server.AcceptOptions) net.Server.AcceptError!net.Socket,
    netBindIp: *const fn (?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.BindOptions) net.IpAddress.BindError!net.Socket,
    netConnectIp: *const fn (?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.ConnectOptions) net.IpAddress.ConnectError!net.Socket,
    netListenUnix: *const fn (?*anyopaque, *const net.UnixAddress, net.UnixAddress.ListenOptions) net.UnixAddress.ListenError!net.Socket.Handle,
    netConnectUnix: *const fn (?*anyopaque, *const net.UnixAddress) net.UnixAddress.ConnectError!net.Socket.Handle,
    netSocketCreatePair: *const fn (?*anyopaque, net.Socket.CreatePairOptions) net.Socket.CreatePairError![2]net.Socket,
    netWriteFile: *const fn (?*anyopaque, net.Socket.Handle, header: []const u8, *Io.File.Reader, Io.Limit) net.Stream.Writer.WriteFileError!usize,
    netClose: *const fn (?*anyopaque, sockets: []const net.Socket) void,
    netShutdown: *const fn (?*anyopaque, handle: net.Socket.Handle, how: net.ShutdownHow) net.ShutdownError!void,
    netInterfaceNameResolve: *const fn (?*anyopaque, *const net.Interface.Name) net.Interface.Name.ResolveError!net.Interface,
    netInterfaceName: *const fn (?*anyopaque, net.Interface) net.Interface.NameError!net.Interface.Name,
    netLookup: *const fn (?*anyopaque, net.HostName, *Queue(net.HostName.LookupResult), net.HostName.LookupOptions) net.HostName.LookupError!void,
};

pub const Operation = union(enum) {
    file_read_streaming: FileReadStreaming,
    file_write_streaming: FileWriteStreaming,
    /// Windows 上为 NtDeviceIoControlFile,POSIX 上为 ioctl。
    /// 其他系统上此标签不可达。
    device_io_control: DeviceIoControl,
    net_receive: NetReceive,
    net_send: NetSend,
    net_read: NetRead,
    net_write: NetWrite,

    pub const Tag = @typeInfo(Operation).@"union".tag_type.?;

    /// 读取可能返回 0,这与 `error.EndOfStream` 不同。
    pub const FileReadStreaming = struct {
        file: File,
        data: []const []u8,

        pub const Error = UnendingError || error{EndOfStream};
        pub const UnendingError = error{
            InputOutput,
            SystemResources,
            /// 尝试将目录文件描述符当作普通文件读取。
            IsDir,
            ConnectionResetByPeer,
            /// 打开文件时未授予读取能力。
            NotOpenForReading,
            SocketUnconnected,
            /// 已启用非阻塞模式,且从该文件描述符读取会阻塞。
            ///
            WouldBlock,
            /// 在 WASI 中,当文件描述符不具有读取
            /// 所需的权限时发生此错误。
            AccessDenied,
            /// 由于锁定而无法读取文件。根据 `Io` 实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。
            ///
            ///
            LockViolation,
        } || Io.UnexpectedError;

        pub const Result = Error!usize;
    };

    pub const FileWriteStreaming = struct {
        file: File,
        header: []const u8 = &.{},
        data: []const []const u8,
        splat: usize = 1,

        pub const Error = error{
            DiskQuota,
            FileTooBig,
            InputOutput,
            NoSpaceLeft,
            DeviceBusy,
            /// 文件描述符没有写入所需的权限。
            AccessDenied,
            PermissionDenied,
            /// 文件为未连接的套接字,或其读取端已关闭。
            BrokenPipe,
            /// 内核内存不足,无法从 in_fd 读取。
            SystemResources,
            NotOpenForWriting,
            /// 进程无法访问文件,因为另一进程已锁定
            /// 文件的一部分。仅限 Windows。
            LockViolation,
            /// 已启用非阻塞模式,而此操作将阻塞。
            WouldBlock,
            /// 写入设备期间,若设备在刷新之前或刷新途中断开,就会发生此错误:errno(6),没有此设备或地址。
            ///
            NoDevice,
            FileBusy,
        } || Io.UnexpectedError;

        pub const Result = Error!usize;
    };

    pub const DeviceIoControl = switch (builtin.os.tag) {
        .wasi => noreturn,
        .windows => struct {
            file: File,
            code: std.os.windows.CTL_CODE,
            in: []const u8 = &.{},
            out: []u8 = &.{},

            pub const Result = std.os.windows.IO_STATUS_BLOCK;
        },
        else => struct {
            file: File,
            /// 取决于设备的操作码。
            code: u32,
            arg: ?*anyopaque,

            /// 取决于设备及操作的结果。负值是
            /// 取负的 errno。
            pub const Result = i32;
        },
    };

    pub const NetReceive = struct {
        socket_handle: net.Socket.Handle,
        message_buffer: []net.IncomingMessage,
        data_buffer: []u8,
        flags: net.ReceiveFlags,

        pub const Error = error{
            /// 操作系统内部内存或其他资源不足。
            SystemResources,
            /// 已达到每进程可打开文件描述符数量上限。
            ProcessFdQuotaExceeded,
            /// 已达到系统范围内已打开文件的总数上限。
            SystemFdQuotaExceeded,
            /// 面向连接的套接字的本地端已关闭,或
            /// 该套接字从未连接。
            SocketUnconnected,
            /// 此套接字类型要求以原子方式发送消息,但待发送
            /// 消息的大小使其无法实现。消息未发送,
            /// 或仅发送了一部分。
            MessageOversize,
            /// 发送方意外关闭了网络连接。
            ConnectionResetByPeer,
            /// 用于到达目标的本地网络接口已离线。
            NetworkDown,
            /// 此前成功发送了无连接数据包,但远端系统的传输目标端口上没有运行任何服务,因此数据包未被接收。
            /// 这使得操作系统收到 ICMP 端口不可达数据包,并将其排队,以便下次在该绑定套接字上调用发送或接收操作时报告。
            ///
            ///
            ///
            ///
            PortUnreachable,
            /// 远端对等方未响应正在进行的通信,导致
            /// 操作系统中止连接。
            ConnectionTimedOut,
        } || Io.UnexpectedError;

        pub const Result = struct { ?net.Socket.ReceiveError, usize };
    };

    pub const NetSend = struct {
        socket_handle: net.Socket.Handle,
        messages: []net.OutgoingMessage,
        flags: net.SendFlags,

        pub const Error = error{
            /// 此套接字类型要求以原子方式发送消息,但待发送
            /// 消息的大小使其无法实现。消息未发送,
            /// 或仅发送了一部分。
            MessageOversize,
            /// 网络接口的输出队列已满。这通常表示
            /// 接口已停止发送,但也可能由短暂拥塞导致。通常,
            /// Linux 不会发生此错误;设备队列溢出时只会
            /// 静默丢弃分组。
            ///
            /// 可用内核内存不足时也会发生此错误。
            SystemResources,
            /// 没有到网络的路由。
            NetworkUnreachable,
            /// 可到达网络,但没有到主机的路由。
            HostUnreachable,
            /// 用于到达目标的本地网络接口已离线。
            NetworkDown,
            /// 目标地址未在侦听;对于无连接消息也可能发生此情况。
            ///
            ConnectionRefused,
            /// 操作系统或协议不支持该地址族。
            AddressFamilyUnsupported,
            /// 另一个 TCP 快速打开已在进行。
            FastOpenAlreadyInProgress,
            /// 网络会话被接收方意外关闭。
            ConnectionResetByPeer,
            /// 面向连接的套接字的本地端已关闭,或
            /// 该套接字从未连接。
            SocketUnconnected,
            /// 尝试向网络/广播地址发送数据,
            /// 却将其当作单播地址。
            AccessDenied,
            /// 远端对等方未响应正在进行的通信,导致
            /// 操作系统中止连接。
            ConnectionTimedOut,
        } || Io.UnexpectedError;

        pub const Result = struct { ?net.Socket.SendError, usize };
    };

    pub const NetRead = struct {
        socket_handle: net.Socket.Handle,
        data: [][]u8,
        control: []u8 = &.{},

        pub const Error = error{
            SystemResources,
            ConnectionResetByPeer,
            SocketUnconnected,
            /// 文件描述符不具有读取所需权限。
            AccessDenied,
            NetworkDown,
            /// 远端对等方未响应正在进行的通信,导致
            /// 操作系统中止连接。
            ConnectionTimedOut,
        } || Io.UnexpectedError;

        pub const Result = Error!net.Stream.ReadResult;
    };

    pub const NetWrite = struct {
        socket_handle: net.Socket.Handle,
        header: []const u8 = &.{},
        data: []const []const u8,
        splat: usize = 1,
        control: []const u8 = &.{},

        pub const Error = error{
            /// 另一个 TCP 快速打开已在进行。
            FastOpenAlreadyInProgress,
            /// 网络会话被接收方意外关闭。
            ConnectionResetByPeer,
            /// 网络接口的输出队列已满。这通常表示
            /// 接口已停止发送,但也可能由短暂拥塞导致。通常,
            /// Linux 不会发生此错误;设备队列溢出时只会
            /// 静默丢弃分组。
            ///
            /// 可用内核内存不足时也会发生此错误。
            SystemResources,
            /// 没有到网络的路由。
            NetworkUnreachable,
            /// 可到达网络,但没有到主机的路由。
            HostUnreachable,
            /// 用于到达目标的本地网络接口已关闭。
            NetworkDown,
            /// 目标地址未在监听。
            ConnectionRefused,
            /// 传入地址的 sa_family 字段未包含正确的地址族。
            AddressFamilyUnsupported,
            /// 面向连接的套接字的本地端已关闭,或
            /// 该套接字从未连接。
            SocketUnconnected,
            /// 远端对等方未响应正在进行的通信,导致
            /// 操作系统中止连接。
            ConnectionTimedOut,
            SocketNotBound,
        } || Io.UnexpectedError;

        pub const Result = Error!usize;
    };

    pub const Result = Result: {
        const operation_info = @typeInfo(Operation).@"union";
        const operation_count = operation_info.field_names.len;
        var field_names: [operation_count][]const u8 = undefined;
        var field_types: [operation_count]type = undefined;
        for (operation_info.field_names, operation_info.field_types, &field_names, &field_types) |f_name, f_type, *field_name, *field_type| {
            field_name.* = f_name;
            field_type.* = if (f_type == noreturn) noreturn else f_type.Result;
        }
        break :Result @Union(.auto, Tag, &field_names, &field_types, &@splat(.{}));
    };

    pub const Storage = union {
        unused: List.DoubleNode,
        submission: Submission,
        pending: Pending,
        completion: Completion,

        pub const Submission = struct {
            node: List.SingleNode,
            operation: Operation,
        };

        pub const Pending = struct {
            node: List.DoubleNode,
            tag: Tag,
            userdata: Userdata align(@max(@alignOf(usize), 4)),

            pub const Userdata = [7]usize;
        };

        pub const Completion = struct {
            node: List.SingleNode,
            result: Result,
        };
    };

    pub const OptionalIndex = enum(u32) {
        none = std.math.maxInt(u32),
        _,

        pub fn fromIndex(i: usize) OptionalIndex {
            const oi: OptionalIndex = @fromBackingInt(@intCast(i));
            assert(oi != .none);
            return oi;
        }

        pub fn toIndex(oi: OptionalIndex) u32 {
            assert(oi != .none);
            return @backingInt(oi);
        }
    };
    pub const List = struct {
        head: OptionalIndex,
        tail: OptionalIndex,

        pub const empty: List = .{ .head = .none, .tail = .none };

        pub const SingleNode = struct { next: OptionalIndex };
        pub const DoubleNode = struct { prev: OptionalIndex, next: OptionalIndex };
    };
};

/// 执行一个 `Operation`。
pub fn operate(io: Io, operation: Operation) Cancelable!Operation.Result {
    return io.vtable.operate(io.userdata, operation);
}

pub const OperateTimeoutError = Cancelable || Timeout.Error || ConcurrentError;

/// 使用给定 `timeout` 执行一个 `Operation`。
pub fn operateTimeout(io: Io, operation: Operation, timeout: Timeout) OperateTimeoutError!Operation.Result {
    if (timeout == .none) return io.vtable.operate(io.userdata, operation);
    var storage: [1]Operation.Storage = undefined;
    var batch: Batch = .init(&storage);
    batch.addAt(0, operation);
    try batch.awaitConcurrent(io, timeout);
    const completion = batch.next().?;
    assert(completion.index == 0);
    return completion.result;
}

/// 一次提交多个操作,无需等待全部操作
/// 完成。
///
/// 这是基于 `Operation` 的底层抽象。关于操作 `Future`
/// 的高层 API,参见 `Select` 和 `Group`。
pub const Batch = struct {
    storage: []Operation.Storage,
    unused: Operation.List,
    submitted: Operation.List,
    pending: Operation.List,
    completed: Operation.List,
    userdata: ?*anyopaque align(@max(@alignOf(?*anyopaque), 4)),

    /// 调用后,可以安全地无条件使用 defer 调用
    /// `cancel`。`storage` 是预分配、内容未定义的内存缓冲区,
    /// 决定可通过 `add` 和 `addAt` 提交的
    /// 最大活动操作数。
    pub fn init(storage: []Operation.Storage) Batch {
        var prev: Operation.OptionalIndex = .none;
        for (storage, 0..) |*operation, index| {
            operation.* = .{ .unused = .{ .prev = prev, .next = .fromIndex(index + 1) } };
            prev = .fromIndex(index);
        }
        storage[storage.len - 1].unused.next = .none;
        return .{
            .storage = storage,
            .unused = .{
                .head = .fromIndex(0),
                .tail = .fromIndex(storage.len - 1),
            },
            .submitted = .empty,
            .pending = .empty,
            .completed = .empty,
            .userdata = null,
        };
    }

    /// 添加一个在下次 await 调用时执行的操作。
    /// 返回该操作完成后 `next` 将返回的索引。
    /// 断言同时活动的操作不超过 `storage.len` 个。
    pub fn add(batch: *Batch, operation: Operation) u32 {
        const index = batch.unused.head.toIndex();
        batch.addAt(index, operation);
        return index;
    }

    /// 添加一个在下次 await 调用时执行的操作。
    /// 操作完成后,`next` 将返回 `index`。
    /// 断言 `index` 处的操作未处于活动状态。
    pub fn addAt(batch: *Batch, index: u32, operation: Operation) void {
        const storage = &batch.storage[index];
        const unused = storage.unused;
        switch (unused.prev) {
            .none => batch.unused.head = unused.next,
            else => |prev_index| batch.storage[prev_index.toIndex()].unused.next = unused.next,
        }
        switch (unused.next) {
            .none => batch.unused.tail = unused.prev,
            else => |next_index| batch.storage[next_index.toIndex()].unused.prev = unused.prev,
        }

        switch (batch.submitted.tail) {
            .none => batch.submitted.head = .fromIndex(index),
            else => |tail_index| batch.storage[tail_index.toIndex()].submission.node.next = .fromIndex(index),
        }
        storage.* = .{ .submission = .{ .node = .{ .next = .none }, .operation = operation } };
        batch.submitted.tail = .fromIndex(index);
    }

    pub const Completion = struct {
        /// 所提供操作存储中已完成的元素。
        /// 可使用 `addAt`,通过此 `index` 重新启用 `Batch`。
        index: u32,
        /// 此操作的返回值。
        result: Operation.Result,
    };

    /// 调用 `awaitAsync`、`awaitConcurrent` 或 `cancel` 后,
    /// 此函数会遍历已完成的操作。
    ///
    /// 每次此函数返回一个完成项时,都会将它从 `Batch` 出队。
    /// 再次等待之前无需取出所有完成项。
    pub fn next(batch: *Batch) ?Completion {
        const index = batch.completed.head;
        if (index == .none) return null;
        const storage = &batch.storage[index.toIndex()];
        const completion = storage.completion;
        const next_index = completion.node.next;
        batch.completed.head = next_index;
        if (next_index == .none) batch.completed.tail = .none;

        const tail_index = batch.unused.tail;
        switch (tail_index) {
            .none => batch.unused.head = index,
            else => batch.storage[tail_index.toIndex()].unused.next = index,
        }
        storage.* = .{ .unused = .{ .prev = tail_index, .next = .none } };
        batch.unused.tail = index;
        return .{ .index = index.toIndex(), .result = completion.result };
    }

    /// 等待至少一个已提交操作完成。此函数返回后,可通过 `next` 迭代已完成操作。
    ///
    /// 此函数允许实现在批量操作之间引入并发,但与 `awaitConcurrent` 不同,并不要求一定并发,因此不会因 `error.ConcurrencyUnavailable` 失败。
    ///
    ///
    ///
    ///
    ///
    pub fn awaitAsync(batch: *Batch, io: Io) Cancelable!void {
        return io.vtable.batchAwaitAsync(io.userdata, batch);
    }

    pub const AwaitConcurrentError = ConcurrentError || Cancelable || Timeout.Error;

    /// 等待已提交操作中至少一个完成。
    /// 函数返回后,可通过 `next` 迭代
    /// 已完成操作。
    ///
    /// 与 `awaitAsync` 不同,此函数要求实现
    /// 并发执行操作,因此可能失败并返回
    /// `error.ConcurrencyUnavailable`。
    pub fn awaitConcurrent(batch: *Batch, io: Io, timeout: Timeout) AwaitConcurrentError!void {
        return io.vtable.batchAwaitConcurrent(io.userdata, batch, timeout);
    }

    /// 请求中断所有未完成操作,然后等待所有
    /// 未完成操作结束。返回后,`Batch` 处于
    /// 定义明确的状态,可通过 `next` 迭代。成功
    /// 取消的操作不会出现在迭代中。某些操作
    /// 可能不受取消请求影响而成功完成,
    /// 它们会出现在迭代中。
    pub fn cancel(batch: *Batch, io: Io) void {
        { // 中止待处理的提交
            var tail_index = batch.unused.tail;
            defer batch.unused.tail = tail_index;
            var index = batch.submitted.head;
            errdefer batch.submissions.head = index;
            while (index != .none) {
                const next_index = batch.storage[index.toIndex()].submission.node.next;
                switch (tail_index) {
                    .none => batch.unused.head = index,
                    else => batch.storage[tail_index.toIndex()].unused.next = index,
                }
                batch.storage[index.toIndex()] = .{ .unused = .{ .prev = tail_index, .next = .none } };
                tail_index = index;
                index = next_index;
            }
            batch.submitted = .{ .head = .none, .tail = .none };
        }
        io.vtable.batchCancel(io.userdata, batch);
        assert(batch.submitted.head == .none and batch.submitted.tail == .none);
        assert(batch.pending.head == .none and batch.pending.tail == .none);
        assert(batch.userdata == null); // 这是释放资源的最后机会
    }
};

pub const Limit = enum(usize) {
    nothing = 0,
    unlimited = math.maxInt(usize),
    _,

    /// `math.maxInt(usize)` 被解释为 `.unlimited`。
    pub fn limited(n: usize) Limit {
        return @fromBackingInt(@intCast(n));
    }

    /// 大于 `math.maxInt(usize)` 的任何值均被解释为 `.unlimited`。
    ///
    pub fn limited64(n: u64) Limit {
        return @fromBackingInt(@intCast(@min(n, math.maxInt(usize))));
    }

    pub fn countVec(data: []const []const u8) Limit {
        var total: usize = 0;
        for (data) |d| total += d.len;
        return .limited(total);
    }

    pub fn min(a: Limit, b: Limit) Limit {
        return @fromBackingInt(@intCast(@min(@backingInt(a), @backingInt(b))));
    }

    pub fn max(a: Limit, b: Limit) Limit {
        if (a == .unlimited or b == .unlimited) {
            return .unlimited;
        }

        return @fromBackingInt(@intCast(@max(@backingInt(a), @backingInt(b))));
    }

    pub fn minInt(l: Limit, n: usize) usize {
        return @min(n, @backingInt(l));
    }

    pub fn minInt64(l: Limit, n: u64) usize {
        return @min(n, @backingInt(l));
    }

    pub fn slice(l: Limit, s: []u8) []u8 {
        return s[0..l.minInt(s.len)];
    }

    pub fn sliceConst(l: Limit, s: []const u8) []const u8 {
        return s[0..l.minInt(s.len)];
    }

    pub fn toInt(l: Limit) ?usize {
        return switch (l) {
            else => @backingInt(l),
            .unlimited => null,
        };
    }

    pub fn toInt64(l: Limit) ?u64 {
        return switch (l) {
            else => @backingInt(l),
            .unlimited => null,
        };
    }

    /// 根据限制缩短切片,但在限制之外额外保留
    /// 一个字节的空间,以便区分
    /// 到达流末尾与达到限制这两种情况。
    pub fn slice1(l: Limit, non_empty_buffer: []u8) []u8 {
        assert(non_empty_buffer.len >= 1);
        return non_empty_buffer[0..@min(@backingInt(l) +| 1, non_empty_buffer.len)];
    }

    pub fn nonzero(l: Limit) bool {
        return l != .nothing;
    }

    /// 返回减去 `amount` 后的新限制,
    /// 或返回 `null` 表示将超出限制。
    pub fn subtract(l: Limit, amount: usize) ?Limit {
        if (l == .unlimited) return .unlimited;
        if (amount > @backingInt(l)) return null;
        return @fromBackingInt(@intCast(@backingInt(l) - amount));
    }
};

pub const Cancelable = error{
    /// 调用方请求停止异步操作。
    Canceled,
};

pub const UnexpectedError = error{
    /// 操作系统返回了未记录在文档中的错误码。
    ///
    /// 理论上不可能出现此错误,但处理
    /// 此错误优于触发未定义行为。
    ///
    /// 观察到此错误码时,通常意味着 Zig 标准
    /// 库需要小幅修补,将该错误码加入
    /// 相应函数的错误集合。
    Unexpected,
};

pub const InheritParentHandleError = error{
    UnsupportedOperation,
} || Cancelable || UnexpectedError;

pub const Clock = enum {
    /// 可设置的系统全局时钟,用于测量实际时间(即墙上时钟时间)。系统时间的不连续跳变(例如系统管理员手动调整时钟)以及 NTP 等应用程序进行的频率调整,都会影响此时钟。
    ///
    /// 此时钟通常计算自协调世界时 (UTC) 1970-01-01 00:00:00 起经过的秒数,但忽略闰秒;临近闰秒时,NTP 通常会调整该时钟,使其大致与 UTC 保持同步。
    ///
    /// 此时钟实现返回的时间戳表示自 POSIX/Unix 纪元 1970-01-01T00:00:00Z 起经过的时间,不计闰秒。通常称为“Unix 时间”。若底层操作系统的原生时间戳使用其他纪元(如 Windows 使用 1601-01-01),则进行相应转换。
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    real,
    /// 不可设置的系统级时钟,表示自过去某个
    /// 未指定时间点以来经过的时间。
    ///
    /// 单调性:保证连续调用返回的时间
    /// 不会倒退,但相邻调用可能返回相同
    /// 而未增加的时间值。
    ///
    /// 不受系统时间不连续跳变的影响,例如
    /// 管理员手动调整时钟;但可能
    /// 受到频率调整的影响。
    ///
    /// 此时钟的意图是**不计入系统
    /// 挂起的时间**。不过,实现可能无法满足
    /// 这一要求,从而将其计入。
    ///
    /// * Linux 上对应 `CLOCK_MONOTONIC`。
    /// * macOS 上对应 `CLOCK_UPTIME_RAW`。
    awake,
    /// 与 `awake` 相同,但表达出**将系统挂起的时间也计入**的意图;
    /// 不过,由于平台限制,其行为可能与 `awake` 完全相同。
    ///
    /// * Linux 上对应 `CLOCK_BOOTTIME`。
    /// * macOS 上对应 `CLOCK_MONOTONIC_RAW`。
    ///
    boot,
    /// 跟踪调用进程在用户态或内核态使用的 CPU 时间。
    ///
    cpu_process,
    /// 跟踪调用线程在用户模式或内核模式下消耗的
    /// CPU 时间。
    cpu_thread,

    /// 此函数不会阻塞,因此不可取消。
    ///
    /// 分辨率由 `resolution` 确定;
    /// 若不支持此时钟,该值可能为 0。
    ///
    /// 另见:
    /// * `Clock.Timestamp.now`
    pub fn now(clock: Clock, io: Io) Io.Timestamp {
        return io.vtable.now(io.userdata, clock);
    }

    pub const ResolutionError = error{
        ClockUnavailable,
        Unexpected,
    };

    /// 提供 `clock` 的粒度。可能为零,表示时钟不受支持。
    ///
    pub fn resolution(clock: Clock, io: Io) ResolutionError!Io.Duration {
        return io.vtable.clockResolution(io.userdata, clock);
    }

    pub const Timestamp = struct {
        raw: Io.Timestamp,
        clock: Clock,

        /// 此函数不会阻塞,因此不可取消。
        ///
        /// 分辨率由 `resolution` 决定;若时钟不受支持,
        /// 则可能为 0。
        ///
        /// 另见:
        /// * `Clock.now`
        pub fn now(io: Io, clock: Clock) Clock.Timestamp {
            return .{
                .raw = io.vtable.now(io.userdata, clock),
                .clock = clock,
            };
        }

        /// 休眠至指定时间戳。
        ///
        /// 另请参见:
        /// * `Io.sleep`
        /// * `Clock.Duration.sleep`
        /// * `Timeout.sleep`
        pub fn wait(t: Clock.Timestamp, io: Io) Cancelable!void {
            return io.vtable.sleep(io.userdata, .{ .deadline = t });
        }

        pub fn durationTo(from: Clock.Timestamp, to: Clock.Timestamp) Clock.Duration {
            assert(from.clock == to.clock);
            return .{
                .raw = from.raw.durationTo(to.raw),
                .clock = from.clock,
            };
        }

        pub fn addDuration(from: Clock.Timestamp, duration: Clock.Duration) Clock.Timestamp {
            assert(from.clock == duration.clock);
            return .{
                .raw = from.raw.addDuration(duration.raw),
                .clock = from.clock,
            };
        }

        pub fn subDuration(from: Clock.Timestamp, duration: Clock.Duration) Clock.Timestamp {
            assert(from.clock == duration.clock);
            return .{
                .raw = from.raw.subDuration(duration.raw),
                .clock = from.clock,
            };
        }

        /// 分辨率由 `resolution` 决定;若时钟不受支持,其值可能为 0。
        ///
        pub fn fromNow(io: Io, duration: Clock.Duration) Clock.Timestamp {
            return .{
                .clock = duration.clock,
                .raw = duration.clock.now(io).addDuration(duration.raw),
            };
        }

        /// 分辨率由 `resolution` 决定;若时钟不受支持,其值可能为 0。
        ///
        pub fn untilNow(timestamp: Clock.Timestamp, io: Io) Clock.Duration {
            const now_ts = Clock.Timestamp.now(io, timestamp.clock);
            return timestamp.durationTo(now_ts);
        }

        /// 分辨率由 `resolution` 决定;若时钟不受支持,其值可能为 0。
        ///
        pub fn durationFromNow(timestamp: Clock.Timestamp, io: Io) Clock.Duration {
            const now_ts = timestamp.clock.now(io);
            return .{
                .clock = timestamp.clock,
                .raw = now_ts.durationTo(timestamp.raw),
            };
        }

        /// 分辨率由 `resolution` 决定;若时钟不受支持,其值可能为 0。
        ///
        pub fn toClock(t: Clock.Timestamp, io: Io, clock: Clock) Clock.Timestamp {
            if (t.clock == clock) return t;
            const now_old = t.clock.now(io);
            const now_new = clock.now(io);
            const duration = now_old.durationTo(t.raw);
            return .{
                .clock = clock,
                .raw = now_new.addDuration(duration),
            };
        }

        pub fn compare(lhs: Clock.Timestamp, op: math.CompareOperator, rhs: Clock.Timestamp) bool {
            assert(lhs.clock == rhs.clock);
            return math.compare(lhs.raw.nanoseconds, op, rhs.raw.nanoseconds);
        }
    };

    pub const Duration = struct {
        raw: Io.Duration,
        clock: Clock,

        /// 等待 `clock` 上经过指定时长。
        ///
        /// 另见:
        /// * `Io.sleep`
        /// * `Clock.Timestamp.wait`
        /// * `Timeout.sleep`
        pub fn sleep(duration: Clock.Duration, io: Io) Cancelable!void {
            return io.vtable.sleep(io.userdata, .{ .duration = duration });
        }
    };
};

pub const Timestamp = struct {
    nanoseconds: i96,

    pub fn now(io: Io, clock: Clock) Io.Timestamp {
        return io.vtable.now(io.userdata, clock);
    }

    pub const zero: Timestamp = .{ .nanoseconds = 0 };

    pub fn durationTo(from: Timestamp, to: Timestamp) Duration {
        return .{ .nanoseconds = to.nanoseconds - from.nanoseconds };
    }

    pub fn addDuration(from: Timestamp, duration: Duration) Timestamp {
        return .{ .nanoseconds = from.nanoseconds + duration.nanoseconds };
    }

    pub fn subDuration(from: Timestamp, duration: Duration) Timestamp {
        return .{ .nanoseconds = from.nanoseconds - duration.nanoseconds };
    }

    pub fn withClock(t: Timestamp, clock: Clock) Clock.Timestamp {
        return .{ .raw = t, .clock = clock };
    }

    pub fn fromNanoseconds(x: i96) Timestamp {
        return .{ .nanoseconds = x };
    }

    pub fn toMicroseconds(t: Timestamp) i64 {
        return @intCast(@divTrunc(t.nanoseconds, std.time.ns_per_us));
    }

    pub fn toMilliseconds(t: Timestamp) i64 {
        return @intCast(@divTrunc(t.nanoseconds, std.time.ns_per_ms));
    }

    pub fn toSeconds(t: Timestamp) i64 {
        return @intCast(@divTrunc(t.nanoseconds, std.time.ns_per_s));
    }

    pub fn toNanoseconds(t: Timestamp) i96 {
        return t.nanoseconds;
    }

    pub fn formatNumber(t: Timestamp, w: *std.Io.Writer, n: std.fmt.Number) std.Io.Writer.Error!void {
        return w.printInt(t.nanoseconds, n.mode.base() orelse 10, n.case, .{
            .precision = n.precision,
            .width = n.width,
            .alignment = n.alignment,
            .fill = n.fill,
        });
    }

    /// 分辨率由 `Clock.resolution` 决定;若不支持该时钟,
    /// 其值可能为 0。
    pub fn untilNow(t: Timestamp, io: Io, clock: Clock) Duration {
        const now_ts = clock.now(io);
        return t.durationTo(now_ts);
    }

    pub fn compare(lhs: Timestamp, op: math.CompareOperator, rhs: Timestamp) bool {
        return math.compare(lhs.nanoseconds, op, rhs.nanoseconds);
    }
};

pub const Duration = struct {
    nanoseconds: i96,

    pub const zero: Duration = .{ .nanoseconds = 0 };
    pub const max: Duration = .{ .nanoseconds = math.maxInt(i96) };

    pub fn fromNanoseconds(x: i96) Duration {
        return .{ .nanoseconds = x };
    }

    pub fn fromMicroseconds(x: i64) Duration {
        return .{ .nanoseconds = @as(i96, x) * std.time.ns_per_us };
    }

    pub fn fromMilliseconds(x: i64) Duration {
        return .{ .nanoseconds = @as(i96, x) * std.time.ns_per_ms };
    }

    pub fn fromSeconds(x: i64) Duration {
        return .{ .nanoseconds = @as(i96, x) * std.time.ns_per_s };
    }

    pub fn toMicroseconds(d: Duration) i64 {
        return @intCast(@divTrunc(d.nanoseconds, std.time.ns_per_us));
    }

    pub fn toMilliseconds(d: Duration) i64 {
        return @intCast(@divTrunc(d.nanoseconds, std.time.ns_per_ms));
    }

    pub fn toSeconds(d: Duration) i64 {
        return @intCast(@divTrunc(d.nanoseconds, std.time.ns_per_s));
    }

    pub fn toNanoseconds(d: Duration) i96 {
        return d.nanoseconds;
    }

    /// 按有符号数值的大小格式化纳秒数:
    /// `[#y][#w][#d][#h][#m]#[.###][n|u|m]s`
    pub fn format(duration: Duration, w: *Writer) Writer.Error!void {
        if (duration.nanoseconds < 0) try w.writeByte('-');
        return formatUnsigned(w, @abs(duration.nanoseconds));
    }

    fn formatUnsigned(w: *Writer, ns: u96) Writer.Error!void {
        var ns_remaining = ns;
        inline for (.{
            .{ .ns = 365 * std.time.ns_per_day, .sep = 'y' },
            .{ .ns = std.time.ns_per_week, .sep = 'w' },
            .{ .ns = std.time.ns_per_day, .sep = 'd' },
            .{ .ns = std.time.ns_per_hour, .sep = 'h' },
            .{ .ns = std.time.ns_per_min, .sep = 'm' },
        }) |unit| {
            if (ns_remaining >= unit.ns) {
                const units = ns_remaining / unit.ns;
                try w.printInt(units, 10, .lower, .{});
                try w.writeByte(unit.sep);
                ns_remaining -= units * unit.ns;
                if (ns_remaining == 0) return;
            }
        }

        inline for (.{
            .{ .ns = std.time.ns_per_s, .sep = "s" },
            .{ .ns = std.time.ns_per_ms, .sep = "ms" },
            .{ .ns = std.time.ns_per_us, .sep = "us" },
        }) |unit| {
            const kunits = ns_remaining * 1000 / unit.ns;
            if (kunits >= 1000) {
                try w.printInt(kunits / 1000, 10, .lower, .{});
                const frac = kunits % 1000;
                if (frac > 0) {
                    // 写入最多三位小数
                    var decimal_buf = [_]u8{ '.', 0, 0, 0 };
                    var inner: Writer = .fixed(decimal_buf[1..]);
                    inner.printInt(frac, 10, .lower, .{ .fill = '0', .width = 3 }) catch unreachable;
                    var end: usize = 4;
                    while (end > 1) : (end -= 1) {
                        if (decimal_buf[end - 1] != '0') break;
                    }
                    try w.writeAll(decimal_buf[0..end]);
                }
                return w.writeAll(unit.sep);
            }
        }

        try w.printInt(ns_remaining, 10, .lower, .{});
        try w.writeAll("ns");
    }

    test format {
        try testFormat("0ns", 0);
        try testFormat("1ns", 1);
        try testFormat("-1ns", -(1));
        try testFormat("999ns", std.time.ns_per_us - 1);
        try testFormat("-999ns", -(std.time.ns_per_us - 1));
        try testFormat("1us", std.time.ns_per_us);
        try testFormat("-1us", -(std.time.ns_per_us));
        try testFormat("1.45us", 1450);
        try testFormat("-1.45us", -(1450));
        try testFormat("1.5us", 3 * std.time.ns_per_us / 2);
        try testFormat("-1.5us", -(3 * std.time.ns_per_us / 2));
        try testFormat("14.5us", 14500);
        try testFormat("-14.5us", -(14500));
        try testFormat("145us", 145000);
        try testFormat("-145us", -(145000));
        try testFormat("999.999us", std.time.ns_per_ms - 1);
        try testFormat("-999.999us", -(std.time.ns_per_ms - 1));
        try testFormat("1ms", std.time.ns_per_ms + 1);
        try testFormat("-1ms", -(std.time.ns_per_ms + 1));
        try testFormat("1.5ms", 3 * std.time.ns_per_ms / 2);
        try testFormat("-1.5ms", -(3 * std.time.ns_per_ms / 2));
        try testFormat("1.11ms", 1110000);
        try testFormat("-1.11ms", -(1110000));
        try testFormat("1.111ms", 1111000);
        try testFormat("-1.111ms", -(1111000));
        try testFormat("1.111ms", 1111100);
        try testFormat("-1.111ms", -(1111100));
        try testFormat("999.999ms", std.time.ns_per_s - 1);
        try testFormat("-999.999ms", -(std.time.ns_per_s - 1));
        try testFormat("1s", std.time.ns_per_s);
        try testFormat("-1s", -(std.time.ns_per_s));
        try testFormat("59.999s", std.time.ns_per_min - 1);
        try testFormat("-59.999s", -(std.time.ns_per_min - 1));
        try testFormat("1m", std.time.ns_per_min);
        try testFormat("-1m", -(std.time.ns_per_min));
        try testFormat("1h", std.time.ns_per_hour);
        try testFormat("-1h", -(std.time.ns_per_hour));
        try testFormat("1d", std.time.ns_per_day);
        try testFormat("-1d", -(std.time.ns_per_day));
        try testFormat("1w", std.time.ns_per_week);
        try testFormat("-1w", -(std.time.ns_per_week));
        try testFormat("1y", 365 * std.time.ns_per_day);
        try testFormat("-1y", -(365 * std.time.ns_per_day));
        try testFormat("1y52w23h59m59.999s", 730 * std.time.ns_per_day - 1); // 365d = 52w1d
        try testFormat("-1y52w23h59m59.999s", -(730 * std.time.ns_per_day - 1)); // 365d = 52w1d
        try testFormat("1y1h1.001s", 365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_s + std.time.ns_per_ms);
        try testFormat("-1y1h1.001s", -(365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_s + std.time.ns_per_ms));
        try testFormat("1y1h1s", 365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_s + 999 * std.time.ns_per_us);
        try testFormat("-1y1h1s", -(365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_s + 999 * std.time.ns_per_us));
        try testFormat("1y1h999.999us", 365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_ms - 1);
        try testFormat("-1y1h999.999us", -(365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_ms - 1));
        try testFormat("1y1h1ms", 365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_ms);
        try testFormat("-1y1h1ms", -(365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_ms));
        try testFormat("1y1h1ms", 365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_ms + 1);
        try testFormat("-1y1h1ms", -(365 * std.time.ns_per_day + std.time.ns_per_hour + std.time.ns_per_ms + 1));
        try testFormat("1y1m999ns", 365 * std.time.ns_per_day + std.time.ns_per_min + 999);
        try testFormat("-1y1m999ns", -(365 * std.time.ns_per_day + std.time.ns_per_min + 999));
        try testFormat("292y24w3d23h47m16.854s", std.math.maxInt(i64));
        try testFormat("-292y24w3d23h47m16.854s", std.math.minInt(i64) + 1);
        try testFormat("-292y24w3d23h47m16.854s", std.math.minInt(i64));
    }

    fn testFormat(expected: []const u8, input: i96) !void {
        // 最坏情况:"-XXXXXXXXXXXXXyXXwXXdXXhXXmXX.XXXs".len = 34
        var buf: [34]u8 = undefined;
        var w: Writer = .fixed(&buf);
        try w.print("{f}", .{Duration{ .nanoseconds = input }});
        try std.testing.expectEqualStrings(expected, w.buffered());
    }
};

/// 声明操作应在何种条件下返回 `error.Timeout`。
pub const Timeout = union(enum) {
    /// `.none` 将无限等待
    none,
    duration: Clock.Duration,
    deadline: Clock.Timestamp,

    pub const Error = error{Timeout};

    pub fn toTimestamp(t: Timeout, io: Io) ?Clock.Timestamp {
        return switch (t) {
            .none => null,
            .duration => |d| .fromNow(io, d),
            .deadline => |d| d,
        };
    }

    pub fn toDeadline(t: Timeout, io: Io) Timeout {
        return switch (t) {
            .none => .none,
            .duration => |d| .{ .deadline = .fromNow(io, d) },
            .deadline => |d| .{ .deadline = d },
        };
    }

    pub fn toDurationFromNow(t: Timeout, io: Io) ?Clock.Duration {
        return switch (t) {
            .none => null,
            .duration => |d| d,
            .deadline => |d| d.durationFromNow(io),
        };
    }

    /// 等待至超时期限经过。
    ///
    /// 另请参见:
    /// * `Io.sleep`
    /// * `Clock.Duration.sleep`
    /// * `Clock.Timestamp.wait`
    pub fn sleep(timeout: Timeout, io: Io) Cancelable!void {
        return io.vtable.sleep(io.userdata, timeout);
    }
};

pub const AnyFuture = opaque {};

pub fn Future(Result: type) type {
    return struct {
        any_future: ?*AnyFuture,
        result: Result,

        /// 等同于 `await`,但会发出取消请求。这使任务在下一个
        /// “取消点”(若存在)收到 `error.Canceled`。取消点是
        /// 对 `Io` 中可返回 `error.Canceled` 的函数的调用。
        ///
        /// 请求取消任务后,仅该任务的下一个取消点
        /// 返回 `error.Canceled`,后续取消点不会再次发出取消信号。因此,
        /// 忽略 `error.Canceled` 通常是错误。若要推迟处理取消
        /// 请求,另请参见 `recancel` 和 `CancelProtection`。
        ///
        /// 幂等。非线程安全。
        pub fn cancel(f: *@This(), io: Io) Result {
            const any_future = f.any_future orelse return f.result;
            io.vtable.cancel(io.userdata, any_future, @ptrCast(&f.result), .of(Result));
            f.any_future = null;
            return f.result;
        }

        /// 幂等。非线程安全。
        pub fn await(f: *@This(), io: Io) Result {
            const any_future = f.any_future orelse return f.result;
            io.vtable.await(io.userdata, any_future, @ptrCast(&f.result), .of(Result));
            f.any_future = null;
            return f.result;
        }
    };
}

/// 无序任务集合,只能整体等待或取消。
/// 通过 `Group.async` 和 `Group.concurrent` 在组中生成任务。
///
/// *保证*每个任务关联的资源会在
/// 该任务返回时释放,而不必等整个组完成或
/// 被等待。因此,对于长时间存在且不断加入
/// 并发任务的组,这不属于资源泄漏。但异步
/// 任务只有在调用 `Group.await` 或 `Group.cancel` 后才保证
/// 运行,因此不断加入异步任务却从不等待该组,可能
/// 泄漏资源。
pub const Group = struct {
    /// 此值表示组中是否有待处理任务。`null`
    /// 表示没有待处理任务,也没有与组关联的资源,
    /// 因此 `await` 和 `cancel` 会直接返回,
    /// 不调用具体实现。这意味着必须原子访问 `token`,
    /// 以免与 `await` 和 `cancel` 中的检查产生竞态条件。
    token: std.atomic.Value(?*anyopaque),
    /// 实现可以自由使用此值。
    state: usize,

    pub const init: Group = .{ .token = .init(null), .state = 0 };

    /// 等同于 `Io.async`,但任务生成于此 `Group` 中,
    /// 而非与 `Future` 关联。
    ///
    /// `function` 的返回类型必须可强制转换为 `Cancelable!void`。
    /// `function` 返回 `error.Canceled` 不会产生任何作用,因为这里是
    /// 取消传播的边界。
    ///
    /// 一旦调用此函数,就会有资源关联到
    /// 该组。为释放这些资源,最终必须调用 `await` 或 `cancel`。
    ///
    /// `function` 只有在调用 `await` 或
    /// `cancel` 后才保证已被调用。
    ///
    pub fn async(g: *Group, io: Io, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function))) void {
        const Args = @TypeOf(args);
        const TypeErased = struct {
            fn start(context: *const anyopaque) void {
                const args_casted: *const Args = @ptrCast(@alignCast(context));
                _ = @as(Cancelable!void, @call(.auto, function, args_casted.*)) catch {};
            }
        };
        io.vtable.groupAsync(io.userdata, g, @ptrCast(&args), .of(Args), TypeErased.start);
    }

    /// 等同于 `Io.concurrent`,但任务创建在此
    /// `Group` 中,而不是与 `Future` 关联。
    ///
    /// `function` 的返回类型必须可强制转换为 `Cancelable!void`。
    /// `function` 返回 `error.Canceled` 不会执行额外操作,因为这里是
    /// 取消传播边界。
    ///
    /// 调用此函数后,就有资源与该组
    /// 关联。要释放这些资源,最终必须
    /// 调用 `Group.await` 或 `Group.cancel`。
    pub fn concurrent(g: *Group, io: Io, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function))) ConcurrentError!void {
        const Args = @TypeOf(args);
        const TypeErased = struct {
            fn start(context: *const anyopaque) void {
                const args_casted: *const Args = @ptrCast(@alignCast(context));
                _ = @as(Cancelable!void, @call(.auto, function, args_casted.*)) catch {};
            }
        };
        return io.vtable.groupConcurrent(io.userdata, g, @ptrCast(&args), .of(Args), TypeErased.start);
    }

    /// 阻塞至组内所有任务结束。此期间,
    /// 取消请求会传播至组内所有成员,
    /// 并使组最终完成时
    /// 返回 `error.Canceled`。
    ///
    /// 此函数返回后,保证 `Group` 中所有通过
    /// `async` 或 `concurrent` 创建的任务均已运行。
    ///
    /// 幂等。不保证线程安全。
    ///
    /// 可以安全地与 `Group.async` 或
    /// `Group.concurrent` 并发调用,但必须确保该组直到
    /// `Group.async` 或 `Group.concurrent` 调用返回后才完成。
    pub fn await(g: *Group, io: Io) Cancelable!void {
        const token = g.token.load(.acquire) orelse return;
        try io.vtable.groupAwait(io.userdata, g, token);
        assert(g.token.raw == null);
    }

    /// 等同于 `await`,但立即请求取消组内
    /// 全部成员。
    ///
    /// 此函数返回后,保证 `Group` 中所有通过
    /// `async` 或 `concurrent` 创建的任务均已运行。
    ///
    /// 取消及取消点的说明参见 `Future.cancel`。
    ///
    /// 幂等。不保证线程安全。
    ///
    /// 可以安全地与 `Group.async` 或
    /// `Group.concurrent` 并发调用,但必须确保该组直到
    /// `Group.async` 或 `Group.concurrent` 调用返回后才完成。
    pub fn cancel(g: *Group, io: Io) void {
        const token = g.token.load(.acquire) orelse return;
        io.vtable.groupCancel(io.userdata, g, token);
        assert(g.token.raw == null);
    }
};

/// 断言此前的取消点返回了 `error.Canceled`,并重新激活
/// 取消请求,使下一个取消点再次返回 `error.Canceled`。
///
/// 关于取消及取消点的说明,参见 `Future.cancel`。
///
pub fn recancel(io: Io) void {
    io.vtable.recancel(io.userdata);
}

/// 极少数情况下,需要完全阻止取消通知,使某段
/// 代码可不受打断地运行,然后才可能观察到 `error.Canceled`。因此,每个
/// 任务都有“取消保护”状态,表示 `Io` 函数是否可以引入
/// 取消点。
///
/// 修改任务取消保护状态,参见 `swapCancelProtection`。
///
/// 关于取消及取消点的说明,参见 `Future.cancel`。
pub const CancelProtection = enum(u1) {
    /// 调用任何错误集合包含 `error.Canceled` 的 `Io` 函数,都是取消点。
    ///
    /// 这是所有任务创建时的默认状态。
    unblocked = 0,
    /// 没有 `Io` 函数引入取消点(永远不会返回 `error.Canceled`)。
    blocked = 1,
};
/// 更新当前任务的取消保护状态,参见 `CancelProtection`。
///
/// 典型用法是保护一段代码,使其不被取消:
/// ```
/// const old_cancel_protect = io.swapCancelProtection(.blocked);
/// defer _ = io.swapCancelProtection(old_cancel_protect);
/// doSomeWork() catch |err| switch (err) {
///     error.Canceled => unreachable,
/// };
/// ```
///
/// 取消及取消点的说明参见 `Future.cancel`。
pub fn swapCancelProtection(io: Io, new: CancelProtection) CancelProtection {
    return io.vtable.swapCancelProtection(io.userdata, new);
}

/// 此函数仅作为取消点,受取消保护约束,参见 `CancelProtection`,
/// 除此之外不执行操作。也就是说,存在未被阻止的待处理取消请求时,返回 `error.Canceled`,
/// 否则不执行任何操作。
///
/// 通常无需调用此函数。主要用途是在耗时较长的 CPU 密集型
/// 任务中,在任务完成前响应取消请求。较短的任务,或者
/// 执行其他 `Io` 操作、因而包含其他取消点的任务,通常已经
/// 能够迅速响应取消请求。
///
/// 关于取消及取消点的说明,参见 `Future.cancel`。
pub fn checkCancel(io: Io) Cancelable!void {
    return io.vtable.checkCancel(io.userdata);
}

/// 共同执行任务,并提供等待一个或多个任务完成的机制。类似 `Batch`,但工作在更高层的任务抽象层,而不是较底层的 `Operation` 抽象层。
///
/// 给定的带标签联合体用作等待函数的返回类型。调用异步或并发接口时,需要指定被调用函数完成后的结果放入哪个联合体字段。
///
///
///
///
pub fn Select(comptime U: type) type {
    return struct {
        io: Io,
        group: Group,
        queue: Queue(U),

        const S = @This();

        pub const Union = U;

        pub const Field = std.meta.FieldEnum(U);

        pub fn init(io: Io, buffer: []U) S {
            return .{
                .io = io,
                .queue = .init(buffer),
                .group = .init,
            };
        }

        /// 异步调用 `function`,参数为 `args`。所创建资源由此选择器拥有。
        ///
        /// `function` 的返回类型必须与 `field` 字段匹配,该字段属于 `Union`。
        ///
        /// `function` 可能在 `async` 返回之前立即调用。
        ///
        /// 此函数返回时,保证 `function` 要么已调用并完成,要么已成功分配到一个并发执行单元。
        ///
        /// 调用此函数后,必须在选择器反初始化之前调用 `await` 或 `cancel`。
        ///
        /// 线程安全。
        ///
        /// 相关接口:
        /// * `Io.async`
        /// * `Group.async`
        ///
        ///
        ///
        ///
        pub fn async(
            s: *S,
            comptime field: Field,
            function: anytype,
            args: std.meta.ArgsTuple(@TypeOf(function)),
        ) void {
            const Context = struct {
                select: *S,
                args: @TypeOf(args),
                fn start(type_erased_context: *const anyopaque) void {
                    const context: *const @This() = @ptrCast(@alignCast(type_erased_context));
                    const result = @call(.auto, function, context.args);
                    const elem = @unionInit(U, @tagName(field), result);
                    context.select.queue.putOneUncancelable(context.select.io, elem) catch |err| switch (err) {
                        error.Closed => {},
                    };
                }
            };
            const context: Context = .{ .select = s, .args = args };
            s.io.vtable.groupAsync(s.io.userdata, &s.group, @ptrCast(&context), .of(Context), Context.start);
        }

        /// 并发调用 `function`,参数为 `args`。所创建资源由此选择器拥有。
        ///
        /// `function` 的返回类型必须与 `field` 字段匹配,该字段属于 `Union`。
        ///
        /// 此函数成功返回后,保证 `function` 已分配到一个并发执行单元,并且必须在选择器反初始化前调用 `await` 或 `cancel`。
        ///
        /// 线程安全。
        ///
        /// 相关接口:
        /// * `Io.concurrent`
        /// * `Group.concurrent`
        ///
        ///
        ///
        ///
        pub fn concurrent(
            s: *S,
            comptime field: Field,
            function: anytype,
            args: std.meta.ArgsTuple(@TypeOf(function)),
        ) ConcurrentError!void {
            const Context = struct {
                select: *S,
                args: @TypeOf(args),
                fn start(type_erased_context: *const anyopaque) void {
                    const context: *const @This() = @ptrCast(@alignCast(type_erased_context));
                    const result = @call(.auto, function, context.args);
                    const elem = @unionInit(U, @tagName(field), result);
                    context.select.queue.putOneUncancelable(context.select.io, elem) catch |err| switch (err) {
                        error.Closed => {},
                    };
                }
            };
            const context: Context = .{ .select = s, .args = args };
            try s.io.vtable.groupConcurrent(s.io.userdata, &s.group, @ptrCast(&context), .of(Context), Context.start);
        }

        /// 阻塞直到 select 中另一个任务完成。
        ///
        /// 此后仍可合法调用 `async` 和 `concurrent`。
        ///
        /// 线程安全。
        pub fn await(s: *S) Cancelable!U {
            return s.queue.getOne(s.io) catch |err| switch (err) {
                error.Canceled => |e| return e,
                error.Closed => unreachable,
            };
        }

        /// 阻塞直到至少有 `min` 个结果被复制
        /// 到 `buffer`。
        ///
        /// 断言 `buffer.len >= min`。
        ///
        /// 此后可以合法调用 `async` 和 `concurrent`。
        ///
        /// 线程安全。
        pub fn awaitMany(s: *S, buffer: []U, min: usize) Cancelable!usize {
            return s.queue.get(s.io, buffer, min) catch |err| switch (err) {
                error.Canceled => |e| return e,
                error.Closed => unreachable,
            };
        }

        /// 请求取消此选择器拥有的全部剩余任务,然后阻塞,直到这些任务全部结束。若初始化选择器时,缓冲区空间不足以容纳所有剩余任务的完成结果,则会死锁。
        ///
        /// 若任一选择任务分配了资源,该任务可能已经完成,因此必须循环调用此函数,直至返回 `null`,才能释放这些资源。若不存在资源泄漏的可能,则优先使用 `cancelDiscard`。
        ///
        /// 此后调用 `await` 或 `awaitMany` 属于非法操作。
        ///
        /// 可安全地多次调用此函数,即使此前已返回 `null`。
        ///
        /// 线程安全。
        ///
        ///
        ///
        ///
        ///
        ///
        ///
        ///
        pub fn cancel(s: *S) ?U {
            const io = s.io;
            s.group.cancel(io);
            s.queue.close(io);
            return s.queue.getOneUncancelable(io) catch |err| switch (err) {
                error.Closed => return null,
            };
        }

        /// 请求取消此 select 拥有的所有剩余任务,
        /// 然后阻塞至它们全部结束。
        ///
        /// 丢弃所有未完成任务的返回值。因此,
        /// 任务可能返回已分配资源时,不适合调用
        /// 此函数。此场景请参见 `cancel`。
        ///
        /// 此后调用 `await` 或 `awaitMany` 属于非法行为。
        ///
        /// 可以安全地多次调用。
        ///
        /// 线程安全。
        pub fn cancelDiscard(s: *S) void {
            const io = s.io;
            const token = s.group.token.load(.acquire) orelse return;
            s.queue.close(io);
            io.vtable.groupCancel(io.userdata, &s.group, token);
            assert(s.group.token.raw == null);
        }
    };
}

/// 原子检查 `ptr` 处的值是否等于 `expected`;如果相等,则阻塞,直到:
///
/// * 发生匹配的、即 `ptr` 参数相同的 `futexWake` 调用;或
/// * 发生伪唤醒,即“随机”唤醒。
///
/// 通常应在更新 `ptr.*` 处的值后立即调用 `futexWake`,
/// 以解除使用 `futexWait` 等待该值变化的任务的阻塞。
///
/// 必要时由调用方负责识别伪唤醒,通常通过检查
/// `ptr.*` 处的值来完成。
///
/// 断言 `T` 的长度为 4 字节,且布局明确、不含填充位。
pub fn futexWait(io: Io, comptime T: type, ptr: *align(@alignOf(u32)) const T, expected: T) Cancelable!void {
    return futexWaitTimeout(io, T, ptr, expected, .none);
}
/// 与 `futexWait` 相同,但 `timeout` 到期时也会解除阻塞。与 `futexWait` 一样,
/// 可能发生伪唤醒。若有必要,调用者仍负责区分这三种
/// 可能的唤醒原因。
pub fn futexWaitTimeout(io: Io, comptime T: type, ptr: *align(@alignOf(u32)) const T, expected: T, timeout: Timeout) Cancelable!void {
    const expected_int: u32 = switch (@typeInfo(T)) {
        .@"enum" => @bitCast(@backingInt(expected)),
        else => @bitCast(expected),
    };
    return io.vtable.futexWait(io.userdata, @ptrCast(ptr), expected_int, timeout);
}
/// 与 `futexWait` 相同,但不引入取消点。
///
/// 取消及取消点的说明见 `Future.cancel`。
pub fn futexWaitUncancelable(io: Io, comptime T: type, ptr: *align(@alignOf(u32)) const T, expected: T) void {
    const expected_int: u32 = switch (@typeInfo(T)) {
        .@"enum" => @bitCast(@backingInt(expected)),
        else => @bitCast(expected),
    };
    io.vtable.futexWaitUncancelable(io.userdata, @ptrCast(ptr), expected_int);
}
/// 解除对 `ptr` 的待处理 futex 等待,最多解除 `max_waiters` 个调用。
pub fn futexWake(io: Io, comptime T: type, ptr: *align(@alignOf(u32)) const T, max_waiters: u32) void {
    comptime assert(@sizeOf(T) == @sizeOf(u32));
    if (max_waiters == 0) return;
    return io.vtable.futexWake(io.userdata, @ptrCast(ptr), max_waiters);
}

/// Mutex 是一种同步原语,确保对称为“临界区”的
/// 共享代码区域进行原子访问。
///
/// Mutex 是 extern 结构体,因此可用作另一个
/// extern 结构体的字段。
pub const Mutex = extern struct {
    state: std.atomic.Value(State),

    pub const init: Mutex = .{ .state = .init(.unlocked) };

    pub const State = enum(u32) {
        unlocked,
        locked_once,
        contended,
    };

    pub fn tryLock(m: *Mutex) bool {
        return m.state.cmpxchgStrong(.unlocked, .locked_once, .acquire, .monotonic) == null;
    }

    pub fn lock(m: *Mutex, io: Io) Cancelable!void {
        const initial_state = m.state.cmpxchgStrong(
            .unlocked,
            .locked_once,
            .acquire,
            .monotonic,
        ) orelse {
            @branchHint(.likely);
            return;
        };
        if (initial_state == .contended) {
            try io.futexWait(State, &m.state.raw, .contended);
        }
        while (m.state.swap(.contended, .acquire) != .unlocked) {
            try io.futexWait(State, &m.state.raw, .contended);
        }
    }

    /// 与 `lock` 相同,但不引入取消点。
    ///
    /// 取消及取消点的说明见 `Future.cancel`。
    pub fn lockUncancelable(m: *Mutex, io: Io) void {
        const initial_state = m.state.cmpxchgStrong(
            .unlocked,
            .locked_once,
            .acquire,
            .monotonic,
        ) orelse {
            @branchHint(.likely);
            return;
        };
        if (initial_state == .contended) {
            io.futexWaitUncancelable(State, &m.state.raw, .contended);
        }
        while (m.state.swap(.contended, .acquire) != .unlocked) {
            io.futexWaitUncancelable(State, &m.state.raw, .contended);
        }
    }

    pub fn unlock(m: *Mutex, io: Io) void {
        switch (m.state.swap(.unlocked, .release)) {
            .unlocked => unreachable,
            .locked_once => {},
            .contended => {
                @branchHint(.unlikely);
                io.futexWake(State, &m.state.raw, 1);
            },
        }
    }
};

pub const Condition = struct {
    state: std.atomic.Value(State),
    /// 每当条件被触发时递增
    epoch: std.atomic.Value(u32),

    const State = packed struct(u32) {
        waiters: u16,
        signals: u16,
    };

    pub const init: Condition = .{
        .state = .init(.{ .waiters = 0, .signals = 0 }),
        .epoch = .init(0),
    };

    /// 阻塞,直到条件收到信号或操作被取消。
    ///
    /// 另请参见:
    /// * `waitUncancelable`
    /// * `waitTimeout`
    pub fn wait(cond: *Condition, io: Io, mutex: *Mutex) Cancelable!void {
        waitTimeout(cond, io, mutex, .none) catch |err| switch (err) {
            error.Timeout => unreachable,
            error.Canceled => |e| return e,
        };
    }

    pub const WaitTimeoutError = Cancelable || Timeout.Error;

    /// 阻塞直到条件被通知、被取消,或给定
    /// 超时到期。
    ///
    /// 另请参见:
    /// * `wait`
    /// * `waitUncancelable`
    pub fn waitTimeout(cond: *Condition, io: Io, mutex: *Mutex, timeout: Timeout) WaitTimeoutError!void {
        const deadline = timeout.toDeadline(io);

        var epoch = cond.epoch.load(.acquire); // 使用 `.acquire`,确保排序在状态加载之前。

        {
            const prev_state = cond.state.fetchAdd(.{ .waiters = 1, .signals = 0 }, .monotonic);
            assert(prev_state.waiters < math.maxInt(u16)); // 等待方过多导致溢出
        }

        mutex.unlock(io);
        defer mutex.lockUncancelable(io);

        while (true) {
            const result = io.futexWaitTimeout(u32, &cond.epoch.raw, epoch, deadline);

            epoch = cond.epoch.load(.acquire); // 使用 `.acquire`,确保顺序位于 `state` 加载之前

            // 我们正常地被唤醒,因此尝试消费待处理信号。信号的优先级
            // 高于已到期的截止时间,所以在下方检查截止时间
            // 之前先检查信号。若出错,我们会安全地移除自身的等待者身份并传播错误。
            if (result) |_| {
                var prev_state = cond.state.load(.monotonic);
                while (prev_state.signals > 0) {
                    prev_state = cond.state.cmpxchgWeak(prev_state, .{
                        .waiters = prev_state.waiters - 1,
                        .signals = prev_state.signals - 1,
                    }, .acquire, .monotonic) orelse {
                        // 成功消耗了一个信号。
                        return;
                    };
                }
            } else |err| {
                cond.deregister(io);
                return err;
            }

            // 无可用信号,也没有错误;若指定了超时,且
            // 已超过截止时间,则将自身从等待方中移除并返回
            // `error.Timeout`。否则,这是一次伪唤醒:重新进入
            // futex 等待循环。
            switch (deadline) {
                .none => {},
                .deadline => |d| if (d.untilNow(io).raw.nanoseconds >= 0) {
                    cond.deregister(io);
                    return error.Timeout;
                },
                .duration => unreachable,
            }
        }
    }

    /// 与 `wait` 相同,但不引入取消点。
    ///
    /// 关于取消点,参见 `Future.cancel`。
    pub fn waitUncancelable(cond: *Condition, io: Io, mutex: *Mutex) void {
        var epoch = cond.epoch.load(.acquire); // 使用 `.acquire`,确保排序在状态加载之前。

        {
            const prev_state = cond.state.fetchAdd(.{ .waiters = 1, .signals = 0 }, .monotonic);
            assert(prev_state.waiters < math.maxInt(u16)); // 等待方过多导致溢出
        }

        mutex.unlock(io);
        defer mutex.lockUncancelable(io);

        while (true) {
            io.futexWaitUncancelable(u32, &cond.epoch.raw, epoch);

            epoch = cond.epoch.load(.acquire); // 使用 `.acquire`,确保顺序位于 `state` 加载之前

            // 即使出错,也先尝试消费待处理信号。否则竞态可能
            // 使信号滞留在状态中,却没有对应的等待者。
            {
                var prev_state = cond.state.load(.monotonic);
                while (prev_state.signals > 0) {
                    prev_state = cond.state.cmpxchgWeak(prev_state, .{
                        .waiters = prev_state.waiters - 1,
                        .signals = prev_state.signals - 1,
                    }, .acquire, .monotonic) orelse {
                        // 成功消耗了一个信号。
                        return;
                    };
                }
            }

            // 没有更多可用信号;此次为虚假唤醒,
            // 因此循环返回 futex 等待。
        }
    }

    fn deregister(cond: *Condition, io: Io) void {
        var prev_state = cond.state.load(.monotonic);
        while (true) {
            const new_signals = @min(prev_state.signals, prev_state.waiters - 1);
            prev_state = cond.state.cmpxchgWeak(prev_state, .{
                .waiters = prev_state.waiters - 1,
                .signals = new_signals,
            }, .monotonic, .monotonic) orelse {
                if (prev_state.signals > 0 and prev_state.signals < prev_state.waiters) {
                    // 保留了一个当前不消费的信号;为其唤醒一个剩余等待者。
                    _ = cond.epoch.fetchAdd(1, .release);
                    io.futexWake(u32, &cond.epoch.raw, 1);
                }
                return;
            };
        }
    }

    pub fn signal(cond: *Condition, io: Io) void {
        var prev_state = cond.state.load(.monotonic);
        while (prev_state.waiters > prev_state.signals) {
            @branchHint(.unlikely);
            prev_state = cond.state.cmpxchgWeak(prev_state, .{
                .waiters = prev_state.waiters,
                .signals = prev_state.signals + 1,
            }, .release, .monotonic) orelse {
                // 更新纪元值,以告知等待线程有新的信号。
                // 注意,如果线程在观察纪元值与开始等待之间,*恰好*发生 (1<<32)-1 次唤醒,
                // 等待线程就可能漏掉一次获取;但由于要求如此精确的
                // 调用次数,发生概率极低。
                _ = cond.epoch.fetchAdd(1, .release); // 使用 `.release`,确保排序在 `state` 更新之后
                io.futexWake(u32, &cond.epoch.raw, 1);
                return;
            };
        }
    }

    pub fn broadcast(cond: *Condition, io: Io) void {
        var prev_state = cond.state.load(.monotonic);
        while (prev_state.waiters > prev_state.signals) {
            @branchHint(.unlikely);
            prev_state = cond.state.cmpxchgWeak(prev_state, .{
                .waiters = prev_state.waiters,
                .signals = prev_state.waiters,
            }, .release, .monotonic) orelse {
                // 更新纪元值,以告知等待线程有新的信号。
                // 注意,如果线程在观察纪元值与开始等待之间,*恰好*发生 (1<<32)-1 次唤醒,
                // 等待线程就可能漏掉一次获取;但由于要求如此精确的
                // 调用次数,发生概率极低。
                _ = cond.epoch.fetchAdd(1, .release); // 使用 `.release`,确保排序在 `state` 更新之后
                io.futexWake(u32, &cond.epoch.raw, prev_state.waiters - prev_state.signals);
                return;
            };
        }
    }
};

/// 可设置及清除的逻辑布尔标志,支持“等待直到被设置”操作。
pub const Event = enum(u32) {
    unset,
    waiting,
    is_set,

    /// 返回逻辑布尔值是否为 `true`。
    pub fn isSet(event: *const Event) bool {
        return switch (@atomicLoad(Event, event, .acquire)) {
            .unset, .waiting => false,
            .is_set => true,
        };
    }

    /// 阻塞直到逻辑布尔值为 `true`。
    pub fn wait(event: *Event, io: Io) Cancelable!void {
        if (@cmpxchgStrong(Event, event, .unset, .waiting, .acquire, .acquire)) |prev| switch (prev) {
            .unset => unreachable,
            .waiting => {},
            .is_set => return,
        };
        errdefer {
            // 理想情况下,应将事件恢复为 `.unset`,而非 `.waiting`,但可能还有其他线程在等待该事件。
            // 理论上可以在 `Event` 的未使用位中跟踪等待线程数量,但这又会导致新等待者加入时唤醒现有等待者。
            // 因此,最简单的方式是让状态保持 `.waiting`,最坏也只会多调用一次 `futexWake`。
            //
            //
        }
        while (true) {
            try io.futexWait(Event, event, .waiting);
            switch (@atomicLoad(Event, event, .acquire)) {
                .unset => unreachable, // 在待处理的 `wait` 返回之前调用了 `reset`
                .waiting => continue,
                .is_set => return,
            }
        }
    }

    /// 与 `wait` 相同,但不会引入取消点。
    ///
    /// 关于取消和取消点的说明,参见 `Future.cancel`。
    pub fn waitUncancelable(event: *Event, io: Io) void {
        if (@cmpxchgStrong(Event, event, .unset, .waiting, .acquire, .acquire)) |prev| switch (prev) {
            .unset => unreachable,
            .waiting => {},
            .is_set => return,
        };
        while (true) {
            io.futexWaitUncancelable(Event, event, .waiting);
            switch (@atomicLoad(Event, event, .acquire)) {
                .unset => unreachable, // 在待处理的 `wait` 返回之前调用了 `reset`
                .waiting => continue,
                .is_set => return,
            }
        }
    }

    pub const WaitTimeoutError = error{Timeout} || Cancelable;

    /// 阻塞调用线程,直到逻辑布尔值被设置或超时。
    pub fn waitTimeout(event: *Event, io: Io, timeout: Timeout) WaitTimeoutError!void {
        if (@cmpxchgStrong(Event, event, .unset, .waiting, .acquire, .acquire)) |prev| switch (prev) {
            .unset => unreachable,
            .waiting => {},
            .is_set => return,
        };
        errdefer {
            // 理想情况下,应将事件恢复为 `.unset`,而非 `.waiting`,但可能还有其他线程在等待该事件。
            // 理论上可以在 `Event` 的未使用位中跟踪等待线程数量,但这又会导致新等待者加入时唤醒现有等待者。
            // 因此,最简单的方式是让状态保持 `.waiting`,最坏也只会多调用一次 `futexWake`。
            //
            //
        }

        const deadline = timeout.toDeadline(io);

        while (true) {
            try io.futexWaitTimeout(Event, event, .waiting, timeout);
            switch (@atomicLoad(Event, event, .acquire)) {
                .unset => unreachable, // 在待处理的 `wait` 返回之前调用了 `reset`
                .waiting => {
                    const remaining = deadline.toDurationFromNow(io) orelse continue;
                    if (remaining.raw.nanoseconds <= 0) return error.Timeout;
                },
                .is_set => return,
            }
        }
    }

    /// 将逻辑布尔值设为 true,从而解除所有待处理的 `wait` 调用的阻塞。逻辑布尔值在调用 `reset` 之前始终保持 true,因此后续调用 `set` 没有语义上的影响。
    ///
    /// `set` 调用之前的所有内存访问都被“释放”,因此,若该 `set` 调用导致 `isSet` 返回 `true` 或等待结束,这些任务就能够观察到之前的内存访问。
    ///
    ///
    ///
    ///
    pub fn set(e: *Event, io: Io) void {
        switch (@atomicRmw(Event, e, .Xchg, .is_set, .release)) {
            .unset, .is_set => {},
            .waiting => io.futexWake(Event, e, math.maxInt(u32)),
        }
    }

    /// 将逻辑布尔值设为 false。
    ///
    /// 假定没有尚未完成的 `wait` 或 `waitUncancelable` 调用。
    ///
    /// 但允许并发调用 `isSet`、`set` 和 `reset`。
    pub fn reset(e: *Event) void {
        @atomicStore(Event, e, .unset, .monotonic);
    }
};

pub const QueueClosedError = error{Closed};

pub const TypeErasedQueue = struct {
    mutex: Mutex,
    closed: bool,

    /// 环形缓冲区。此数据在逻辑上位于已排队获取者*之后*。
    buffer: []u8,
    start: usize,
    len: usize,

    putters: std.DoublyLinkedList,
    getters: std.DoublyLinkedList,

    const Put = struct {
        remaining: []const u8,
        needed: usize,
        condition: Condition,
        node: std.DoublyLinkedList.Node,
    };

    const Get = struct {
        remaining: []u8,
        needed: usize,
        condition: Condition,
        node: std.DoublyLinkedList.Node,
    };

    pub fn init(buffer: []u8) TypeErasedQueue {
        return .{
            .mutex = .init,
            .closed = false,
            .buffer = buffer,
            .start = 0,
            .len = 0,
            .putters = .{},
            .getters = .{},
        };
    }

    /// 调用后,队列进入“已关闭”状态。已关闭的
    /// 队列在尝试放入元素时始终返回 `error.Closed`,即使
    /// 缓冲区中仍有空间。但在返回 `error.Closed`
    /// 之前,仍可取出队列中已有的元素。
    ///
    /// 幂等。线程安全。
    pub fn close(q: *TypeErasedQueue, io: Io) void {
        q.mutex.lockUncancelable(io);
        defer q.mutex.unlock(io);
        q.closed = true;
        {
            var it = q.getters.first;
            while (it) |node| : (it = node.next) {
                const getter: *Get = @alignCast(@fieldParentPtr("node", node));
                getter.condition.signal(io);
            }
        }
        {
            var it = q.putters.first;
            while (it) |node| : (it = node.next) {
                const putter: *Put = @alignCast(@fieldParentPtr("node", node));
                putter.condition.signal(io);
            }
        }
    }

    pub fn put(q: *TypeErasedQueue, io: Io, elements: []const u8, min: usize) (QueueClosedError || Cancelable)!usize {
        assert(elements.len >= min);
        if (elements.len == 0) return 0;
        try q.mutex.lock(io);
        defer q.mutex.unlock(io);
        return q.putLocked(io, elements, min, false);
    }

    /// 与 `put` 相同,但不引入取消点。
    ///
    /// 关于取消和取消点,参见 `Future.cancel`。
    pub fn putUncancelable(q: *TypeErasedQueue, io: Io, elements: []const u8, min: usize) QueueClosedError!usize {
        assert(elements.len >= min);
        if (elements.len == 0) return 0;
        q.mutex.lockUncancelable(io);
        defer q.mutex.unlock(io);
        return q.putLocked(io, elements, min, true) catch |err| switch (err) {
            error.Canceled => unreachable,
            error.Closed => |e| return e,
        };
    }

    fn puttableSlice(q: *const TypeErasedQueue) ?[]u8 {
        const unwrapped_index = q.start + q.len;
        const wrapped_index, const overflow = @subWithOverflow(unwrapped_index, q.buffer.len);
        const slice = switch (overflow) {
            1 => q.buffer[unwrapped_index..],
            0 => q.buffer[wrapped_index..q.start],
        };
        return if (slice.len > 0) slice else null;
    }

    fn putLocked(q: *TypeErasedQueue, io: Io, elements: []const u8, min: usize, uncancelable: bool) (QueueClosedError || Cancelable)!usize {
        // 已关闭的队列不能继续添加项目,即使缓冲区仍有空间。
        if (q.closed) return error.Closed;

        // 获取者具有访问数据的最高优先级,只有获取者
        // 队列为空时,才开始填充缓冲区。

        // 在可能阻塞前立即添加的元素数量。
        var n: usize = 0;

        while (q.getters.popFirst()) |getter_node| {
            const getter: *Get = @alignCast(@fieldParentPtr("node", getter_node));
            const copy_len = @min(getter.remaining.len, elements.len - n);
            assert(copy_len > 0);
            @memcpy(getter.remaining[0..copy_len], elements[n..][0..copy_len]);
            getter.remaining = getter.remaining[copy_len..];
            getter.needed -|= copy_len;
            n += copy_len;
            if (getter.needed == 0) {
                getter.condition.signal(io);
            } else {
                assert(n == elements.len); // 没有足够元素供获取者使用。
                q.getters.prepend(getter_node);
            }
            if (n == elements.len) return elements.len;
        }

        while (q.puttableSlice()) |slice| {
            const copy_len = @min(slice.len, elements.len - n);
            assert(copy_len > 0);
            @memcpy(slice[0..copy_len], elements[n..][0..copy_len]);
            q.len += copy_len;
            n += copy_len;
            if (n == elements.len) return elements.len;
        }

        // 达到最小值时不要阻塞。
        if (n >= min) return n;

        var pending: Put = .{
            .remaining = elements[n..],
            .needed = min - n,
            .condition = .init,
            .node = .{},
        };
        q.putters.append(&pending.node);
        defer if (pending.needed > 0) q.putters.remove(&pending.node);

        while (pending.needed > 0 and !q.closed) {
            if (uncancelable) {
                pending.condition.waitUncancelable(io, &q.mutex);
                continue;
            }
            pending.condition.wait(io, &q.mutex) catch |err| switch (err) {
                error.Canceled => if (pending.remaining.len == elements.len) {
                    // 等待期间被取消,未追加任何元素。
                    return error.Canceled;
                } else {
                    // 等待期间被取消,但已追加部分元素,因此先报告这些元素。
                    io.recancel();
                    return elements.len - pending.remaining.len;
                },
            };
        }
        if (pending.remaining.len == elements.len) {
            // 等待期间队列已关闭。未追加任何元素。
            assert(q.closed);
            return error.Closed;
        }
        return elements.len - pending.remaining.len;
    }

    pub fn get(q: *TypeErasedQueue, io: Io, buffer: []u8, min: usize) (QueueClosedError || Cancelable)!usize {
        assert(buffer.len >= min);
        if (buffer.len == 0) return 0;
        try q.mutex.lock(io);
        defer q.mutex.unlock(io);
        return q.getLocked(io, buffer, min, false);
    }

    /// 与 `get` 相同,但不会引入取消点。
    ///
    /// 关于取消和取消点的说明,参见 `Future.cancel`。
    pub fn getUncancelable(q: *TypeErasedQueue, io: Io, buffer: []u8, min: usize) QueueClosedError!usize {
        assert(buffer.len >= min);
        if (buffer.len == 0) return 0;
        q.mutex.lockUncancelable(io);
        defer q.mutex.unlock(io);
        return q.getLocked(io, buffer, min, true) catch |err| switch (err) {
            error.Canceled => unreachable,
            error.Closed => |e| return e,
        };
    }

    fn gettableSlice(q: *const TypeErasedQueue) ?[]const u8 {
        const overlong_slice = q.buffer[q.start..];
        const slice = overlong_slice[0..@min(overlong_slice.len, q.len)];
        return if (slice.len > 0) slice else null;
    }

    fn getLocked(q: *TypeErasedQueue, io: Io, buffer: []u8, min: usize, uncancelable: bool) (QueueClosedError || Cancelable)!usize {
        // 优先读取环形缓冲区,然后读取排队写入方的
        // 数据;最后将写入方的数据填入环形缓冲区,
        // 使这些写入方能够恢复执行。

        // 在可能阻塞之前,立即接收到的元素数量。
        var n: usize = 0;

        while (q.gettableSlice()) |slice| {
            const copy_len = @min(slice.len, buffer.len - n);
            assert(copy_len > 0);
            @memcpy(buffer[n..][0..copy_len], slice[0..copy_len]);
            q.start += copy_len;
            if (q.buffer.len - q.start == 0) q.start = 0;
            q.len -= copy_len;
            n += copy_len;
            if (n == buffer.len) {
                q.fillRingBufferFromPutters(io);
                return buffer.len;
            }
        }

        // 直接从放入者复制到缓冲区。
        while (q.putters.popFirst()) |putter_node| {
            const putter: *Put = @alignCast(@fieldParentPtr("node", putter_node));
            const copy_len = @min(putter.remaining.len, buffer.len - n);
            assert(copy_len > 0);
            @memcpy(buffer[n..][0..copy_len], putter.remaining[0..copy_len]);
            putter.remaining = putter.remaining[copy_len..];
            putter.needed -|= copy_len;
            n += copy_len;
            if (putter.needed == 0) {
                putter.condition.signal(io);
            } else {
                assert(n == buffer.len); // 没有足够空间容纳放入者
                q.putters.prepend(putter_node);
            }
            if (n == buffer.len) {
                q.fillRingBufferFromPutters(io);
                return buffer.len;
            }
        }

        // 从此处起无需再调用 `fillRingBufferFromPutters`,
        // 因为环形缓冲区*和*放入者队列均已清空!

        // 达到最小数量或队列已关闭时不阻塞。返回
        // 能够立即取得的元素数量;但若队列已关闭且为空,
        // 则报告 `error.Closed`。
        if (n == 0 and q.closed) return error.Closed;
        if (n >= min or q.closed) return n;

        var pending: Get = .{
            .remaining = buffer[n..],
            .needed = min - n,
            .condition = .init,
            .node = .{},
        };
        q.getters.append(&pending.node);
        defer if (pending.needed > 0) q.getters.remove(&pending.node);

        while (pending.needed > 0 and !q.closed) {
            if (uncancelable) {
                pending.condition.waitUncancelable(io, &q.mutex);
                continue;
            }
            pending.condition.wait(io, &q.mutex) catch |err| switch (err) {
                error.Canceled => if (pending.remaining.len == buffer.len) {
                    // 等待期间被取消,且未收到任何元素。
                    return error.Canceled;
                } else {
                    // 等待时被取消,但已收到一些元素,因此先报告这些元素。
                    io.recancel();
                    return buffer.len - pending.remaining.len;
                },
            };
        }
        if (pending.remaining.len == buffer.len) {
            // 等待期间队列已关闭。没有收到任何元素。
            assert(q.closed);
            return error.Closed;
        }
        return buffer.len - pending.remaining.len;
    }

    /// 环形缓冲区存在非零可用空间,且可能有等待中的写入方时调用。
    /// 此时已持有互斥锁;任务是将写入方数据复制到
    /// 环形缓冲区,并通知那些缓冲区数据
    /// 已全部复制完成的写入方。
    fn fillRingBufferFromPutters(q: *TypeErasedQueue, io: Io) void {
        while (q.putters.popFirst()) |putter_node| {
            const putter: *Put = @alignCast(@fieldParentPtr("node", putter_node));
            while (q.puttableSlice()) |slice| {
                const copy_len = @min(slice.len, putter.remaining.len);
                assert(copy_len > 0);
                @memcpy(slice[0..copy_len], putter.remaining[0..copy_len]);
                q.len += copy_len;
                putter.remaining = putter.remaining[copy_len..];
                putter.needed -|= copy_len;
                if (putter.needed == 0) {
                    putter.condition.signal(io);
                    break;
                }
            } else {
                q.putters.prepend(putter_node);
                break;
            }
        }
    }
};

/// 多生产者、多消费者、线程安全、缓冲区大小可在运行时配置。
/// 缓冲区为空时,消费者挂起,由生产者恢复。
/// 缓冲区满时,生产者挂起,由消费者恢复。
pub fn Queue(Elem: type) type {
    return struct {
        type_erased: TypeErasedQueue,

        pub fn init(buffer: []Elem) @This() {
            return .{ .type_erased = .init(@ptrCast(buffer)) };
        }

        /// 调用后,队列进入“已关闭”状态。已关闭的
        /// 队列在尝试放入元素时始终返回 `error.Closed`,即使
        /// 缓冲区中仍有空间。但在返回 `error.Closed`
        /// 之前,仍可取出队列中已有的元素。
        ///
        /// 线程安全。
        pub fn close(q: *@This(), io: Io) void {
            q.type_erased.close(io);
        }

        /// 将元素追加到队列末尾;容量不足时可能阻塞。
        /// 满足以下任一
        /// 条件即返回:
        ///
        /// * 至少已向队列加入 `min` 个元素;
        /// * 队列关闭;
        /// * 当前任务被取消。
        ///
        /// 返回已加入队列的 `elements` 元素数量,可以为零。
        /// 若返回错误,则没有加入任何元素。
        ///
        /// 如果队列关闭或任务取消之前
        /// 已加入部分元素,`put` 可能
        /// 返回小于 `min` 的数量;此时保证后续调用
        /// 返回 `error.Canceled` 或 `error.Closed`。
        ///
        /// 只有 `min` 为 0 时,返回值才可能为 0;此时
        /// 保证在*不*阻塞的情况下,
        /// 尽可能将 `elements` 加入队列。
        ///
        /// 断言 `elements.len >= min`。
        pub fn put(q: *@This(), io: Io, elements: []const Elem, min: usize) (QueueClosedError || Cancelable)!usize {
            return @divExact(try q.type_erased.put(io, @ptrCast(elements), min * @sizeOf(Elem)), @sizeOf(Elem));
        }

        /// 与 `put` 相同,但会阻塞,直到所有元素都已加入队列。
        ///
        /// 如果队列已关闭或操作取消,则返回 `error.Closed` 或 `error.Canceled`;
        /// 不保证取消或关闭之前,有多少个
        /// `elements` 已加入队列,也可能一个都没有。
        pub fn putAll(q: *@This(), io: Io, elements: []const Elem) (QueueClosedError || Cancelable)!void {
            const n = try q.put(io, elements, elements.len);
            if (n != elements.len) {
                _ = try q.put(io, elements[n..], elements.len - n);
                unreachable; // `put` 部分完成意味着队列已关闭,或操作已取消。
            }
        }

        /// 与 `put` 相同,但不引入取消点。
        ///
        /// 关于取消和取消点,参见 `Future.cancel`。
        pub fn putUncancelable(q: *@This(), io: Io, elements: []const Elem, min: usize) QueueClosedError!usize {
            return @divExact(try q.type_erased.putUncancelable(io, @ptrCast(elements), min * @sizeOf(Elem)), @sizeOf(Elem));
        }

        /// 将 `item` 追加到队尾;队列满时阻塞。
        pub fn putOne(q: *@This(), io: Io, item: Elem) (QueueClosedError || Cancelable)!void {
            assert(try q.put(io, &.{item}, 1) == 1);
        }

        /// 与 `putOne` 相同,但不会引入取消点。
        ///
        /// 关于取消和取消点的说明,参见 `Future.cancel`。
        pub fn putOneUncancelable(q: *@This(), io: Io, item: Elem) QueueClosedError!void {
            assert(try q.putUncancelable(io, &.{item}, 1) == 1);
        }

        /// 从队列头部接收元素,当前元素不足时可能阻塞。满足以下任一条件时返回:
        ///
        /// * 至少从队列接收到 `min` 个元素。
        /// * 队列已关闭,且没有缓冲的元素。
        /// * 当前任务被取消。
        ///
        /// 返回 `buffer` 中已填入的元素数量;若未填入任何元素则为零。
        /// 若返回错误,则没有填入任何元素。
        ///
        /// 若队列已关闭或任务已取消,但关闭或取消之前已接收到部分元素,则 `get` 可能返回小于 `min` 的数量;此时保证后续调用会返回 `error.Canceled` 或 `error.Closed`。
        ///
        /// 仅当 `min` 为 0 时才可能返回 0;此时保证在不阻塞的前提下,尽可能填充 `buffer`。
        ///
        /// 断言 `buffer.len >= min`。
        ///
        ///
        ///
        ///
        ///
        ///
        ///
        pub fn get(q: *@This(), io: Io, buffer: []Elem, min: usize) (QueueClosedError || Cancelable)!usize {
            return @divExact(try q.type_erased.get(io, @ptrCast(buffer), min * @sizeOf(Elem)), @sizeOf(Elem));
        }

        /// 与 `get` 相同,但不会引入取消点。
        ///
        /// 关于取消和取消点的说明,参见 `Future.cancel`。
        pub fn getUncancelable(q: *@This(), io: Io, buffer: []Elem, min: usize) QueueClosedError!usize {
            return @divExact(try q.type_erased.getUncancelable(io, @ptrCast(buffer), min * @sizeOf(Elem)), @sizeOf(Elem));
        }

        /// 从队首接收一个元素;如果队列为空,则阻塞。
        pub fn getOne(q: *@This(), io: Io) (QueueClosedError || Cancelable)!Elem {
            var buf: [1]Elem = undefined;
            assert(try q.get(io, &buf, 1) == 1);
            return buf[0];
        }

        /// 与 `getOne` 相同,但不引入取消点。
        ///
        /// 取消及取消点的说明见 `Future.cancel`。
        pub fn getOneUncancelable(q: *@This(), io: Io) QueueClosedError!Elem {
            var buf: [1]Elem = undefined;
            assert(try q.getUncancelable(io, &buf, 1) == 1);
            return buf[0];
        }

        /// 返回以 `Elem` 为单位的缓冲区长度。
        pub fn capacity(q: *const @This()) usize {
            return @divExact(q.type_erased.buffer.len, @sizeOf(Elem));
        }
    };
}

/// 调用 `function`,参数为 `args`,只有调用 `await` 后才保证能够取得函数返回值。
///
/// `function` 可能在 `async` 返回前立即调用。其保证比 `concurrent` 弱,因此更易移植和复用。
///
/// 此函数返回时,保证 `function` 要么已经调用并完成,要么已成功分配到一个并发执行单元。
///
/// 另见:
/// * `Group`
///
///
///
///
pub fn async(
    io: Io,
    function: anytype,
    args: std.meta.ArgsTuple(@TypeOf(function)),
) Future(@typeInfo(@TypeOf(function)).@"fn".return_type.?) {
    const Result = @typeInfo(@TypeOf(function)).@"fn".return_type.?;
    const Args = @TypeOf(args);
    const TypeErased = struct {
        fn start(context: *const anyopaque, result: *anyopaque) void {
            const args_casted: *const Args = @ptrCast(@alignCast(context));
            const result_casted: *Result = @ptrCast(@alignCast(result));
            result_casted.* = @call(.auto, function, args_casted.*);
        }
    };
    var future: Future(Result) = undefined;
    future.any_future = io.vtable.async(
        io.userdata,
        @ptrCast(&future.result),
        .of(Result),
        @ptrCast(&args),
        .of(Args),
        TypeErased.start,
    );
    return future;
}

pub const ConcurrentError = error{
    /// 可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。
    ///
    ConcurrencyUnavailable,
};

/// 使用 `args` 调用 `function`,函数的返回值
/// 只有在调用 `await` 后才保证可用,从而允许调用方
/// 在等待 `Io` 操作时继续执行。
///
/// 与 `async` 相比,此操作提供更强保证,因此限制
/// 可支持的 `Io` 实现类型。改为调用 `async`,则
/// 可允许有栈、单线程、阻塞式 I/O 等实现。
pub fn concurrent(
    io: Io,
    function: anytype,
    args: std.meta.ArgsTuple(@TypeOf(function)),
) ConcurrentError!Future(@typeInfo(@TypeOf(function)).@"fn".return_type.?) {
    const Result = @typeInfo(@TypeOf(function)).@"fn".return_type.?;
    const Args = @TypeOf(args);
    const TypeErased = struct {
        fn start(context: *const anyopaque, result: *anyopaque) void {
            const args_casted: *const Args = @ptrCast(@alignCast(context));
            const result_casted: *Result = @ptrCast(@alignCast(result));
            result_casted.* = @call(.auto, function, args_casted.*);
        }
    };
    var future: Future(Result) = undefined;
    future.any_future = try io.vtable.concurrent(
        io.userdata,
        @sizeOf(Result),
        .of(Result),
        @ptrCast(&args),
        .of(Args),
        TypeErased.start,
    );
    return future;
}

/// 等待 `clock` 上经过指定时间。
///
/// 另见:
/// * `Clock.Duration.sleep`
/// * `Clock.Timestamp.wait`
/// * `Timeout.sleep`
pub fn sleep(io: Io, duration: Duration, clock: Clock) Cancelable!void {
    return io.vtable.sleep(io.userdata, .{ .duration = .{
        .raw = duration,
        .clock = clock,
    } });
}

pub const LockedStderr = struct {
    file_writer: *File.Writer,
    terminal_mode: Terminal.Mode,

    pub fn terminal(ls: LockedStderr) Terminal {
        return .{
            .writer = &ls.file_writer.interface,
            .mode = ls.terminal_mode,
        };
    }

    pub fn clear(ls: LockedStderr, buffer: []u8) Cancelable!void {
        const fw = ls.file_writer;
        std.Progress.clearWrittenWithEscapeCodes(fw) catch |err| switch (err) {
            error.WriteFailed => switch (fw.err.?) {
                error.Canceled => |e| return e,
                else => {},
            },
        };
        fw.interface.flush() catch |err| switch (err) {
            error.WriteFailed => switch (fw.err.?) {
                error.Canceled => |e| return e,
                else => {},
            },
        };
        fw.interface.buffer = buffer;
    }
};

/// 用于在应用层向标准错误流写入。
/// 也会与不了解 Io 接口及其实现的
/// 调试层写入操作协调。
///
/// 另见:
/// * `tryLockStderr`
pub fn lockStderr(io: Io, buffer: []u8, terminal_mode: ?Terminal.Mode) Cancelable!LockedStderr {
    const ls = try io.vtable.lockStderr(io.userdata, terminal_mode);
    try ls.clear(buffer);
    return ls;
}

/// 与 `lockStderr` 相同,但不阻塞。
pub fn tryLockStderr(io: Io, buffer: []u8, terminal_mode: ?Terminal.Mode) Cancelable!?LockedStderr {
    const ls = (try io.vtable.tryLockStderr(io.userdata, terminal_mode)) orelse return null;
    try ls.clear(buffer);
    return ls;
}

pub fn unlockStderr(io: Io) void {
    return io.vtable.unlockStderr(io.userdata);
}

/// 从密码学安全的伪随机数生成器获取熵。
///
/// 实现可能在进程内存中存储随机数生成器状态,并用它填充 `buffer`。
///
/// 随机种子来自 `randomSecure`;若失败,则使用安全性较低的机制。
///
/// 线程安全。
///
/// 另见 `randomSecure`。
///
///
///
pub fn random(io: Io, buffer: []u8) void {
    return io.vtable.random(io.userdata, buffer);
}

pub const RandomSecureError = error{EntropyUnavailable} || Cancelable;

/// 从进程外部获取密码学安全的熵。
///
/// 始终发起系统调用,或通过其他方式避免依赖进程内存,
/// 以获取新鲜的随机性。不依赖已保存的随机数生成器状态。
///
/// 不提供任何后备机制;出现任何问题时均返回
/// `error.EntropyUnavailable`。
///
/// 线程安全。
///
/// 另见 `random`。
pub fn randomSecure(io: Io, buffer: []u8) RandomSecureError!void {
    return io.vtable.randomSecure(io.userdata, buffer);
}

test {
    _ = net;
    _ = File;
    _ = Dir;
    _ = Reader;
    _ = Writer;
    _ = Evented;
    _ = Threaded;
    _ = RwLock;
    _ = Semaphore;
    _ = @import("Io/test.zig");
}

/// 模拟不支持任何 `Io` 操作的系统的 `Io` 实现。
///
/// 该系统具有以下属性:
/// * 无法并发执行。
/// * 标准输入输出句柄是远端已关闭的管道。
/// * 文件系统完全为空,包括当前工作目录也已不存在。
/// * 文件系统已满,因此尝试创建条目始终返回 `error.NoSpaceLeft`。
/// * 不支持熵源,因此 `randomSecure` 始终返回 `error.EntropyUnavailable`,`random` 始终返回 0(以 0 填充缓冲区)。
/// * 不支持时钟,因此 `now` 和 `sleep` 始终返回 `error.UnsupportedClock`。
/// * 未连接网络,因此网络操作始终返回 `error.NetworkDown`。
pub const failing: std.Io = .{
    .userdata = null,
    .vtable = &.{
        .crashHandler = noCrashHandler,

        .async = noAsync,
        .concurrent = failingConcurrent,
        .await = unreachableAwait,
        .cancel = unreachableCancel,

        .groupAsync = noGroupAsync,
        .groupConcurrent = failingGroupConcurrent,
        .groupAwait = unreachableGroupAwait,
        .groupCancel = unreachableGroupCancel,

        .recancel = unreachableRecancel,
        .swapCancelProtection = unreachableSwapCancelProtection,
        .checkCancel = unreachableCheckCancel,

        .futexWait = noFutexWait,
        .futexWaitUncancelable = noFutexWaitUncancelable,
        .futexWake = noFutexWake,

        .operate = failingOperate,
        .batchAwaitAsync = unreachableBatchAwaitAsync,
        .batchAwaitConcurrent = unreachableBatchAwaitConcurrent,
        .batchCancel = unreachableBatchCancel,

        .dirCreateDir = failingDirCreateDir,
        .dirCreateDirPath = failingDirCreateDirPath,
        .dirCreateDirPathOpen = failingDirCreateDirPathOpen,
        .dirOpenDir = failingDirOpenDir,
        .dirStat = failingDirStat,
        .dirStatFile = failingDirStatFile,
        .dirAccess = failingDirAccess,
        .dirCreateFile = failingDirCreateFile,
        .dirCreateFileAtomic = failingDirCreateFileAtomic,
        .dirOpenFile = failingDirOpenFile,
        .dirClose = unreachableDirClose,
        .dirRead = noDirRead,
        .dirRealPath = failingDirRealPath,
        .dirRealPathFile = failingDirRealPathFile,
        .dirDeleteFile = failingDirDeleteFile,
        .dirDeleteDir = failingDirDeleteDir,
        .dirRename = failingDirRename,
        .dirRenamePreserve = failingDirRenamePreserve,
        .dirSymLink = failingDirSymLink,
        .dirReadLink = failingDirReadLink,
        .dirSetOwner = failingDirSetOwner,
        .dirSetFileOwner = failingDirSetFileOwner,
        .dirSetPermissions = failingDirSetPermissions,
        .dirSetFilePermissions = failingDirSetFilePermissions,
        .dirSetTimestamps = noDirSetTimestamps,
        .dirHardLink = failingDirHardLink,

        .fileStat = failingFileStat,
        .fileLength = failingFileLength,
        .fileClose = unreachableFileClose,
        .fileWritePositional = failingFileWritePositional,
        .fileWriteFileStreaming = noFileWriteFileStreaming,
        .fileWriteFilePositional = noFileWriteFilePositional,
        .fileReadPositional = failingFileReadPositional,
        .fileSeekBy = failingFileSeekBy,
        .fileSeekTo = failingFileSeekTo,
        .fileSync = failingFileSync,
        .fileIsTty = unreachableFileIsTty,
        .fileEnableAnsiEscapeCodes = unreachableFileEnableAnsiEscapeCodes,
        .fileSupportsAnsiEscapeCodes = unreachableFileSupportsAnsiEscapeCodes,
        .fileSetLength = failingFileSetLength,
        .fileSetOwner = failingFileSetOwner,
        .fileSetPermissions = failingFileSetPermissions,
        .fileSetTimestamps = noFileSetTimestamps,
        .fileLock = failingFileLock,
        .fileTryLock = failingFileTryLock,
        .fileUnlock = unreachableFileUnlock,
        .fileDowngradeLock = failingFileDowngradeLock,
        .fileRealPath = failingFileRealPath,
        .fileHardLink = failingFileHardLink,

        .fileMemoryMapCreate = failingFileMemoryMapCreate,
        .fileMemoryMapDestroy = unreachableFileMemoryMapDestroy,
        .fileMemoryMapSetLength = unreachableFileMemoryMapSetLength,
        .fileMemoryMapRead = unreachableFileMemoryMapRead,
        .fileMemoryMapWrite = unreachableFileMemoryMapWrite,

        .processExecutableOpen = failingProcessExecutableOpen,
        .processExecutablePath = failingProcessExecutablePath,
        .lockStderr = unreachableLockStderr,
        .tryLockStderr = noTryLockStderr,
        .unlockStderr = unreachableUnlockStderr,
        .processCurrentPath = failingProcessCurrentPath,
        .processSetCurrentDir = failingProcessSetCurrentDir,
        .processSetCurrentPath = failingProcessSetCurrentPath,
        .processReplace = failingProcessReplace,
        .processSpawn = failingProcessSpawn,
        .childWait = unreachableChildWait,
        .childKill = unreachableChildKill,

        .progressParentFile = failingProgressParentFile,
        .inheritParentDir = failingInheritParentDir,
        .inheritParentFile = failingInheritParentFile,

        .random = noRandom,
        .randomSecure = failingRandomSecure,

        .now = noNow,
        .clockResolution = failingClockResolution,
        .sleep = noSleep,

        .netListenIp = failingNetListenIp,
        .netAccept = failingNetAccept,
        .netBindIp = failingNetBindIp,
        .netConnectIp = failingNetConnectIp,
        .netListenUnix = failingNetListenUnix,
        .netConnectUnix = failingNetConnectUnix,
        .netSocketCreatePair = failingNetSocketCreatePair,
        .netWriteFile = failingNetWriteFile,
        .netClose = unreachableNetClose,
        .netShutdown = failingNetShutdown,
        .netInterfaceNameResolve = failingNetInterfaceNameResolve,
        .netInterfaceName = unreachableNetInterfaceName,
        .netLookup = failingNetLookup,
    },
};

pub fn noCrashHandler(userdata: ?*anyopaque) void {
    _ = userdata;
}

pub fn noAsync(userdata: ?*anyopaque, result: []u8, result_alignment: std.mem.Alignment, context: []const u8, context_alignment: std.mem.Alignment, start: *const fn (context: *const anyopaque, result: *anyopaque) void) ?*AnyFuture {
    _ = userdata;
    _ = result_alignment;
    _ = context_alignment;
    start(context.ptr, result.ptr);
    return null;
}

pub fn failingConcurrent(
    userdata: ?*anyopaque,
    result_len: usize,
    result_alignment: std.mem.Alignment,
    context: []const u8,
    context_alignment: std.mem.Alignment,
    start: *const fn (context: *const anyopaque, result: *anyopaque) void,
) ConcurrentError!*AnyFuture {
    _ = userdata;
    _ = result_len;
    _ = result_alignment;
    _ = context;
    _ = context_alignment;
    _ = start;
    return error.ConcurrencyUnavailable;
}

pub fn unreachableAwait(
    userdata: ?*anyopaque,
    any_future: *AnyFuture,
    result: []u8,
    result_alignment: std.mem.Alignment,
) void {
    _ = userdata;
    _ = any_future;
    _ = result;
    _ = result_alignment;
    unreachable;
}

pub fn unreachableCancel(
    userdata: ?*anyopaque,
    any_future: *AnyFuture,
    result: []u8,
    result_alignment: std.mem.Alignment,
) void {
    _ = userdata;
    _ = any_future;
    _ = result;
    _ = result_alignment;
    unreachable;
}

pub fn noGroupAsync(
    userdata: ?*anyopaque,
    group: *Group,
    context: []const u8,
    context_alignment: std.mem.Alignment,
    start: *const fn (context: *const anyopaque) void,
) void {
    _ = userdata;
    _ = group;
    _ = context_alignment;
    start(context.ptr);
}

pub fn failingGroupConcurrent(
    userdata: ?*anyopaque,
    group: *Group,
    context: []const u8,
    context_alignment: std.mem.Alignment,
    start: *const fn (context: *const anyopaque) void,
) ConcurrentError!void {
    _ = userdata;
    _ = group;
    _ = context;
    _ = context_alignment;
    _ = start;
    return error.ConcurrencyUnavailable;
}

pub fn unreachableGroupAwait(userdata: ?*anyopaque, group: *Group, token: *anyopaque) Cancelable!void {
    _ = userdata;
    _ = group;
    _ = token;
    unreachable;
}

pub fn unreachableGroupCancel(userdata: ?*anyopaque, group: *Group, token: *anyopaque) void {
    _ = userdata;
    _ = group;
    _ = token;
    unreachable;
}

pub fn unreachableRecancel(userdata: ?*anyopaque) void {
    _ = userdata;
    unreachable;
}

pub fn unreachableSwapCancelProtection(userdata: ?*anyopaque, new: CancelProtection) CancelProtection {
    _ = userdata;
    _ = new;
    unreachable;
}

pub fn unreachableCheckCancel(userdata: ?*anyopaque) Cancelable!void {
    _ = userdata;
    unreachable;
}

pub fn noFutexWait(userdata: ?*anyopaque, ptr: *const u32, expected: u32, timeout: Timeout) Cancelable!void {
    _ = userdata;
    std.debug.assert(ptr.* == expected or timeout != .none);
}

pub fn noFutexWaitUncancelable(userdata: ?*anyopaque, ptr: *const u32, expected: u32) void {
    _ = userdata;
    std.debug.assert(ptr.* == expected);
}

pub fn noFutexWake(userdata: ?*anyopaque, ptr: *const u32, max_waiters: u32) void {
    _ = userdata;
    _ = ptr;
    _ = max_waiters;
    // 空操作
}

pub fn failingOperate(userdata: ?*anyopaque, operation: Operation) Cancelable!Operation.Result {
    _ = userdata;
    return switch (operation) {
        .file_read_streaming => .{ .file_read_streaming = error.InputOutput },
        .file_write_streaming => .{ .file_write_streaming = error.InputOutput },
        .device_io_control => unreachable,
        .net_receive => .{ .net_receive = .{ error.NetworkDown, 0 } },
        .net_send => .{ .net_send = .{ error.NetworkDown, 0 } },
        .net_read => .{ .net_read = error.NetworkDown },
        .net_write => .{ .net_write = error.NetworkDown },
    };
}

pub fn unreachableBatchAwaitAsync(userdata: ?*anyopaque, b: *Batch) Cancelable!void {
    _ = userdata;
    _ = b;
    unreachable;
}

pub fn unreachableBatchAwaitConcurrent(userdata: ?*anyopaque, b: *Batch, timeout: Timeout) Batch.AwaitConcurrentError!void {
    _ = userdata;
    _ = b;
    _ = timeout;
    unreachable;
}

pub fn unreachableBatchCancel(userdata: ?*anyopaque, b: *Batch) void {
    _ = userdata;
    _ = b;
    unreachable;
}

pub fn failingDirCreateDir(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions) Dir.CreateDirError!void {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    _ = permissions;
    return error.NoSpaceLeft;
}

pub fn failingDirCreateDirPath(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions) Dir.CreateDirPathError!Dir.CreatePathStatus {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    _ = permissions;
    return error.NoSpaceLeft;
}

pub fn failingDirCreateDirPathOpen(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions, options: Dir.OpenOptions) Dir.CreateDirPathOpenError!Dir {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    _ = permissions;
    _ = options;
    return error.NoSpaceLeft;
}

pub fn failingDirOpenDir(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.OpenOptions) Dir.OpenError!Dir {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    _ = options;
    return error.FileNotFound;
}

pub fn failingDirStat(userdata: ?*anyopaque, dir: Dir) Dir.StatError!Dir.Stat {
    _ = userdata;
    _ = dir;
    return error.Streaming;
}

pub fn failingDirStatFile(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.StatFileOptions) Dir.StatFileError!File.Stat {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    _ = options;
    return error.FileNotFound;
}

pub fn failingDirAccess(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.AccessOptions) Dir.AccessError!void {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    _ = options;
    return error.FileNotFound;
}

pub fn failingDirCreateFile(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.CreateFileOptions) File.OpenError!File {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    _ = options;
    return error.NoSpaceLeft;
}

pub fn failingDirCreateFileAtomic(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.CreateFileAtomicOptions) Dir.CreateFileAtomicError!File.Atomic {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    _ = options;
    return error.NoSpaceLeft;
}

pub fn failingDirOpenFile(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, flags: Dir.OpenFileOptions) File.OpenError!File {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    _ = flags;
    return error.FileNotFound;
}

pub fn unreachableDirClose(userdata: ?*anyopaque, dirs: []const Dir) void {
    _ = userdata;
    _ = dirs;
    unreachable;
}

pub fn noDirRead(userdata: ?*anyopaque, dir_reader: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize {
    _ = userdata;
    _ = buffer;
    dir_reader.state = .finished;
    return 0;
}

pub fn failingDirRealPath(userdata: ?*anyopaque, dir: Dir, out_buffer: []u8) Dir.RealPathError!usize {
    _ = userdata;
    _ = dir;
    _ = out_buffer;
    return error.FileNotFound;
}

pub fn failingDirRealPathFile(userdata: ?*anyopaque, dir: Dir, path_name: []const u8, out_buffer: []u8) Dir.RealPathFileError!usize {
    _ = userdata;
    _ = dir;
    _ = path_name;
    _ = out_buffer;
    return error.FileNotFound;
}

pub fn failingDirDeleteFile(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteFileError!void {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    return error.FileNotFound;
}

pub fn failingDirDeleteDir(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteDirError!void {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    return error.FileNotFound;
}

pub fn failingDirRename(userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8) Dir.RenameError!void {
    _ = userdata;
    _ = old_dir;
    _ = old_sub_path;
    _ = new_dir;
    _ = new_sub_path;
    return error.FileNotFound;
}

pub fn failingDirRenamePreserve(userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8) Dir.RenamePreserveError!void {
    _ = userdata;
    _ = old_dir;
    _ = old_sub_path;
    _ = new_dir;
    _ = new_sub_path;
    return error.FileNotFound;
}

pub fn failingDirSymLink(userdata: ?*anyopaque, dir: Dir, target_path: []const u8, sym_link_path: []const u8, flags: Dir.SymLinkFlags) Dir.SymLinkError!void {
    _ = userdata;
    _ = dir;
    _ = target_path;
    _ = sym_link_path;
    _ = flags;
    return error.FileNotFound;
}

pub fn failingDirReadLink(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, buffer: []u8) Dir.ReadLinkError!usize {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    _ = buffer;
    return error.FileNotFound;
}

pub fn failingDirSetOwner(userdata: ?*anyopaque, dir: Dir, owner: ?File.Uid, group: ?File.Gid) Dir.SetOwnerError!void {
    _ = userdata;
    _ = dir;
    _ = owner;
    _ = group;
    return error.FileNotFound;
}

pub fn failingDirSetFileOwner(userdata: ?*anyopaque, dir: std.Io.Dir, sub_path: []const u8, owner: ?File.Uid, group: ?File.Gid, options: Dir.SetFileOwnerOptions) Dir.SetFileOwnerError!void {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    _ = owner;
    _ = group;
    _ = options;
    return error.FileNotFound;
}

pub fn failingDirSetPermissions(userdata: ?*anyopaque, dir: Dir, permissions: Dir.Permissions) Dir.SetPermissionsError!void {
    _ = userdata;
    _ = dir;
    _ = permissions;
    return error.FileNotFound;
}

pub fn failingDirSetFilePermissions(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: File.Permissions, options: Dir.SetFilePermissionsOptions) Dir.SetFilePermissionsError!void {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    _ = permissions;
    _ = options;
    return error.FileNotFound;
}

pub fn noDirSetTimestamps(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.SetTimestampsOptions) Dir.SetTimestampsError!void {
    _ = userdata;
    _ = dir;
    _ = sub_path;
    _ = options;
    // 空操作
}

pub fn failingDirHardLink(userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8, options: Dir.HardLinkOptions) Dir.HardLinkError!void {
    _ = userdata;
    _ = old_dir;
    _ = old_sub_path;
    _ = new_dir;
    _ = new_sub_path;
    _ = options;
    return error.FileNotFound;
}

pub fn failingFileStat(userdata: ?*anyopaque, file: File) File.StatError!File.Stat {
    _ = userdata;
    _ = file;
    return error.Streaming;
}

pub fn failingFileLength(userdata: ?*anyopaque, file: File) File.LengthError!u64 {
    _ = userdata;
    _ = file;
    return error.Streaming;
}

pub fn unreachableFileClose(userdata: ?*anyopaque, files: []const File) void {
    _ = userdata;
    _ = files;
    unreachable;
}

pub fn failingFileWritePositional(userdata: ?*anyopaque, file: File, header: []const u8, data: []const []const u8, splat: usize, offset: u64) File.WritePositionalError!usize {
    _ = userdata;
    _ = file;
    _ = offset;
    if (header.len != 0) return error.BrokenPipe;
    for (data[0 .. data.len - 1]) |item| {
        if (item.len > 0) return error.BrokenPipe;
    }
    if (data[data.len - 1].len != 0 and splat != 0) return error.BrokenPipe;
    return 0;
}

pub fn noFileWriteFileStreaming(userdata: ?*anyopaque, file: File, header: []const u8, file_reader: *Io.File.Reader, limit: Io.Limit) File.Writer.WriteFileError!usize {
    _ = userdata;
    _ = file;
    _ = header;
    _ = file_reader;
    _ = limit;
    return error.Unimplemented;
}

pub fn noFileWriteFilePositional(userdata: ?*anyopaque, file: File, header: []const u8, file_reader: *Io.File.Reader, limit: Io.Limit, offset: u64) File.WriteFilePositionalError!usize {
    _ = userdata;
    _ = file;
    _ = header;
    _ = file_reader;
    _ = limit;
    _ = offset;
    return error.Unimplemented;
}

pub fn failingFileReadPositional(userdata: ?*anyopaque, file: File, data: []const []u8, offset: u64) File.ReadPositionalError!usize {
    _ = userdata;
    _ = file;
    _ = offset;
    for (data) |item| {
        if (item.len > 0) return error.InputOutput;
    }
    return 0;
}

pub fn failingFileSeekBy(userdata: ?*anyopaque, file: File, relative_offset: i64) File.SeekError!void {
    _ = userdata;
    _ = file;
    _ = relative_offset;
    return error.Unseekable;
}

pub fn failingFileSeekTo(userdata: ?*anyopaque, file: File, absolute_offset: u64) File.SeekError!void {
    _ = userdata;
    _ = file;
    _ = absolute_offset;
    return error.Unseekable;
}

pub fn failingFileSync(userdata: ?*anyopaque, file: File) File.SyncError!void {
    _ = userdata;
    _ = file;
    return error.NoSpaceLeft;
}

pub fn unreachableFileIsTty(userdata: ?*anyopaque, file: File) Cancelable!bool {
    _ = userdata;
    _ = file;
    unreachable;
}

pub fn unreachableFileEnableAnsiEscapeCodes(userdata: ?*anyopaque, file: File) File.EnableAnsiEscapeCodesError!void {
    _ = userdata;
    _ = file;
    unreachable;
}

pub fn unreachableFileSupportsAnsiEscapeCodes(userdata: ?*anyopaque, file: File) Cancelable!bool {
    _ = userdata;
    _ = file;
    unreachable;
}

pub fn failingFileSetLength(userdata: ?*anyopaque, file: File, length: u64) File.SetLengthError!void {
    _ = userdata;
    _ = file;
    _ = length;
    return error.NonResizable;
}

pub fn failingFileSetOwner(userdata: ?*anyopaque, file: File, owner: ?File.Uid, group: ?File.Gid) File.SetOwnerError!void {
    _ = userdata;
    _ = file;
    _ = owner;
    _ = group;
    return error.FileNotFound;
}

pub fn failingFileSetPermissions(userdata: ?*anyopaque, file: File, permissions: File.Permissions) File.SetPermissionsError!void {
    _ = userdata;
    _ = file;
    _ = permissions;
    return error.FileNotFound;
}

pub fn noFileSetTimestamps(userdata: ?*anyopaque, file: File, options: File.SetTimestampsOptions) File.SetTimestampsError!void {
    _ = userdata;
    _ = file;
    _ = options;
    // 空操作
}

pub fn failingFileLock(userdata: ?*anyopaque, file: File, lock: File.Lock) File.LockError!void {
    _ = userdata;
    _ = file;
    _ = lock;
    return error.FileLocksUnsupported;
}

pub fn failingFileTryLock(userdata: ?*anyopaque, file: File, lock: File.Lock) File.LockError!bool {
    _ = userdata;
    _ = file;
    _ = lock;
    return error.FileLocksUnsupported;
}

pub fn unreachableFileUnlock(userdata: ?*anyopaque, file: File) void {
    _ = userdata;
    _ = file;
    unreachable;
}

pub fn failingFileDowngradeLock(userdata: ?*anyopaque, file: File) File.DowngradeLockError!void {
    _ = userdata;
    _ = file;
    // 空操作
}

pub fn failingFileRealPath(userdata: ?*anyopaque, file: File, out_buffer: []u8) File.RealPathError!usize {
    _ = userdata;
    _ = file;
    _ = out_buffer;
    return error.FileNotFound;
}

pub fn failingFileHardLink(userdata: ?*anyopaque, file: File, new_dir: Dir, new_sub_path: []const u8, options: File.HardLinkOptions) File.HardLinkError!void {
    _ = userdata;
    _ = file;
    _ = new_dir;
    _ = new_sub_path;
    _ = options;
    return error.FileNotFound;
}

pub fn failingFileMemoryMapCreate(userdata: ?*anyopaque, file: File, options: File.MemoryMap.CreateOptions) File.MemoryMap.CreateError!File.MemoryMap {
    _ = userdata;
    _ = file;
    _ = options;
    return error.AccessDenied;
}

pub fn unreachableFileMemoryMapDestroy(userdata: ?*anyopaque, mm: *File.MemoryMap) void {
    _ = userdata;
    _ = mm;
    unreachable;
}

pub fn unreachableFileMemoryMapSetLength(userdata: ?*anyopaque, mm: *File.MemoryMap, new_len: usize) File.MemoryMap.SetLengthError!void {
    _ = userdata;
    _ = mm;
    _ = new_len;
    unreachable;
}

pub fn unreachableFileMemoryMapRead(userdata: ?*anyopaque, mm: *File.MemoryMap) File.ReadPositionalError!void {
    _ = userdata;
    _ = mm;
    unreachable;
}

pub fn unreachableFileMemoryMapWrite(userdata: ?*anyopaque, mm: *File.MemoryMap) File.WritePositionalError!void {
    _ = userdata;
    _ = mm;
    unreachable;
}

pub fn failingProcessExecutableOpen(userdata: ?*anyopaque, flags: Dir.OpenFileOptions) std.process.OpenExecutableError!File {
    _ = userdata;
    _ = flags;
    return error.FileNotFound;
}

pub fn failingProcessExecutablePath(userdata: ?*anyopaque, buffer: []u8) std.process.ExecutablePathError!usize {
    _ = userdata;
    _ = buffer;
    return error.FileNotFound;
}

pub fn unreachableLockStderr(userdata: ?*anyopaque, terminal_mode: ?Terminal.Mode) Cancelable!LockedStderr {
    _ = userdata;
    _ = terminal_mode;
    unreachable;
}

pub fn noTryLockStderr(userdata: ?*anyopaque, terminal_mode: ?Terminal.Mode) Cancelable!?LockedStderr {
    _ = userdata;
    _ = terminal_mode;
    return null;
}

pub fn unreachableUnlockStderr(userdata: ?*anyopaque) void {
    _ = userdata;
    unreachable;
}

pub fn failingProcessCurrentPath(userdata: ?*anyopaque, buffer: []u8) std.process.CurrentPathError!usize {
    _ = userdata;
    _ = buffer;
    return error.CurrentDirUnlinked;
}

pub fn failingProcessSetCurrentDir(userdata: ?*anyopaque, dir: Dir) std.process.SetCurrentDirError!void {
    _ = userdata;
    _ = dir;
    return error.FileNotFound;
}

pub fn failingProcessSetCurrentPath(userdata: ?*anyopaque, path: []const u8) std.process.SetCurrentPathError!void {
    _ = userdata;
    _ = path;
    return error.FileNotFound;
}

pub fn failingProcessReplace(userdata: ?*anyopaque, options: std.process.ReplaceOptions) std.process.ReplaceError {
    _ = userdata;
    _ = options;
    return error.OperationUnsupported;
}

pub fn failingProcessSpawn(userdata: ?*anyopaque, options: std.process.SpawnOptions) std.process.SpawnError!std.process.Child {
    _ = userdata;
    _ = options;
    return error.OperationUnsupported;
}

pub fn unreachableChildWait(userdata: ?*anyopaque, child: *std.process.Child) std.process.Child.WaitError!std.process.Child.Term {
    _ = userdata;
    _ = child;
    unreachable;
}

pub fn unreachableChildKill(userdata: ?*anyopaque, child: *std.process.Child) void {
    _ = userdata;
    _ = child;
    unreachable;
}

pub fn failingProgressParentFile(userdata: ?*anyopaque) std.Progress.ParentFileError!File {
    _ = userdata;
    return error.UnsupportedOperation;
}

pub fn failingInheritParentDir(userdata: ?*anyopaque, handle: Dir.Handle) InheritParentHandleError!Dir {
    _ = userdata;
    _ = handle;
    return error.UnsupportedOperation;
}

pub fn failingInheritParentFile(userdata: ?*anyopaque, handle: File.Handle, flags: File.Flags) InheritParentHandleError!File {
    _ = userdata;
    _ = handle;
    _ = flags;
    return error.UnsupportedOperation;
}

pub fn noRandom(userdata: ?*anyopaque, buffer: []u8) void {
    _ = userdata;
    @memset(buffer, 0);
}

pub fn failingRandomSecure(userdata: ?*anyopaque, buffer: []u8) RandomSecureError!void {
    _ = userdata;
    _ = buffer;
    return error.EntropyUnavailable;
}

pub fn noNow(userdata: ?*anyopaque, clock: Clock) Timestamp {
    _ = userdata;
    _ = clock;
    return .zero;
}

pub fn failingClockResolution(userdata: ?*anyopaque, clock: Clock) Clock.ResolutionError!Duration {
    _ = userdata;
    _ = clock;
    return error.ClockUnavailable;
}

pub fn noSleep(userdata: ?*anyopaque, clock: Timeout) Cancelable!void {
    _ = userdata;
    _ = clock;
}

pub fn failingNetListenIp(userdata: ?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.ListenOptions) net.IpAddress.ListenError!net.Socket {
    _ = userdata;
    _ = address;
    _ = options;
    return error.NetworkDown;
}

pub fn failingNetAccept(userdata: ?*anyopaque, listen_fd: net.Socket.Handle, options: net.Server.AcceptOptions) net.Server.AcceptError!net.Socket {
    _ = userdata;
    _ = listen_fd;
    _ = options;
    return error.NetworkDown;
}

pub fn failingNetBindIp(userdata: ?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.BindOptions) net.IpAddress.BindError!net.Socket {
    _ = userdata;
    _ = address;
    _ = options;
    return error.NetworkDown;
}

pub fn failingNetConnectIp(userdata: ?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.ConnectOptions) net.IpAddress.ConnectError!net.Socket {
    _ = userdata;
    _ = address;
    _ = options;
    return error.NetworkDown;
}

pub fn failingNetListenUnix(userdata: ?*anyopaque, address: *const net.UnixAddress, options: net.UnixAddress.ListenOptions) net.UnixAddress.ListenError!net.Socket.Handle {
    _ = userdata;
    _ = address;
    _ = options;
    return error.NetworkDown;
}

pub fn failingNetConnectUnix(userdata: ?*anyopaque, address: *const net.UnixAddress) net.UnixAddress.ConnectError!net.Socket.Handle {
    _ = userdata;
    _ = address;
    return error.NetworkDown;
}

pub fn failingNetSocketCreatePair(userdata: ?*anyopaque, options: net.Socket.CreatePairOptions) net.Socket.CreatePairError![2]net.Socket {
    _ = userdata;
    _ = options;
    return error.OperationUnsupported;
}

pub fn failingNetWriteFile(userdata: ?*anyopaque, handle: net.Socket.Handle, header: []const u8, file_reader: *Io.File.Reader, limit: Io.Limit) net.Stream.Writer.WriteFileError!usize {
    _ = userdata;
    _ = handle;
    _ = header;
    _ = file_reader;
    _ = limit;
    return error.NetworkDown;
}

pub fn unreachableNetClose(userdata: ?*anyopaque, sockets: []const net.Socket) void {
    _ = userdata;
    _ = sockets;
    unreachable;
}

pub fn failingNetShutdown(userdata: ?*anyopaque, handle: net.Socket.Handle, how: net.ShutdownHow) net.ShutdownError!void {
    _ = userdata;
    _ = handle;
    _ = how;
    return error.NetworkDown;
}

pub fn failingNetInterfaceNameResolve(userdata: ?*anyopaque, name: *const net.Interface.Name) net.Interface.Name.ResolveError!net.Interface {
    _ = userdata;
    _ = name;
    return error.InterfaceNotFound;
}

pub fn unreachableNetInterfaceName(userdata: ?*anyopaque, interface: net.Interface) net.Interface.NameError!net.Interface.Name {
    _ = userdata;
    _ = interface;
    unreachable;
}

pub fn failingNetLookup(userdata: ?*anyopaque, host_name: net.HostName, resolved: *Queue(net.HostName.LookupResult), options: net.HostName.LookupOptions) net.HostName.LookupError!void {
    _ = userdata;
    _ = host_name;
    _ = resolved;
    _ = options;
    return error.NetworkDown;
}

test failing {
    const f: Io = .failing;
    // 文件相关内容
    try std.testing.expectError(error.NoSpaceLeft, Dir.createDir(.cwd(), f, "test", .default_dir));
    try std.testing.expectError(error.NoSpaceLeft, Dir.createFile(.cwd(), f, "test", .{}));
    try std.testing.expectError(error.FileNotFound, Dir.openDir(.cwd(), f, "test", .{}));
    try std.testing.expectError(error.FileNotFound, Dir.openFile(.cwd(), f, "test", .{}));
    try File.writeStreamingAll(.stdout(), f, &.{});
    try std.testing.expectError(error.AccessDenied, File.MemoryMap.create(f, .stdout(), .{ .len = 0 }));
    // 异步相关内容
    const closure = struct {
        var foo: usize = 0;
        fn doOp() void {
            foo = 4;
        }
    };
    var future = f.async(closure.doOp, .{});
    _ = future.await(f);
    try std.testing.expect(closure.foo == 4);
    // 其他内容
    var buffer: [1]u8 = undefined;
    f.random(&buffer);
    try std.testing.expect(buffer[0] == 0);
}