字段
id: ?Id
thread_handle: if (native_os == .windows) std.os.windows.HANDLE else void
stdin: ?File子进程标准输入管道的写入端。
使用时要求设置 process.SpawnOptions.StdIo.pipe。
stdout: ?File子进程标准输出管道的读取端。
使用时要求 process.SpawnOptions.StdIo.pipe。
stderr: ?File子进程标准错误管道的读取端。
使用此字段要求设置 process.SpawnOptions.StdIo.pipe。
resource_usage_statistics: ResourceUsageStatistics = .{}如果在调用 spawn 之前将
request_resource_usage_statistics 设置为 true,
则调用 wait 后可获取此数据。
TODO 将此数据移入 Term
request_resource_usage_statistics: bool
std.process.Child.Allocator
别名
别名目标 std.mem.Allocator
std.process.Child.assert
别名
别名目标 std.debug.assert
std.process.Child.builtin
常量
std.process.Child.Child
别名
别名目标 std.process.Child
std.process.Child.Cwd
容器
字段
std.process.Child.File
别名
别名目标 std.Io.File
std.process.Child.Id
类型
std.process.Child.Io
别名
别名目标 std.Io
std.process.Child.kill
函数
pub fn kill(child: *Child, io: Io) void
参数
std.process.Child.native_os
常量
std.process.Child.process
别名
别名目标 std.process
std.process.Child.ResourceUsageStatistics
容器
字段
rusage: @TypeOf(rusage_init) = rusage_init
std.process.Child.ResourceUsageStatistics.getMaxRss
函数
若可用,则返回子进程的峰值常驻集大小,单位为字节。
pub inline fn getMaxRss(rus: ResourceUsageStatistics) ?usize
参数
std.process.Child.ResourceUsageStatistics.rusage_init
常量
std.process.Child.std
别名
别名目标 std
std.process.Child.Term
容器
字段
std.process.Child.Term.format
函数
pub fn format(t: Term, w: *Io.Writer) Io.Writer.Error!void
参数
错误
- WriteFailed
详细诊断信息见
Writer实现。
std.process.Child.Term.success
函数
pub fn success(t: Term) bool
参数
t: Term
std.process.Child.wait
函数
阻塞直到子进程终止,然后清理所有资源。
pub fn wait(child: *Child, io: Io) WaitError!Term
参数
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
std.process.Child.WaitError
错误集合
错误
- AccessDenied
- Canceled Cancelable
调用方请求停止异步操作。
- Unexpected UnexpectedError
操作系统返回了未记录在文档中的错误码。
理论上不可能出现此错误,但处理 此错误优于触发未定义行为。
观察到此错误码时,通常意味着 Zig 标准 库需要小幅修补,将该错误码加入 相应函数的错误集合。
源码
std/process/Child.zig
const Child = @This();
const builtin = @import("builtin");
const native_os = builtin.os.tag;
const std = @import("../std.zig");
const Io = std.Io;
const process = std.process;
const File = std.Io.File;
const assert = std.debug.assert;
const Allocator = std.mem.Allocator;
pub const Id = switch (native_os) {
.windows => std.os.windows.HANDLE,
.wasi => void,
else => std.posix.pid_t,
};
/// 调用 `wait` 或 `kill` 后,此值变为 `null`。
/// 在 Windows 上为 hProcess。
/// 在 POSIX 上为 pid。
id: ?Id,
thread_handle: if (native_os == .windows) std.os.windows.HANDLE else void,
/// 子进程标准输入管道的写入端。
/// 使用时要求设置 `process.SpawnOptions.StdIo.pipe`。
stdin: ?File,
/// 子进程标准输出管道的读取端。
/// 使用时要求 `process.SpawnOptions.StdIo.pipe`。
stdout: ?File,
/// 子进程标准错误管道的读取端。
/// 使用此字段要求设置 `process.SpawnOptions.StdIo.pipe`。
stderr: ?File,
/// 如果在调用 `spawn` 之前将
/// `request_resource_usage_statistics` 设置为 `true`,
/// 则调用 wait 后可获取此数据。
/// TODO 将此数据移入 `Term`
resource_usage_statistics: ResourceUsageStatistics = .{},
request_resource_usage_statistics: bool,
pub const ResourceUsageStatistics = struct {
rusage: @TypeOf(rusage_init) = rusage_init,
/// 若可用,则返回子进程的峰值常驻集大小,单位为字节。
///
pub inline fn getMaxRss(rus: ResourceUsageStatistics) ?usize {
switch (native_os) {
.dragonfly, .freebsd, .netbsd, .openbsd, .illumos, .linux, .serenity => {
if (rus.rusage) |ru| {
return @as(usize, @intCast(ru.maxrss)) * 1024;
} else {
return null;
}
},
.windows => {
if (rus.rusage) |ru| {
return ru.PeakWorkingSetSize;
} else {
return null;
}
},
.driverkit, .ios, .maccatalyst, .macos, .tvos, .visionos, .watchos => {
if (rus.rusage) |ru| {
// Darwin 特殊地以字节而非千字节报告。
return @as(usize, @intCast(ru.maxrss));
} else {
return null;
}
},
else => return null,
}
}
const rusage_init = switch (native_os) {
.dragonfly,
.freebsd,
.netbsd,
.openbsd,
.illumos,
.linux,
.serenity,
.driverkit,
.ios,
.maccatalyst,
.macos,
.tvos,
.visionos,
.watchos,
=> @as(?std.posix.rusage, null),
.windows => @as(?std.os.windows.PROCESS.VM_COUNTERS, null),
else => {},
};
};
pub const Term = union(enum) {
exited: u8,
signal: std.posix.SIG,
stopped: std.posix.SIG,
unknown: u32,
pub fn success(t: Term) bool {
return switch (t) {
.exited => |code| code == 0,
else => false,
};
}
pub fn format(t: Term, w: *Io.Writer) Io.Writer.Error!void {
switch (t) {
.exited => |code| return w.print("exited with code {d}", .{code}),
.signal => |sig| return w.print("terminated with signal {t}", .{sig}),
.stopped => |sig| return w.print("stopped with signal {t}", .{sig}),
.unknown => return w.writeAll("terminated unexpectedly"),
}
}
};
pub const Cwd = union(enum) {
/// 子进程的当前工作目录与当前进程相同。
inherit,
/// POSIX 系统上,在 `fork` 之后使用此句柄调用 `fchdir`。
/// Windows 上,从提供的句柄推导路径,并在调用 `CreateProcessW` 时使用该路径。
dir: Io.Dir,
/// 在 POSIX 系统上,`fork` 后使用此路径调用 `chdir`。
/// 在 Windows 上,调用 `CreateProcessW` 时使用此路径。
path: []const u8,
};
/// 请求操作系统强制终止子进程,
/// 然后阻塞至其终止,再清理全部资源。
///
/// 幂等;`wait` 返回后不执行任何操作。
///
/// 不可取消。忽略操作系统的意外错误。
pub fn kill(child: *Child, io: Io) void {
if (child.id == null) {
assert(child.stdin == null);
assert(child.stdout == null);
assert(child.stderr == null);
return;
}
io.vtable.childKill(io.userdata, child);
assert(child.id == null);
}
pub const WaitError = error{
AccessDenied,
} || Io.Cancelable || Io.UnexpectedError;
/// 阻塞直到子进程终止,然后清理所有资源。
pub fn wait(child: *Child, io: Io) WaitError!Term {
assert(child.id != null);
return io.vtable.childWait(io.userdata, child);
}
test {
_ = Term;
}