跳转到内容

std.process.Child

标准库Zig 0.17.1官方原文
源码std/process/Child.zig

第 1 行

字段

id: ?Id

调用 wait 或 kill 后,此值变为 null。 在 Windows 上为 hProcess。 在 POSIX 上为 pid。

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

别名

第 11 行

别名目标 std.mem.Allocator

std.process.Child.assert

别名

第 10 行

别名目标 std.debug.assert

std.process.Child.builtin

常量

第 3 行

std.process.Child.Child

别名

第 1 行

别名目标 std.process.Child

std.process.Child.Cwd

容器

第 117 行

字段

inherit

子进程的当前工作目录与当前进程相同。

dir: Io.Dir

POSIX 系统上,在 fork 之后使用此句柄调用 fchdir。 Windows 上,从提供的句柄推导路径,并在调用 CreateProcessW 时使用该路径。

path: []const u8

在 POSIX 系统上,fork 后使用此路径调用 chdir。 在 Windows 上,调用 CreateProcessW 时使用此路径。

std.process.Child.File

别名

第 9 行

别名目标 std.Io.File

std.process.Child.Id

类型

第 13 行

std.process.Child.Io

别名

第 7 行

别名目标 std.Io

std.process.Child.kill

函数

第 134 行

请求操作系统强制终止子进程, 然后阻塞至其终止,再清理全部资源。

幂等;wait 返回后不执行任何操作。

不可取消。忽略操作系统的意外错误。

pub fn kill(child: *Child, io: Io) void

参数

child: *Child
io: Io

std.process.Child.native_os

常量

第 4 行

std.process.Child.process

别名

第 8 行

别名目标 std.process

std.process.Child.ResourceUsageStatistics

容器

第 40 行

字段

rusage: @TypeOf(rusage_init) = rusage_init

std.process.Child.ResourceUsageStatistics.getMaxRss

函数

第 45 行

若可用,则返回子进程的峰值常驻集大小,单位为字节。

pub inline fn getMaxRss(rus: ResourceUsageStatistics) ?usize

参数

std.process.Child.ResourceUsageStatistics.rusage_init

常量

第 73 行

std.process.Child.std

别名

第 6 行

别名目标 std

std.process.Child.Term

容器

第 94 行

字段

exited: u8
signal: std.posix.SIG
stopped: std.posix.SIG
unknown: u32

std.process.Child.Term.format

函数

第 107 行

pub fn format(t: Term, w: *Io.Writer) Io.Writer.Error!void

参数

t: Term
w: *Io.Writer

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.process.Child.Term.success

函数

第 100 行

pub fn success(t: Term) bool

参数

t: Term

std.process.Child.wait

函数

第 150 行

阻塞直到子进程终止,然后清理所有资源。

pub fn wait(child: *Child, io: Io) WaitError!Term

参数

child: *Child
io: Io

错误

AccessDenied
Canceled Cancelable

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

Unexpected UnexpectedError

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

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

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

std.process.Child.WaitError

错误集合

第 145 行

错误

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;
}