抽象所有 I/O 操作与并发的 跨平台接口,包括:
- 文件系统
- 网络
- 进程
- 时间与休眠
- 随机性
- 异步、等待、并发和取消
- 并发队列
- 等待组和选择
- 互斥锁、futex、事件和条件变量
- 内存映射文件 此接口使程序员在执行这些操作时, 能够编写高效且可复用的代码。
字段
userdata: ?*anyopaque
vtable: *const VTable
IobuiltinstdmathassertAllocatorAlignmentThreadedfiberEventedDispatchKqueueUringReaderWriternetDirFileTerminalRwLockSemaphoreVTableOperationoperateOperateTimeoutErroroperateTimeoutBatchLimitCancelableUnexpectedErrorInheritParentHandleErrorClockTimestampDurationTimeoutAnyFutureFutureGrouprecancelCancelProtectionswapCancelProtectioncheckCancelSelectfutexWaitfutexWaitTimeoutfutexWaitUncancelablefutexWakeMutexConditionEventQueueClosedErrorTypeErasedQueueQueueasyncConcurrentErrorconcurrentsleepLockedStderrlockStderrtryLockStderrunlockStderrrandomRandomSecureErrorrandomSecurefailingnoCrashHandlernoAsyncfailingConcurrentunreachableAwaitunreachableCancelnoGroupAsyncfailingGroupConcurrentunreachableGroupAwaitunreachableGroupCancelunreachableRecancelunreachableSwapCancelProtectionunreachableCheckCancelnoFutexWaitnoFutexWaitUncancelablenoFutexWakefailingOperateunreachableBatchAwaitAsyncunreachableBatchAwaitConcurrentunreachableBatchCancelfailingDirCreateDirfailingDirCreateDirPathfailingDirCreateDirPathOpenfailingDirOpenDirfailingDirStatfailingDirStatFilefailingDirAccessfailingDirCreateFilefailingDirCreateFileAtomicfailingDirOpenFileunreachableDirClosenoDirReadfailingDirRealPathfailingDirRealPathFilefailingDirDeleteFilefailingDirDeleteDirfailingDirRenamefailingDirRenamePreservefailingDirSymLinkfailingDirReadLinkfailingDirSetOwnerfailingDirSetFileOwnerfailingDirSetPermissionsfailingDirSetFilePermissionsnoDirSetTimestampsfailingDirHardLinkfailingFileStatfailingFileLengthunreachableFileClosefailingFileWritePositionalnoFileWriteFileStreamingnoFileWriteFilePositionalfailingFileReadPositionalfailingFileSeekByfailingFileSeekTofailingFileSyncunreachableFileIsTtyunreachableFileEnableAnsiEscapeCodesunreachableFileSupportsAnsiEscapeCodesfailingFileSetLengthfailingFileSetOwnerfailingFileSetPermissionsnoFileSetTimestampsfailingFileLockfailingFileTryLockunreachableFileUnlockfailingFileDowngradeLockfailingFileRealPathfailingFileHardLinkfailingFileMemoryMapCreateunreachableFileMemoryMapDestroyunreachableFileMemoryMapSetLengthunreachableFileMemoryMapReadunreachableFileMemoryMapWritefailingProcessExecutableOpenfailingProcessExecutablePathunreachableLockStderrnoTryLockStderrunreachableUnlockStderrfailingProcessCurrentPathfailingProcessSetCurrentDirfailingProcessSetCurrentPathfailingProcessReplacefailingProcessSpawnunreachableChildWaitunreachableChildKillfailingProgressParentFilefailingInheritParentDirfailingInheritParentFilenoRandomfailingRandomSecurenoNowfailingClockResolutionnoSleepfailingNetListenIpfailingNetAcceptfailingNetBindIpfailingNetConnectIpfailingNetListenUnixfailingNetConnectUnixfailingNetSocketCreatePairfailingNetWriteFileunreachableNetClosefailingNetShutdownfailingNetInterfaceNameResolveunreachableNetInterfaceNamefailingNetLookupfoodoOp
std.Io.Alignment
别名
别名目标 std.mem.Alignment
std.Io.Allocator
别名
别名目标 std.mem.Allocator
std.Io.AnyFuture
容器
std.Io.assert
别名
别名目标 std.debug.assert
std.Io.async
函数
调用 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.?)
参数
std.Io.async.start
函数
fn start(context: *const anyopaque, result: *anyopaque) void
参数
context: *const anyopaque
result: *anyopaque
std.Io.Batch
容器
字段
std.Io.Batch.add
函数
添加一个在下次 await 调用时执行的操作。
返回该操作完成后 next 将返回的索引。
断言同时活动的操作不超过 storage.len 个。
pub fn add(batch: *Batch, operation: Operation) u32
参数
std.Io.Batch.addAt
函数
添加一个在下次 await 调用时执行的操作。
操作完成后,next 将返回 index。
断言 index 处的操作未处于活动状态。
pub fn addAt(batch: *Batch, index: u32, operation: Operation) void
参数
std.Io.Batch.awaitAsync
函数
等待至少一个已提交操作完成。此函数返回后,可通过 next 迭代已完成操作。
此函数允许实现在批量操作之间引入并发,但与 awaitConcurrent 不同,并不要求一定并发,因此不会因 error.ConcurrencyUnavailable 失败。
pub fn awaitAsync(batch: *Batch, io: Io) Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Batch.awaitConcurrent
函数
等待已提交操作中至少一个完成。
函数返回后,可通过 next 迭代
已完成操作。
与 awaitAsync 不同,此函数要求实现
并发执行操作,因此可能失败并返回
error.ConcurrencyUnavailable。
pub fn awaitConcurrent(batch: *Batch, io: Io, timeout: Timeout) AwaitConcurrentError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- ConcurrencyUnavailable ConcurrentError
可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。
- Timeout Error
std.Io.Batch.AwaitConcurrentError
错误集合
错误
- Canceled Cancelable
调用方请求停止异步操作。
- ConcurrencyUnavailable ConcurrentError
可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。
- Timeout Error
std.Io.Batch.cancel
函数
请求中断所有未完成操作,然后等待所有
未完成操作结束。返回后,Batch 处于
定义明确的状态,可通过 next 迭代。成功
取消的操作不会出现在迭代中。某些操作
可能不受取消请求影响而成功完成,
它们会出现在迭代中。
pub fn cancel(batch: *Batch, io: Io) void
参数
std.Io.Batch.Completion
容器
字段
std.Io.Batch.init
函数
调用后,可以安全地无条件使用 defer 调用
cancel。storage 是预分配、内容未定义的内存缓冲区,
决定可通过 add 和 addAt 提交的
最大活动操作数。
pub fn init(storage: []Operation.Storage) Batch
参数
std.Io.Batch.next
函数
调用 awaitAsync、awaitConcurrent 或 cancel 后,
此函数会遍历已完成的操作。
每次此函数返回一个完成项时,都会将它从 Batch 出队。
再次等待之前无需取出所有完成项。
pub fn next(batch: *Batch) ?Completion
参数
batch: *Batch
std.Io.builtin
常量
std.Io.Cancelable
错误集合
错误
- Canceled
调用方请求停止异步操作。
std.Io.CancelProtection
容器
极少数情况下,需要完全阻止取消通知,使某段
代码可不受打断地运行,然后才可能观察到 error.Canceled。因此,每个
任务都有“取消保护”状态,表示 Io 函数是否可以引入
取消点。
修改任务取消保护状态,参见 swapCancelProtection。
关于取消及取消点的说明,参见 Future.cancel。
字段
std.Io.checkCancel
函数
此函数仅作为取消点,受取消保护约束,参见 CancelProtection,
除此之外不执行操作。也就是说,存在未被阻止的待处理取消请求时,返回 error.Canceled,
否则不执行任何操作。
通常无需调用此函数。主要用途是在耗时较长的 CPU 密集型
任务中,在任务完成前响应取消请求。较短的任务,或者
执行其他 Io 操作、因而包含其他取消点的任务,通常已经
能够迅速响应取消请求。
关于取消及取消点的说明,参见 Future.cancel。
pub fn checkCancel(io: Io) Cancelable!void
参数
io: Io
错误
- Canceled
调用方请求停止异步操作。
std.Io.Clock
容器
字段
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
容器
字段
std.Io.Clock.Duration.sleep
函数
等待 clock 上经过指定时长。
另见:
Io.sleepClock.Timestamp.waitTimeout.sleep
pub fn sleep(duration: Clock.Duration, io: Io) Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Clock.now
函数
此函数不会阻塞,因此不可取消。
分辨率由 resolution 确定;
若不支持此时钟,该值可能为 0。
另见:
Clock.Timestamp.now
pub fn now(clock: Clock, io: Io) Io.Timestamp
参数
std.Io.Clock.resolution
函数
提供 clock 的粒度。可能为零,表示时钟不受支持。
pub fn resolution(clock: Clock, io: Io) ResolutionError!Io.Duration
参数
错误
- ClockUnavailable
- Unexpected
std.Io.Clock.ResolutionError
错误集合
错误
- ClockUnavailable
- Unexpected
std.Io.Clock.Timestamp
容器
字段
std.Io.Clock.Timestamp.addDuration
函数
pub fn addDuration(from: Clock.Timestamp, duration: Clock.Duration) Clock.Timestamp
参数
std.Io.Clock.Timestamp.compare
函数
pub fn compare(lhs: Clock.Timestamp, op: math.CompareOperator, rhs: Clock.Timestamp) bool
参数
std.Io.Clock.Timestamp.durationFromNow
函数
分辨率由 resolution 决定;若时钟不受支持,其值可能为 0。
pub fn durationFromNow(timestamp: Clock.Timestamp, io: Io) Clock.Duration
参数
std.Io.Clock.Timestamp.durationTo
函数
pub fn durationTo(from: Clock.Timestamp, to: Clock.Timestamp) Clock.Duration
参数
std.Io.Clock.Timestamp.fromNow
函数
分辨率由 resolution 决定;若时钟不受支持,其值可能为 0。
pub fn fromNow(io: Io, duration: Clock.Duration) Clock.Timestamp
参数
std.Io.Clock.Timestamp.now
函数
此函数不会阻塞,因此不可取消。
分辨率由 resolution 决定;若时钟不受支持,
则可能为 0。
另见:
Clock.now
pub fn now(io: Io, clock: Clock) Clock.Timestamp
参数
std.Io.Clock.Timestamp.subDuration
函数
pub fn subDuration(from: Clock.Timestamp, duration: Clock.Duration) Clock.Timestamp
参数
std.Io.Clock.Timestamp.toClock
函数
分辨率由 resolution 决定;若时钟不受支持,其值可能为 0。
pub fn toClock(t: Clock.Timestamp, io: Io, clock: Clock) Clock.Timestamp
参数
std.Io.Clock.Timestamp.untilNow
函数
分辨率由 resolution 决定;若时钟不受支持,其值可能为 0。
pub fn untilNow(timestamp: Clock.Timestamp, io: Io) Clock.Duration
参数
std.Io.Clock.Timestamp.wait
函数
休眠至指定时间戳。
另请参见:
Io.sleepClock.Duration.sleepTimeout.sleep
pub fn wait(t: Clock.Timestamp, io: Io) Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.concurrent
函数
使用 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.?)
参数
错误
- ConcurrencyUnavailable
可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。
std.Io.concurrent.start
函数
fn start(context: *const anyopaque, result: *anyopaque) void
参数
context: *const anyopaque
result: *anyopaque
std.Io.ConcurrentError
错误集合
错误
- ConcurrencyUnavailable
可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。
std.Io.Condition
容器
字段
std.Io.Condition.broadcast
函数
pub fn broadcast(cond: *Condition, io: Io) void
参数
std.Io.Condition.deregister
函数
fn deregister(cond: *Condition, io: Io) void
参数
std.Io.Condition.init
常量
Condition
std.Io.Condition.signal
函数
pub fn signal(cond: *Condition, io: Io) void
参数
std.Io.Condition.State
容器
字段
waiters: u16
signals: u16
std.Io.Condition.wait
函数
阻塞,直到条件收到信号或操作被取消。
另请参见:
waitUncancelablewaitTimeout
pub fn wait(cond: *Condition, io: Io, mutex: *Mutex) Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Condition.waitTimeout
函数
阻塞直到条件被通知、被取消,或给定 超时到期。
另请参见:
waitwaitUncancelable
pub fn waitTimeout(cond: *Condition, io: Io, mutex: *Mutex, timeout: Timeout) WaitTimeoutError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- Timeout Error
std.Io.Condition.WaitTimeoutError
错误集合
错误
- Canceled Cancelable
调用方请求停止异步操作。
- Timeout Error
std.Io.Condition.waitUncancelable
函数
与 wait 相同,但不引入取消点。
关于取消点,参见 Future.cancel。
pub fn waitUncancelable(cond: *Condition, io: Io, mutex: *Mutex) void
参数
std.Io.Dir
别名
别名目标 std.Io.Dir
std.Io.Dispatch
别名
别名目标 std.Io.Dispatch
std.Io.doOp
函数
fn doOp() void
std.Io.Duration
容器
字段
nanoseconds: i96
std.Io.Duration.format
函数
按有符号数值的大小格式化纳秒数:
[#y][#w][#d][#h][#m]#[.###][n|u|m]s
pub fn format(duration: Duration, w: *Writer) Writer.Error!void
参数
错误
- 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
函数
fn formatUnsigned(w: *Writer, ns: u96) Writer.Error!void
参数
w: *Writer
ns: u96
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.Io.Duration.fromMicroseconds
函数
pub fn fromMicroseconds(x: i64) Duration
参数
x: i64
std.Io.Duration.fromMilliseconds
函数
pub fn fromMilliseconds(x: i64) Duration
参数
x: i64
std.Io.Duration.fromNanoseconds
函数
pub fn fromNanoseconds(x: i96) Duration
参数
x: i96
std.Io.Duration.fromSeconds
函数
pub fn fromSeconds(x: i64) Duration
参数
x: i64
std.Io.Duration.max
常量
Duration
std.Io.Duration.testFormat
函数
fn testFormat(expected: []const u8, input: i96) !void
参数
expected: []const u8
input: i96
std.Io.Duration.toMicroseconds
函数
pub fn toMicroseconds(d: Duration) i64
参数
d: Duration
std.Io.Duration.toMilliseconds
函数
pub fn toMilliseconds(d: Duration) i64
参数
d: Duration
std.Io.Duration.toNanoseconds
函数
pub fn toNanoseconds(d: Duration) i96
参数
d: Duration
std.Io.Duration.toSeconds
函数
pub fn toSeconds(d: Duration) i64
参数
d: Duration
std.Io.Duration.zero
常量
Duration
std.Io.Event
容器
可设置及清除的逻辑布尔标志,支持“等待直到被设置”操作。
字段
unset
waiting
is_set
std.Io.Event.isSet
函数
返回逻辑布尔值是否为 true。
pub fn isSet(event: *const Event) bool
参数
event: *const Event
std.Io.Event.reset
函数
将逻辑布尔值设为 false。
假定没有尚未完成的 wait 或 waitUncancelable 调用。
但允许并发调用 isSet、set 和 reset。
pub fn reset(e: *Event) void
参数
e: *Event
std.Io.Event.set
函数
将逻辑布尔值设为 true,从而解除所有待处理的 wait 调用的阻塞。逻辑布尔值在调用 reset 之前始终保持 true,因此后续调用 set 没有语义上的影响。
set 调用之前的所有内存访问都被“释放”,因此,若该 set 调用导致 isSet 返回 true 或等待结束,这些任务就能够观察到之前的内存访问。
pub fn set(e: *Event, io: Io) void
参数
std.Io.Event.wait
函数
阻塞直到逻辑布尔值为 true。
pub fn wait(event: *Event, io: Io) Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Event.waitTimeout
函数
阻塞调用线程,直到逻辑布尔值被设置、超时到期,或
发生伪唤醒。若超时到期或发生伪唤醒,则返回 error.Timeout。
pub fn waitTimeout(event: *Event, io: Io, timeout: Timeout) WaitTimeoutError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- Timeout
std.Io.Event.WaitTimeoutError
错误集合
错误
- Canceled Cancelable
调用方请求停止异步操作。
- Timeout
std.Io.Event.waitUncancelable
函数
与 wait 相同,但不会引入取消点。
关于取消和取消点的说明,参见 Future.cancel。
pub fn waitUncancelable(event: *Event, io: Io) void
参数
std.Io.Evented
类型
std.Io.failing
常量
该系统具有以下属性:
- 无法并发执行。
- 标准输入输出句柄是远端已关闭的管道。
- 文件系统完全为空,包括当前工作目录也已不存在。
- 文件系统已满,因此尝试创建条目始终返回
error.NoSpaceLeft。 - 不支持熵源,因此
randomSecure始终返回error.EntropyUnavailable,random始终返回 0(以 0 填充缓冲区)。 - 不支持时钟,因此
now和sleep始终返回error.UnsupportedClock。 - 未连接网络,因此网络操作始终返回
error.NetworkDown。
std.Io
std.Io.failingClockResolution
函数
pub fn failingClockResolution(userdata: ?*anyopaque, clock: Clock) Clock.ResolutionError!Duration
参数
userdata: ?*anyopaque
clock: Clock
错误
- ClockUnavailable
- Unexpected
std.Io.failingConcurrent
函数
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
函数
pub fn failingDirAccess(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.AccessOptions) Dir.AccessError!void
参数
错误
- 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
函数
pub fn failingDirCreateDir(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions) Dir.CreateDirError!void
参数
错误
- 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
函数
pub fn failingDirCreateDirPath(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, permissions: Dir.Permissions) Dir.CreateDirPathError!Dir.CreatePathStatus
参数
错误
- 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
函数
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
函数
pub fn failingDirCreateFile(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.CreateFileOptions) File.OpenError!File
参数
错误
- 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
函数
pub fn failingDirCreateFileAtomic(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.CreateFileAtomicOptions) Dir.CreateFileAtomicError!File.Atomic
参数
错误
- 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
函数
pub fn failingDirDeleteDir(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteDirError!void
参数
错误
- 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
函数
pub fn failingDirDeleteFile(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8) Dir.DeleteFileError!void
参数
错误
- 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
函数
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
函数
pub fn failingDirOpenDir(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.OpenOptions) Dir.OpenError!Dir
参数
错误
- 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
函数
pub fn failingDirOpenFile(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, flags: Dir.OpenFileOptions) File.OpenError!File
参数
错误
- 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
函数
pub fn failingDirReadLink(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, buffer: []u8) Dir.ReadLinkError!usize
参数
错误
- 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
函数
pub fn failingDirRealPath(userdata: ?*anyopaque, dir: Dir, out_buffer: []u8) Dir.RealPathError!usize
参数
错误
- 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
函数
pub fn failingDirRealPathFile(userdata: ?*anyopaque, dir: Dir, path_name: []const u8, out_buffer: []u8) Dir.RealPathFileError!usize
参数
错误
- 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
函数
pub fn failingDirRename(userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8) Dir.RenameError!void
参数
错误
- 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
函数
pub fn failingDirRenamePreserve(userdata: ?*anyopaque, old_dir: Dir, old_sub_path: []const u8, new_dir: Dir, new_sub_path: []const u8) Dir.RenamePreserveError!void
参数
错误
- 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
函数
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
函数
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
函数
pub fn failingDirSetOwner(userdata: ?*anyopaque, dir: Dir, owner: ?File.Uid, group: ?File.Gid) Dir.SetOwnerError!void
参数
错误
- AccessDenied SetOwnerError
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetOwnerError
- InputOutput SetOwnerError
- PermissionDenied SetOwnerError
- ReadOnlyFileSystem SetOwnerError
- SymLinkLoop SetOwnerError
- SystemResources SetOwnerError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.failingDirSetPermissions
函数
pub fn failingDirSetPermissions(userdata: ?*anyopaque, dir: Dir, permissions: Dir.Permissions) Dir.SetPermissionsError!void
参数
错误
- AccessDenied SetPermissionsError
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound SetPermissionsError
- InputOutput SetPermissionsError
- PermissionDenied SetPermissionsError
- ReadOnlyFileSystem SetPermissionsError
- SymLinkLoop SetPermissionsError
- SystemResources SetPermissionsError
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.failingDirStat
函数
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
函数
pub fn failingDirStatFile(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.StatFileOptions) Dir.StatFileError!File.Stat
参数
错误
- 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
函数
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
函数
pub fn failingFileDowngradeLock(userdata: ?*anyopaque, file: File) File.DowngradeLockError!void
参数
userdata: ?*anyopaque
file: File
错误
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.failingFileHardLink
函数
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
函数
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
函数
pub fn failingFileLock(userdata: ?*anyopaque, file: File, lock: File.Lock) File.LockError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- FileLocksUnsupported
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.failingFileMemoryMapCreate
函数
pub fn failingFileMemoryMapCreate(userdata: ?*anyopaque, file: File, options: File.MemoryMap.CreateOptions) File.MemoryMap.CreateError!File.MemoryMap
参数
错误
- 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
函数
pub fn failingFileReadPositional(userdata: ?*anyopaque, file: File, data: []const []u8, offset: u64) File.ReadPositionalError!usize
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- InputOutput
- IsDir
尝试将目录文件描述符当作普通文件读取。
- LockViolation
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading
打开文件时未授予读取能力。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
此文件不支持按位置读取。
- WouldBlock
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.failingFileRealPath
函数
pub fn failingFileRealPath(userdata: ?*anyopaque, file: File, out_buffer: []u8) File.RealPathError!usize
参数
错误
- 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
函数
pub fn failingFileSeekBy(userdata: ?*anyopaque, file: File, relative_offset: i64) File.SeekError!void
参数
错误
- AccessDenied
文件描述符不具备执行定位所需的权限。
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
std.Io.failingFileSeekTo
函数
pub fn failingFileSeekTo(userdata: ?*anyopaque, file: File, absolute_offset: u64) File.SeekError!void
参数
错误
- AccessDenied
文件描述符不具备执行定位所需的权限。
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
std.Io.failingFileSetLength
函数
pub fn failingFileSetLength(userdata: ?*anyopaque, file: File, length: u64) File.SetLengthError!void
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy
- FileTooBig
- InputOutput
- NonResizable
- PermissionDenied
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.failingFileSetOwner
函数
pub fn failingFileSetOwner(userdata: ?*anyopaque, file: File, owner: ?File.Uid, group: ?File.Gid) File.SetOwnerError!void
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- InputOutput
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.failingFileSetPermissions
函数
pub fn failingFileSetPermissions(userdata: ?*anyopaque, file: File, permissions: File.Permissions) File.SetPermissionsError!void
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- InputOutput
- PermissionDenied
- ReadOnlyFileSystem
- SymLinkLoop
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.failingFileStat
函数
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
函数
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
函数
pub fn failingFileTryLock(userdata: ?*anyopaque, file: File, lock: File.Lock) File.LockError!bool
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- FileLocksUnsupported
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.failingFileWritePositional
函数
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
函数
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
函数
pub fn failingInheritParentDir(userdata: ?*anyopaque, handle: Dir.Handle) InheritParentHandleError!Dir
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedOperation
std.Io.failingInheritParentFile
函数
pub fn failingInheritParentFile(userdata: ?*anyopaque, handle: File.Handle, flags: File.Flags) InheritParentHandleError!File
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedOperation
std.Io.failingNetAccept
函数
pub fn failingNetAccept(userdata: ?*anyopaque, listen_fd: net.Socket.Handle, options: net.Server.AcceptOptions) net.Server.AcceptError!net.Socket
参数
错误
- BlockedByFirewall
防火墙规则禁止连接。
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionAborted
曾有传入连接,但在接受调用之前, 远端对等方已将其终止。
- NetworkDown
网络子系统已失败。
- ProcessFdQuotaExceeded
已达到每个进程可打开的文件描述符数量限制。
- ProtocolFailure
- SocketNotListening
从未调用
listen,或已调用shutdown,后者可能发生于 本调用阻塞期间。因此,可将shutdown用作 并发取消机制。- SystemFdQuotaExceeded
已达到系统范围内打开文件总数的上限。
- SystemResources
可用内存不足。这通常意味着内存分配受限于 套接字缓冲区上限,而非系统内存。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
没有已排队且可立即接受的连接, 而套接字配置为非阻塞模式。
std.Io.failingNetBindIp
函数
pub fn failingNetBindIp(userdata: ?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.BindOptions) net.IpAddress.BindError!net.Socket
参数
错误
- AccessDenied
该地址受到保护,当前用户没有绑定它的权限。
- AddressFamilyUnsupported
该地址对于套接字的地址族无效。
- AddressInUse
地址已被占用。当绑定端口为 0, 但所有临时端口均已使用时,可能发生此情况。
- AddressUnavailable
请求了不存在的接口,或请求的地址不是本地地址。
- Canceled Cancelable
调用方请求停止异步操作。
- NetworkDown
用于到达目标的本地网络接口已离线。
- OptionUnsupported
Io 实现不支持某个
BindOptions。- ProcessFdQuotaExceeded
已达到每进程可打开文件描述符数量上限。
- ProtocolUnsupportedByAddressFamily
- ProtocolUnsupportedBySystem
- SocketModeUnsupported
- SystemFdQuotaExceeded
已达到系统范围内已打开文件的总数上限。
- SystemResources
操作系统内部内存或其他资源不足。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.failingNetConnectIp
函数
pub fn failingNetConnectIp(userdata: ?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.ConnectOptions) net.IpAddress.ConnectError!net.Socket
参数
错误
- 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
函数
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
函数
pub fn failingNetInterfaceNameResolve(userdata: ?*anyopaque, name: *const net.Interface.Name) net.Interface.Name.ResolveError!net.Interface
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- InterfaceNotFound
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.failingNetListenIp
函数
pub fn failingNetListenIp(userdata: ?*anyopaque, address: *const net.IpAddress, options: net.IpAddress.ListenOptions) net.IpAddress.ListenError!net.Socket
参数
错误
- 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
函数
pub fn failingNetListenUnix(userdata: ?*anyopaque, address: *const net.UnixAddress, options: net.UnixAddress.ListenOptions) net.UnixAddress.ListenError!net.Socket.Handle
参数
错误
- AccessDenied
- AddressFamilyUnsupported
- AddressInUse
- AddressUnavailable
- Canceled Cancelable
调用方请求停止异步操作。
- FileNotFound
- NetworkDown
- NotDir
- PermissionDenied
- ProcessFdQuotaExceeded
- ReadOnlyFileSystem
- SymLinkLoop
- SystemFdQuotaExceeded
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.failingNetLookup
函数
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
函数
pub fn failingNetShutdown(userdata: ?*anyopaque, handle: net.Socket.Handle, how: net.ShutdownHow) net.ShutdownError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- ConnectionAborted
- ConnectionResetByPeer
- NetworkDown
- SocketUnconnected
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.failingNetSocketCreatePair
函数
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
函数
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
函数
pub fn failingOperate(userdata: ?*anyopaque, operation: Operation) Cancelable!Operation.Result
参数
userdata: ?*anyopaque
operation: Operation
错误
- Canceled
调用方请求停止异步操作。
std.Io.failingProcessCurrentPath
函数
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
函数
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
函数
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
函数
pub fn failingProcessReplace(userdata: ?*anyopaque, options: std.process.ReplaceOptions) std.process.ReplaceError
参数
userdata: ?*anyopaque
options: std.process.ReplaceOptions
std.Io.failingProcessSetCurrentDir
函数
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
函数
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
函数
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
函数
pub fn failingProgressParentFile(userdata: ?*anyopaque) std.Progress.ParentFileError!File
参数
userdata: ?*anyopaque
错误
- EnvironmentVariableMissing
- UnrecognizedFormat
- UnsupportedOperation
std.Io.failingRandomSecure
函数
pub fn failingRandomSecure(userdata: ?*anyopaque, buffer: []u8) RandomSecureError!void
参数
userdata: ?*anyopaque
buffer: []u8
错误
- Canceled Cancelable
调用方请求停止异步操作。
- EntropyUnavailable
std.Io.fiber
别名
别名目标 std.Io.fiber
std.Io.File
别名
别名目标 std.Io.File
std.Io.foo
变量
usize
std.Io.futexWait
函数
原子检查 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
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.futexWaitTimeout
函数
pub fn futexWaitTimeout(io: Io, comptime T: type, ptr: *align(@alignOf(u32)) const T, expected: T, timeout: Timeout) Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.futexWaitUncancelable
函数
与 futexWait 相同,但不引入取消点。
取消及取消点的说明见 Future.cancel。
pub fn futexWaitUncancelable(io: Io, comptime T: type, ptr: *align(@alignOf(u32)) const T, expected: T) void
参数
std.Io.futexWake
函数
解除对 ptr 的待处理 futex 等待,最多解除 max_waiters 个调用。
pub fn futexWake(io: Io, comptime T: type, ptr: *align(@alignOf(u32)) const T, max_waiters: u32) void
参数
std.Io.Future
类型函数
pub fn Future(Result: type) type
参数
Result: type
字段
any_future: ?*AnyFuture
result: Result
std.Io.Future.await
函数
幂等。非线程安全。
pub fn await(f: *@This(), io: Io) Result
参数
f: *@This()
io: Io
std.Io.Future.cancel
函数
等同于 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
容器
无序任务集合,只能整体等待或取消。
通过 Group.async 和 Group.concurrent 在组中生成任务。
保证每个任务关联的资源会在
该任务返回时释放,而不必等整个组完成或
被等待。因此,对于长时间存在且不断加入
并发任务的组,这不属于资源泄漏。但异步
任务只有在调用 Group.await 或 Group.cancel 后才保证
运行,因此不断加入异步任务却从不等待该组,可能
泄漏资源。
字段
std.Io.Group.async
函数
等同于 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
参数
std.Io.Group.async.start
函数
fn start(context: *const anyopaque) void
参数
context: *const anyopaque
std.Io.Group.await
函数
阻塞至组内所有任务结束。此期间,
取消请求会传播至组内所有成员,
并使组最终完成时
返回 error.Canceled。
此函数返回后,保证 Group 中所有通过
async 或 concurrent 创建的任务均已运行。
幂等。不保证线程安全。
可以安全地与 Group.async 或
Group.concurrent 并发调用,但必须确保该组直到
Group.async 或 Group.concurrent 调用返回后才完成。
pub fn await(g: *Group, io: Io) Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Group.cancel
函数
等同于 await,但立即请求取消组内
全部成员。
此函数返回后,保证 Group 中所有通过
async 或 concurrent 创建的任务均已运行。
取消及取消点的说明参见 Future.cancel。
幂等。不保证线程安全。
可以安全地与 Group.async 或
Group.concurrent 并发调用,但必须确保该组直到
Group.async 或 Group.concurrent 调用返回后才完成。
pub fn cancel(g: *Group, io: Io) void
参数
std.Io.Group.concurrent
函数
等同于 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
参数
错误
- ConcurrencyUnavailable
可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。
std.Io.Group.concurrent.start
函数
fn start(context: *const anyopaque) void
参数
context: *const anyopaque
std.Io.Group.init
常量
Group
std.Io.InheritParentHandleError
错误集合
错误
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- UnsupportedOperation
std.Io.Io
别名
别名目标 std.Io
std.Io.Kqueue
别名
别名目标 std.Io.Kqueue
std.Io.Limit
容器
字段
std.Io.Limit.countVec
函数
pub fn countVec(data: []const []const u8) Limit
参数
data: []const []const u8
std.Io.Limit.limited
函数
math.maxInt(usize) 被解释为 .unlimited。
pub fn limited(n: usize) Limit
参数
n: usize
std.Io.Limit.limited64
函数
大于 math.maxInt(usize) 的任何值均被解释为 .unlimited。
pub fn limited64(n: u64) Limit
参数
n: u64
std.Io.Limit.max
函数
pub fn max(a: Limit, b: Limit) Limit
参数
std.Io.Limit.min
函数
pub fn min(a: Limit, b: Limit) Limit
参数
std.Io.Limit.minInt
函数
pub fn minInt(l: Limit, n: usize) usize
参数
l: Limit
n: usize
std.Io.Limit.minInt64
函数
pub fn minInt64(l: Limit, n: u64) usize
参数
l: Limit
n: u64
std.Io.Limit.nonzero
函数
pub fn nonzero(l: Limit) bool
参数
l: Limit
std.Io.Limit.slice
函数
pub fn slice(l: Limit, s: []u8) []u8
参数
l: Limit
s: []u8
std.Io.Limit.slice1
函数
根据限制缩短切片,但在限制之外额外保留 一个字节的空间,以便区分 到达流末尾与达到限制这两种情况。
pub fn slice1(l: Limit, non_empty_buffer: []u8) []u8
参数
l: Limit
non_empty_buffer: []u8
std.Io.Limit.sliceConst
函数
pub fn sliceConst(l: Limit, s: []const u8) []const u8
参数
l: Limit
s: []const u8
std.Io.Limit.subtract
函数
返回减去 amount 后的新限制,
或返回 null 表示将超出限制。
pub fn subtract(l: Limit, amount: usize) ?Limit
参数
l: Limit
amount: usize
std.Io.Limit.toInt
函数
pub fn toInt(l: Limit) ?usize
参数
l: Limit
std.Io.Limit.toInt64
函数
pub fn toInt64(l: Limit) ?u64
参数
l: Limit
std.Io.LockedStderr
容器
字段
std.Io.LockedStderr.clear
函数
pub fn clear(ls: LockedStderr, buffer: []u8) Cancelable!void
参数
ls: LockedStderr
buffer: []u8
错误
- Canceled
调用方请求停止异步操作。
std.Io.LockedStderr.terminal
函数
pub fn terminal(ls: LockedStderr) Terminal
参数
ls: LockedStderr
std.Io.lockStderr
函数
pub fn lockStderr(io: Io, buffer: []u8, terminal_mode: ?Terminal.Mode) Cancelable!LockedStderr
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.math
别名
别名目标 std.math
std.Io.Mutex
容器
Mutex 是一种同步原语,确保对称为“临界区”的 共享代码区域进行原子访问。
Mutex 是 extern 结构体,因此可用作另一个 extern 结构体的字段。
字段
std.Io.Mutex.init
常量
Mutex
std.Io.Mutex.lock
函数
pub fn lock(m: *Mutex, io: Io) Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Mutex.lockUncancelable
函数
与 lock 相同,但不引入取消点。
取消及取消点的说明见 Future.cancel。
pub fn lockUncancelable(m: *Mutex, io: Io) void
参数
std.Io.Mutex.State
容器
字段
unlocked
locked_once
contended
std.Io.Mutex.tryLock
函数
pub fn tryLock(m: *Mutex) bool
参数
m: *Mutex
std.Io.Mutex.unlock
函数
pub fn unlock(m: *Mutex, io: Io) void
参数
std.Io.net
别名
别名目标 std.Io.net
std.Io.noAsync
函数
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
参数
std.Io.noCrashHandler
函数
pub fn noCrashHandler(userdata: ?*anyopaque) void
参数
userdata: ?*anyopaque
std.Io.noDirRead
函数
pub fn noDirRead(userdata: ?*anyopaque, dir_reader: *Dir.Reader, buffer: []Dir.Entry) Dir.Reader.Error!usize
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- PermissionDenied
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.noDirSetTimestamps
函数
pub fn noDirSetTimestamps(userdata: ?*anyopaque, dir: Dir, sub_path: []const u8, options: Dir.SetTimestampsOptions) Dir.SetTimestampsError!void
参数
错误
- 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
函数
pub fn noFileSetTimestamps(userdata: ?*anyopaque, file: File, options: File.SetTimestampsOptions) File.SetTimestampsError!void
参数
错误
- 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
函数
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
函数
pub fn noFileWriteFileStreaming(userdata: ?*anyopaque, file: File, header: []const u8, file_reader: *Io.File.Reader, limit: Io.Limit) File.Writer.WriteFileError!usize
参数
错误
- 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
函数
pub fn noFutexWait(userdata: ?*anyopaque, ptr: *const u32, expected: u32, timeout: Timeout) Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.noFutexWaitUncancelable
函数
pub fn noFutexWaitUncancelable(userdata: ?*anyopaque, ptr: *const u32, expected: u32) void
参数
userdata: ?*anyopaque
ptr: *const u32
expected: u32
std.Io.noFutexWake
函数
pub fn noFutexWake(userdata: ?*anyopaque, ptr: *const u32, max_waiters: u32) void
参数
userdata: ?*anyopaque
ptr: *const u32
max_waiters: u32
std.Io.noGroupAsync
函数
pub fn noGroupAsync( userdata: ?*anyopaque, group: *Group, context: []const u8, context_alignment: std.mem.Alignment, start: *const fn (context: *const anyopaque) void, ) void
参数
std.Io.noNow
函数
pub fn noNow(userdata: ?*anyopaque, clock: Clock) Timestamp
参数
userdata: ?*anyopaque
clock: Clock
std.Io.noRandom
函数
pub fn noRandom(userdata: ?*anyopaque, buffer: []u8) void
参数
userdata: ?*anyopaque
buffer: []u8
std.Io.noSleep
函数
pub fn noSleep(userdata: ?*anyopaque, clock: Timeout) Cancelable!void
参数
userdata: ?*anyopaque
clock: Timeout
错误
- Canceled
调用方请求停止异步操作。
std.Io.noTryLockStderr
函数
pub fn noTryLockStderr(userdata: ?*anyopaque, terminal_mode: ?Terminal.Mode) Cancelable!?LockedStderr
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.operate
函数
执行一个 Operation。
pub fn operate(io: Io, operation: Operation) Cancelable!Operation.Result
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.operateTimeout
函数
使用给定 timeout 执行一个 Operation。
pub fn operateTimeout(io: Io, operation: Operation, timeout: Timeout) OperateTimeoutError!Operation.Result
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- ConcurrencyUnavailable ConcurrentError
可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。
- Timeout Error
std.Io.OperateTimeoutError
错误集合
错误
- Canceled Cancelable
调用方请求停止异步操作。
- ConcurrencyUnavailable ConcurrentError
可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。
- Timeout Error
std.Io.Operation
容器
字段
file_read_streaming: FileReadStreaming
file_write_streaming: FileWriteStreaming
device_io_control: DeviceIoControlWindows 上为 NtDeviceIoControlFile,POSIX 上为 ioctl。 其他系统上此标签不可达。
net_receive: NetReceive
net_send: NetSend
net_read: NetRead
net_write: NetWrite
std.Io.Operation.DeviceIoControl
类型
std.Io.Operation.DeviceIoControl.Result
别名
std.Io.Operation.DeviceIoControl.Result
类型
取决于设备及操作的结果。负值是 取负的 errno。
std.Io.Operation.FileReadStreaming
容器
读取可能返回 0,这与 error.EndOfStream 不同。
字段
file: File
data: []const []u8
std.Io.Operation.FileReadStreaming.Error
错误集合
错误
- 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
常量
std.Io.Operation.FileReadStreaming.UnendingError
错误集合
错误
- AccessDenied
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- ConnectionResetByPeer
- InputOutput
- IsDir
尝试将目录文件描述符当作普通文件读取。
- LockViolation
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading
打开文件时未授予读取能力。
- SocketUnconnected
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- WouldBlock
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.Operation.FileWriteStreaming
容器
字段
std.Io.Operation.FileWriteStreaming.Error
错误集合
错误
- 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
常量
std.Io.Operation.List
容器
字段
head: OptionalIndex
tail: OptionalIndex
std.Io.Operation.List.DoubleNode
容器
字段
prev: OptionalIndex
next: OptionalIndex
std.Io.Operation.List.empty
常量
List
std.Io.Operation.List.SingleNode
容器
字段
next: OptionalIndex
std.Io.Operation.NetRead
容器
字段
std.Io.Operation.NetRead.Error
错误集合
错误
- AccessDenied
文件描述符不具有读取所需权限。
- ConnectionResetByPeer
- ConnectionTimedOut
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- NetworkDown
- SocketUnconnected
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Operation.NetRead.Result
常量
std.Io.Operation.NetReceive
容器
字段
socket_handle: net.Socket.Handle
message_buffer: []net.IncomingMessage
data_buffer: []u8
flags: net.ReceiveFlags
std.Io.Operation.NetReceive.Error
错误集合
错误
- ConnectionResetByPeer
发送方意外关闭了网络连接。
- ConnectionTimedOut
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- MessageOversize
此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。
- NetworkDown
用于到达目标的本地网络接口已离线。
- PortUnreachable
此前成功发送了无连接数据包,但远端系统的传输目标端口上没有运行任何服务,因此数据包未被接收。 这使得操作系统收到 ICMP 端口不可达数据包,并将其排队,以便下次在该绑定套接字上调用发送或接收操作时报告。
- ProcessFdQuotaExceeded
已达到每进程可打开文件描述符数量上限。
- SocketUnconnected
面向连接的套接字的本地端已关闭,或 该套接字从未连接。
- SystemFdQuotaExceeded
已达到系统范围内已打开文件的总数上限。
- SystemResources
操作系统内部内存或其他资源不足。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Operation.NetReceive.Result
容器
字段
?net.Socket.ReceiveError
usize
std.Io.Operation.NetSend
容器
字段
std.Io.Operation.NetSend.Error
错误集合
错误
- AccessDenied
尝试向网络/广播地址发送数据, 却将其当作单播地址。
- AddressFamilyUnsupported
操作系统或协议不支持该地址族。
- ConnectionRefused
目标地址未在侦听;对于无连接消息也可能发生此情况。
- ConnectionResetByPeer
网络会话被接收方意外关闭。
- ConnectionTimedOut
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- FastOpenAlreadyInProgress
另一个 TCP 快速打开已在进行。
- HostUnreachable
可到达网络,但没有到主机的路由。
- MessageOversize
此套接字类型要求以原子方式发送消息,但待发送 消息的大小使其无法实现。消息未发送, 或仅发送了一部分。
- NetworkDown
用于到达目标的本地网络接口已离线。
- NetworkUnreachable
没有到网络的路由。
- SocketUnconnected
面向连接的套接字的本地端已关闭,或 该套接字从未连接。
- SystemResources
网络接口的输出队列已满。这通常表示 接口已停止发送,但也可能由短暂拥塞导致。通常, Linux 不会发生此错误;设备队列溢出时只会 静默丢弃分组。
可用内核内存不足时也会发生此错误。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Operation.NetSend.Result
容器
字段
std.Io.Operation.NetWrite
容器
字段
std.Io.Operation.NetWrite.Error
错误集合
错误
- AddressFamilyUnsupported
传入地址的 sa_family 字段未包含正确的地址族。
- ConnectionRefused
目标地址未在监听。
- ConnectionResetByPeer
网络会话被接收方意外关闭。
- ConnectionTimedOut
远端对等方未响应正在进行的通信,导致 操作系统中止连接。
- FastOpenAlreadyInProgress
另一个 TCP 快速打开已在进行。
- HostUnreachable
可到达网络,但没有到主机的路由。
- NetworkDown
用于到达目标的本地网络接口已关闭。
- NetworkUnreachable
没有到网络的路由。
- SocketNotBound
- SocketUnconnected
面向连接的套接字的本地端已关闭,或 该套接字从未连接。
- SystemResources
网络接口的输出队列已满。这通常表示 接口已停止发送,但也可能由短暂拥塞导致。通常, Linux 不会发生此错误;设备队列溢出时只会 静默丢弃分组。
可用内核内存不足时也会发生此错误。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.Operation.NetWrite.Result
常量
std.Io.Operation.OptionalIndex
容器
字段
std.Io.Operation.OptionalIndex.fromIndex
函数
pub fn fromIndex(i: usize) OptionalIndex
参数
i: usize
std.Io.Operation.OptionalIndex.toIndex
函数
pub fn toIndex(oi: OptionalIndex) u32
参数
oi: OptionalIndex
std.Io.Operation.Result
常量
std.Io.Operation.Storage
容器
字段
std.Io.Operation.Storage.Completion
容器
字段
node: List.SingleNode
result: Result
std.Io.Operation.Storage.Pending
容器
字段
std.Io.Operation.Storage.Pending.Userdata
类型
std.Io.Operation.Storage.Submission
容器
字段
node: List.SingleNode
operation: Operation
std.Io.Operation.Tag
常量
std.Io.Queue
类型函数
多生产者、多消费者、线程安全、缓冲区大小可在运行时配置。 缓冲区为空时,消费者挂起,由生产者恢复。 缓冲区满时,生产者挂起,由消费者恢复。
pub fn Queue(Elem: type) type
参数
Elem: type
字段
type_erased: TypeErasedQueue
std.Io.Queue.capacity
函数
返回以 Elem 为单位的缓冲区长度。
pub fn capacity(q: *const @This()) usize
参数
q: *const @This()
std.Io.Queue.close
函数
调用后,队列进入“已关闭”状态。已关闭的
队列在尝试放入元素时始终返回 error.Closed,即使
缓冲区中仍有空间。但在返回 error.Closed
之前,仍可取出队列中已有的元素。
线程安全。
pub fn close(q: *@This(), io: Io) void
参数
q: *@This()
io: Io
std.Io.Queue.get
函数
从队列头部接收元素,当前元素不足时可能阻塞。满足以下任一条件时返回:
- 至少从队列接收到
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
参数
std.Io.Queue.getOne
函数
从队首接收一个元素;如果队列为空,则阻塞。
pub fn getOne(q: *@This(), io: Io) (QueueClosedError || Cancelable)!Elem
参数
q: *@This()
io: Io
std.Io.Queue.getOneUncancelable
函数
与 getOne 相同,但不引入取消点。
取消及取消点的说明见 Future.cancel。
pub fn getOneUncancelable(q: *@This(), io: Io) QueueClosedError!Elem
参数
q: *@This()
io: Io
错误
- Closed
std.Io.Queue.getUncancelable
函数
与 get 相同,但不会引入取消点。
关于取消和取消点的说明,参见 Future.cancel。
pub fn getUncancelable(q: *@This(), io: Io, buffer: []Elem, min: usize) QueueClosedError!usize
参数
错误
- Closed
std.Io.Queue.init
函数
pub fn init(buffer: []Elem) @This()
参数
buffer: []Elem
std.Io.Queue.put
函数
将元素追加到队列末尾;容量不足时可能阻塞。 满足以下任一 条件即返回:
- 至少已向队列加入
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
参数
std.Io.Queue.putAll
函数
与 put 相同,但会阻塞,直到所有元素都已加入队列。
如果队列已关闭或操作取消,则返回 error.Closed 或 error.Canceled;
不保证取消或关闭之前,有多少个
elements 已加入队列,也可能一个都没有。
pub fn putAll(q: *@This(), io: Io, elements: []const Elem) (QueueClosedError || Cancelable)!void
参数
std.Io.Queue.putOne
函数
将 item 追加到队尾;队列满时阻塞。
pub fn putOne(q: *@This(), io: Io, item: Elem) (QueueClosedError || Cancelable)!void
参数
std.Io.Queue.putOneUncancelable
函数
与 putOne 相同,但不会引入取消点。
关于取消和取消点的说明,参见 Future.cancel。
pub fn putOneUncancelable(q: *@This(), io: Io, item: Elem) QueueClosedError!void
参数
错误
- Closed
std.Io.Queue.putUncancelable
函数
与 put 相同,但不引入取消点。
关于取消和取消点,参见 Future.cancel。
pub fn putUncancelable(q: *@This(), io: Io, elements: []const Elem, min: usize) QueueClosedError!usize
参数
错误
- Closed
std.Io.QueueClosedError
错误集合
错误
- Closed
std.Io.random
函数
从密码学安全的伪随机数生成器获取熵。
实现可能在进程内存中存储随机数生成器状态,并用它填充 buffer。
随机种子来自 randomSecure;若失败,则使用安全性较低的机制。
线程安全。
另见 randomSecure。
pub fn random(io: Io, buffer: []u8) void
参数
io: Io
buffer: []u8
std.Io.randomSecure
函数
从进程外部获取密码学安全的熵。
始终发起系统调用,或通过其他方式避免依赖进程内存, 以获取新鲜的随机性。不依赖已保存的随机数生成器状态。
不提供任何后备机制;出现任何问题时均返回
error.EntropyUnavailable。
线程安全。
另见 random。
pub fn randomSecure(io: Io, buffer: []u8) RandomSecureError!void
参数
io: Io
buffer: []u8
错误
- Canceled Cancelable
调用方请求停止异步操作。
- EntropyUnavailable
std.Io.RandomSecureError
错误集合
错误
- Canceled Cancelable
调用方请求停止异步操作。
- EntropyUnavailable
std.Io.Reader
别名
别名目标 std.Io.Reader
std.Io.recancel
函数
断言此前的取消点返回了 error.Canceled,并重新激活
取消请求,使下一个取消点再次返回 error.Canceled。
关于取消及取消点的说明,参见 Future.cancel。
pub fn recancel(io: Io) void
参数
io: Io
std.Io.RwLock
别名
别名目标 std.Io.RwLock
std.Io.Select
类型函数
共同执行任务,并提供等待一个或多个任务完成的机制。类似 Batch,但工作在更高层的任务抽象层,而不是较底层的 Operation 抽象层。
给定的带标签联合体用作等待函数的返回类型。调用异步或并发接口时,需要指定被调用函数完成后的结果放入哪个联合体字段。
pub fn Select(comptime U: type) type
参数
U: type
字段
std.Io.Select.async
函数
异步调用 function,参数为 args。所创建资源由此选择器拥有。
function 的返回类型必须与 field 字段匹配,该字段属于 Union。
function 可能在 async 返回之前立即调用。
此函数返回时,保证 function 要么已调用并完成,要么已成功分配到一个并发执行单元。
调用此函数后,必须在选择器反初始化之前调用 await 或 cancel。
线程安全。
相关接口:
Io.asyncGroup.async
pub fn async( s: *S, comptime field: Field, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function)), ) void
参数
std.Io.Select.async.start
函数
fn start(type_erased_context: *const anyopaque) void
参数
type_erased_context: *const anyopaque
std.Io.Select.await
函数
阻塞直到 select 中另一个任务完成。
此后仍可合法调用 async 和 concurrent。
线程安全。
pub fn await(s: *S) Cancelable!U
参数
s: *S
错误
- Canceled
调用方请求停止异步操作。
std.Io.Select.awaitMany
函数
阻塞直到至少有 min 个结果被复制
到 buffer。
断言 buffer.len >= min。
此后可以合法调用 async 和 concurrent。
线程安全。
pub fn awaitMany(s: *S, buffer: []U, min: usize) Cancelable!usize
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Select.cancel
函数
请求取消此选择器拥有的全部剩余任务,然后阻塞,直到这些任务全部结束。若初始化选择器时,缓冲区空间不足以容纳所有剩余任务的完成结果,则会死锁。
若任一选择任务分配了资源,该任务可能已经完成,因此必须循环调用此函数,直至返回 null,才能释放这些资源。若不存在资源泄漏的可能,则优先使用 cancelDiscard。
此后调用 await 或 awaitMany 属于非法操作。
可安全地多次调用此函数,即使此前已返回 null。
线程安全。
pub fn cancel(s: *S) ?U
参数
s: *S
std.Io.Select.cancelDiscard
函数
请求取消此 select 拥有的所有剩余任务, 然后阻塞至它们全部结束。
丢弃所有未完成任务的返回值。因此,
任务可能返回已分配资源时,不适合调用
此函数。此场景请参见 cancel。
此后调用 await 或 awaitMany 属于非法行为。
可以安全地多次调用。
线程安全。
pub fn cancelDiscard(s: *S) void
参数
s: *S
std.Io.Select.concurrent
函数
并发调用 function,参数为 args。所创建资源由此选择器拥有。
function 的返回类型必须与 field 字段匹配,该字段属于 Union。
此函数成功返回后,保证 function 已分配到一个并发执行单元,并且必须在选择器反初始化前调用 await 或 cancel。
线程安全。
相关接口:
Io.concurrentGroup.concurrent
pub fn concurrent( s: *S, comptime field: Field, function: anytype, args: std.meta.ArgsTuple(@TypeOf(function)), ) ConcurrentError!void
参数
错误
- ConcurrencyUnavailable
可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。
std.Io.Select.concurrent.start
函数
fn start(type_erased_context: *const anyopaque) void
参数
type_erased_context: *const anyopaque
std.Io.Select.Field
类型
std.Io.Select.init
函数
pub fn init(io: Io, buffer: []U) S
参数
io: Io
buffer: []U
std.Io.Select.S
别名
别名目标 std.Io.Select
std.Io.Select.Union
常量
std.Io.Semaphore
别名
别名目标 std.Io.Semaphore
std.Io.sleep
函数
pub fn sleep(io: Io, duration: Duration, clock: Clock) Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.std
别名
别名目标 std
std.Io.swapCancelProtection
函数
更新当前任务的取消保护状态,参见 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
别名
别名目标 std.Io.Terminal
std.Io.Threaded
别名
别名目标 std.Io.Threaded
std.Io.Timeout
容器
声明操作应在何种条件下返回 error.Timeout。
字段
std.Io.Timeout.Error
错误集合
错误
- Timeout
std.Io.Timeout.sleep
函数
等待至超时期限经过。
另请参见:
Io.sleepClock.Duration.sleepClock.Timestamp.wait
pub fn sleep(timeout: Timeout, io: Io) Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.Timeout.toDeadline
函数
pub fn toDeadline(t: Timeout, io: Io) Timeout
参数
std.Io.Timeout.toDurationFromNow
函数
pub fn toDurationFromNow(t: Timeout, io: Io) ?Clock.Duration
参数
std.Io.Timeout.toTimestamp
函数
pub fn toTimestamp(t: Timeout, io: Io) ?Clock.Timestamp
参数
std.Io.Timestamp
容器
字段
nanoseconds: i96
std.Io.Timestamp.addDuration
函数
pub fn addDuration(from: Timestamp, duration: Duration) Timestamp
参数
std.Io.Timestamp.compare
函数
pub fn compare(lhs: Timestamp, op: math.CompareOperator, rhs: Timestamp) bool
参数
std.Io.Timestamp.durationTo
函数
pub fn durationTo(from: Timestamp, to: Timestamp) Duration
参数
std.Io.Timestamp.formatNumber
函数
pub fn formatNumber(t: Timestamp, w: *std.Io.Writer, n: std.fmt.Number) std.Io.Writer.Error!void
参数
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.Io.Timestamp.fromNanoseconds
函数
pub fn fromNanoseconds(x: i96) Timestamp
参数
x: i96
std.Io.Timestamp.now
函数
pub fn now(io: Io, clock: Clock) Io.Timestamp
参数
std.Io.Timestamp.subDuration
函数
pub fn subDuration(from: Timestamp, duration: Duration) Timestamp
参数
std.Io.Timestamp.toMicroseconds
函数
pub fn toMicroseconds(t: Timestamp) i64
参数
t: Timestamp
std.Io.Timestamp.toMilliseconds
函数
pub fn toMilliseconds(t: Timestamp) i64
参数
t: Timestamp
std.Io.Timestamp.toNanoseconds
函数
pub fn toNanoseconds(t: Timestamp) i96
参数
t: Timestamp
std.Io.Timestamp.toSeconds
函数
pub fn toSeconds(t: Timestamp) i64
参数
t: Timestamp
std.Io.Timestamp.untilNow
函数
分辨率由 Clock.resolution 决定;若不支持该时钟,
其值可能为 0。
pub fn untilNow(t: Timestamp, io: Io, clock: Clock) Duration
参数
std.Io.Timestamp.withClock
函数
pub fn withClock(t: Timestamp, clock: Clock) Clock.Timestamp
参数
std.Io.Timestamp.zero
常量
Timestamp
std.Io.tryLockStderr
函数
与 lockStderr 相同,但不阻塞。
pub fn tryLockStderr(io: Io, buffer: []u8, terminal_mode: ?Terminal.Mode) Cancelable!?LockedStderr
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.TypeErasedQueue
容器
字段
mutex: Mutex
closed: bool
buffer: []u8环形缓冲区。此数据在逻辑上位于已排队获取者之后。
start: usize
len: usize
putters: std.DoublyLinkedList
getters: std.DoublyLinkedList
std.Io.TypeErasedQueue.close
函数
调用后,队列进入“已关闭”状态。已关闭的
队列在尝试放入元素时始终返回 error.Closed,即使
缓冲区中仍有空间。但在返回 error.Closed
之前,仍可取出队列中已有的元素。
幂等。线程安全。
pub fn close(q: *TypeErasedQueue, io: Io) void
参数
q: *TypeErasedQueue
io: Io
std.Io.TypeErasedQueue.fillRingBufferFromPutters
函数
环形缓冲区存在非零可用空间,且可能有等待中的写入方时调用。 此时已持有互斥锁;任务是将写入方数据复制到 环形缓冲区,并通知那些缓冲区数据 已全部复制完成的写入方。
fn fillRingBufferFromPutters(q: *TypeErasedQueue, io: Io) void
参数
q: *TypeErasedQueue
io: Io
std.Io.TypeErasedQueue.get
函数
pub fn get(q: *TypeErasedQueue, io: Io, buffer: []u8, min: usize) (QueueClosedError || Cancelable)!usize
参数
std.Io.TypeErasedQueue.Get
容器
字段
std.Io.TypeErasedQueue.getLocked
函数
fn getLocked(q: *TypeErasedQueue, io: Io, buffer: []u8, min: usize, uncancelable: bool) (QueueClosedError || Cancelable)!usize
参数
std.Io.TypeErasedQueue.gettableSlice
函数
fn gettableSlice(q: *const TypeErasedQueue) ?[]const u8
参数
q: *const TypeErasedQueue
std.Io.TypeErasedQueue.getUncancelable
函数
与 get 相同,但不会引入取消点。
关于取消和取消点的说明,参见 Future.cancel。
pub fn getUncancelable(q: *TypeErasedQueue, io: Io, buffer: []u8, min: usize) QueueClosedError!usize
参数
错误
- Closed
std.Io.TypeErasedQueue.init
函数
pub fn init(buffer: []u8) TypeErasedQueue
参数
buffer: []u8
std.Io.TypeErasedQueue.put
函数
pub fn put(q: *TypeErasedQueue, io: Io, elements: []const u8, min: usize) (QueueClosedError || Cancelable)!usize
参数
std.Io.TypeErasedQueue.Put
容器
字段
std.Io.TypeErasedQueue.putLocked
函数
fn putLocked(q: *TypeErasedQueue, io: Io, elements: []const u8, min: usize, uncancelable: bool) (QueueClosedError || Cancelable)!usize
参数
std.Io.TypeErasedQueue.puttableSlice
函数
fn puttableSlice(q: *const TypeErasedQueue) ?[]u8
参数
q: *const TypeErasedQueue
std.Io.TypeErasedQueue.putUncancelable
函数
与 put 相同,但不引入取消点。
关于取消和取消点,参见 Future.cancel。
pub fn putUncancelable(q: *TypeErasedQueue, io: Io, elements: []const u8, min: usize) QueueClosedError!usize
参数
错误
- Closed
std.Io.UnexpectedError
错误集合
错误
- Unexpected
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.unlockStderr
函数
pub fn unlockStderr(io: Io) void
参数
io: Io
std.Io.unreachableAwait
函数
pub fn unreachableAwait( userdata: ?*anyopaque, any_future: *AnyFuture, result: []u8, result_alignment: std.mem.Alignment, ) void
参数
std.Io.unreachableBatchAwaitAsync
函数
pub fn unreachableBatchAwaitAsync(userdata: ?*anyopaque, b: *Batch) Cancelable!void
参数
userdata: ?*anyopaque
b: *Batch
错误
- Canceled
调用方请求停止异步操作。
std.Io.unreachableBatchAwaitConcurrent
函数
pub fn unreachableBatchAwaitConcurrent(userdata: ?*anyopaque, b: *Batch, timeout: Timeout) Batch.AwaitConcurrentError!void
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- ConcurrencyUnavailable ConcurrentError
可能由资源耗尽等临时情况引起,也可能因为 Io 实现不支持并发。
- Timeout Error
std.Io.unreachableBatchCancel
函数
pub fn unreachableBatchCancel(userdata: ?*anyopaque, b: *Batch) void
参数
userdata: ?*anyopaque
b: *Batch
std.Io.unreachableCancel
函数
pub fn unreachableCancel( userdata: ?*anyopaque, any_future: *AnyFuture, result: []u8, result_alignment: std.mem.Alignment, ) void
参数
std.Io.unreachableCheckCancel
函数
pub fn unreachableCheckCancel(userdata: ?*anyopaque) Cancelable!void
参数
userdata: ?*anyopaque
错误
- Canceled
调用方请求停止异步操作。
std.Io.unreachableChildKill
函数
pub fn unreachableChildKill(userdata: ?*anyopaque, child: *std.process.Child) void
参数
std.Io.unreachableChildWait
函数
pub fn unreachableChildWait(userdata: ?*anyopaque, child: *std.process.Child) std.process.Child.WaitError!std.process.Child.Term
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.unreachableDirClose
函数
pub fn unreachableDirClose(userdata: ?*anyopaque, dirs: []const Dir) void
参数
userdata: ?*anyopaque
dirs: []const Dir
std.Io.unreachableFileClose
函数
pub fn unreachableFileClose(userdata: ?*anyopaque, files: []const File) void
参数
userdata: ?*anyopaque
files: []const File
std.Io.unreachableFileEnableAnsiEscapeCodes
函数
pub fn unreachableFileEnableAnsiEscapeCodes(userdata: ?*anyopaque, file: File) File.EnableAnsiEscapeCodesError!void
参数
userdata: ?*anyopaque
file: File
错误
- Canceled Cancelable
调用方请求停止异步操作。
- NotTerminalDevice
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.unreachableFileIsTty
函数
pub fn unreachableFileIsTty(userdata: ?*anyopaque, file: File) Cancelable!bool
参数
userdata: ?*anyopaque
file: File
错误
- Canceled
调用方请求停止异步操作。
std.Io.unreachableFileMemoryMapDestroy
函数
pub fn unreachableFileMemoryMapDestroy(userdata: ?*anyopaque, mm: *File.MemoryMap) void
参数
std.Io.unreachableFileMemoryMapRead
函数
pub fn unreachableFileMemoryMapRead(userdata: ?*anyopaque, mm: *File.MemoryMap) File.ReadPositionalError!void
参数
错误
- AccessDenied
在 WASI 中,当文件描述符不具有读取 所需的权限时发生此错误。
- Canceled Cancelable
调用方请求停止异步操作。
- InputOutput
- IsDir
尝试将目录文件描述符当作普通文件读取。
- LockViolation
由于锁定而无法读取文件。根据
Io实现的不同,读取已锁定文件可能返回此错误,也可能忽略锁。- NotOpenForReading
打开文件时未授予读取能力。
- SystemResources
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
- Unseekable
此文件不支持按位置读取。
- WouldBlock
已启用非阻塞模式,且从该文件描述符读取会阻塞。
std.Io.unreachableFileMemoryMapSetLength
函数
pub fn unreachableFileMemoryMapSetLength(userdata: ?*anyopaque, mm: *File.MemoryMap, new_len: usize) File.MemoryMap.SetLengthError!void
参数
错误
- AccessDenied
以下任一情况:
File.Kind不是file。- 文件未以读取方式打开,且启用了读取访问保护。
- 文件未以写入方式打开,且启用了写入访问保护。
- Canceled Cancelable
调用方请求停止异步操作。
- FileBusy SetLengthError
- FileTooBig SetLengthError
- InputOutput SetLengthError
- LockedMemoryLimitExceeded
- NonResizable SetLengthError
- OperationUnsupported
- OutOfMemory Error
- PermissionDenied
prot参数请求PROT_EXEC,但映射区域属于 挂载为禁止执行的文件系统中的文件。- ProcessFdQuotaExceeded
- SystemFdQuotaExceeded
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.unreachableFileMemoryMapWrite
函数
pub fn unreachableFileMemoryMapWrite(userdata: ?*anyopaque, mm: *File.MemoryMap) File.WritePositionalError!void
参数
错误
- 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
函数
pub fn unreachableFileSupportsAnsiEscapeCodes(userdata: ?*anyopaque, file: File) Cancelable!bool
参数
userdata: ?*anyopaque
file: File
错误
- Canceled
调用方请求停止异步操作。
std.Io.unreachableFileUnlock
函数
pub fn unreachableFileUnlock(userdata: ?*anyopaque, file: File) void
参数
userdata: ?*anyopaque
file: File
std.Io.unreachableGroupAwait
函数
pub fn unreachableGroupAwait(userdata: ?*anyopaque, group: *Group, token: *anyopaque) Cancelable!void
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.unreachableGroupCancel
函数
pub fn unreachableGroupCancel(userdata: ?*anyopaque, group: *Group, token: *anyopaque) void
参数
std.Io.unreachableLockStderr
函数
pub fn unreachableLockStderr(userdata: ?*anyopaque, terminal_mode: ?Terminal.Mode) Cancelable!LockedStderr
参数
错误
- Canceled
调用方请求停止异步操作。
std.Io.unreachableNetClose
函数
pub fn unreachableNetClose(userdata: ?*anyopaque, sockets: []const net.Socket) void
参数
std.Io.unreachableNetInterfaceName
函数
pub fn unreachableNetInterfaceName(userdata: ?*anyopaque, interface: net.Interface) net.Interface.NameError!net.Interface.Name
参数
错误
- Canceled Cancelable
调用方请求停止异步操作。
- InterfaceNotFound
index超出范围。- NameTooLong
接口名称长于
Name.max_len。- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.Io.unreachableRecancel
函数
pub fn unreachableRecancel(userdata: ?*anyopaque) void
参数
userdata: ?*anyopaque
std.Io.unreachableSwapCancelProtection
函数
pub fn unreachableSwapCancelProtection(userdata: ?*anyopaque, new: CancelProtection) CancelProtection
参数
userdata: ?*anyopaque
new: CancelProtection
std.Io.unreachableUnlockStderr
函数
pub fn unreachableUnlockStderr(userdata: ?*anyopaque) void
参数
userdata: ?*anyopaque
std.Io.Uring
别名
别名目标 std.Io.Uring
std.Io.VTable
容器
字段
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
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
别名
别名目标 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;
/// 阻塞调用线程,直到逻辑布尔值被设置、超时到期,或
/// 发生伪唤醒。若超时到期或发生伪唤醒,则返回 `error.Timeout`。
///
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`。
//
//
}
try io.futexWaitTimeout(Event, event, .waiting, timeout);
switch (@atomicLoad(Event, event, .acquire)) {
.unset => unreachable, // 在待处理的 `wait` 返回之前调用了 `reset`
.waiting => 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;
_ = header;
_ = offset;
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);
}