跳转到内容

std.zig.Client

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

第 1 行

字段

in: *Reader
out: *Writer

std.zig.Client.Allocator

别名

第 5 行

别名目标 std.mem.Allocator

std.zig.Client.assert

别名

第 6 行

别名目标 std.debug.assert

std.zig.Client.Client

别名

第 1 行

别名目标 std.zig.Client

std.zig.Client.Configuration

别名

第 7 行

别名目标 std.Build.Configuration

std.zig.Client.InMessage

别名

第 9 行

别名目标 std.zig.Server.Message

std.zig.Client.Io

别名

第 4 行

别名目标 std.Io

std.zig.Client.Message

命名空间

第 16 行

std.zig.Client.Message.Arg

容器

第 74 行

字段

string

尾随内容:

  • string: [:0]u8,
prefix

尾随内容:

  • string: [:0]u8,
suffix

尾随内容:

  • string: [:0]u8,
input_file

尾随数据:

  • handle: Handle,
input_dir

尾随数据:

  • handle: Handle,
input_file_content

尾随数据:

  • handle: Handle,
output_file

尾随数据:

  • handle: Handle,
output_dir

尾随数据:

  • handle: Handle,

std.zig.Client.Message.BuildSteps

容器

第 103 行

尾随数据:

  • step_indices: [step_count]std.Build.Configuration.Step.Index,

字段

step_count: u32
flags: Flags

std.zig.Client.Message.BuildSteps.Flags

容器

第 107 行

字段

watch: bool

仅当服务器声明支持文件监视时, 才可启用。

reserved: u31 = 0

std.zig.Client.Message.Header

容器

第 17 行

字段

tag: Tag
bytes_len: u32

仅消息体的大小,不包括此 Header。

std.zig.Client.Message.Tag

容器

第 23 行

字段

exit

通知编译器正常关闭。 无函数体。

update

通知编译器检测源码文件变化,并更新受影响的输出编译产物。 若某个编译产物是正在作为子进程运行的可执行文件,则编译器先等待其退出,再进行更新。 无消息体。

run

告知编译器将可执行文件作为子进程执行。 无消息体。

hot_update

通知编译器检测源文件变化, 并更新受影响的输出编译产物。 若某个编译产物是正在作为子进程运行的 可执行文件,编译器将执行 热代码替换。 无消息体。

query_test_metadata

向测试运行器请求所有可运行单元测试的元数据。 服务器将以 test_metadata 消息响应。 无消息体。

run_test

要求测试运行器执行特定测试。 消息体为 u32 测试索引。

start_fuzzing

要求测试运行器开始无限次模糊测试一组测试,或对每个测试执行指定 次数。发送后,唯一允许的消息是 new_fuzz_input。

消息体如下:

  • 一个 u8 测试限制种类,std.Build.api.fuzz.LimitKind
  • 一个 u64 值,含义取决于 FuzzLimitKind,是限制数量或实例标识符
  • 一个 u32 测试数量,后跟 n 个元素,每个元素包含:
    • 一个 u32 测试名称长度
    • 一个具有上述长度的测试名称
new_fuzz_input

消息体格式与 Server 中相同。

args

主体为 Arg 序列

bsp_build_steps = 0x80000000

请求服务器运行步骤列表。 消息体为 BuildSteps。 此消息仅适用于构建系统协议。

_

std.zig.Client.OutMessage

别名

第 8 行

别名目标 std.zig.Client.Message

std.zig.Client.Reader

别名

第 10 行

别名目标 std.Io.Reader

std.zig.Client.receiveMessage

函数

第 120 行

pub fn receiveMessage(c: *const Client) Reader.Error!InMessage.Header

参数

c: *const Client

错误

EndOfStream
ReadFailed

详细诊断参见 Reader 的实现。

std.zig.Client.receiveMessageWithMultiReader

函数

第 126 行

假定 c.in 是 multi_reader 中的读取器。 成功时,保证响应消息体缓存在 c.in 中。

pub fn receiveMessageWithMultiReader( c: *Client, multi_reader: *Io.File.MultiReader, timeout: Io.Timeout, ) (Io.File.MultiReader.Error || Io.Timeout.Error)!InMessage.Header

参数

c: *Client
multi_reader: *Io.File.MultiReader
timeout: Io.Timeout

std.zig.Client.serveBodylessMessage

函数

第 153 行

pub fn serveBodylessMessage(c: *const Client, tag: OutMessage.Tag) Writer.Error!void

参数

c: *const Client
tag: OutMessage.Tag

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.zig.Client.serveBuildSteps

函数

第 193 行

pub fn serveBuildSteps( c: *const Client, steps: []const Configuration.Step.Index, flags: OutMessage.BuildSteps.Flags, ) !void

参数

c: *const Client
steps: []const Configuration.Step.Index
flags: OutMessage.BuildSteps.Flags

std.zig.Client.serveMessageHeader

函数

第 149 行

不要忘记刷新!

pub fn serveMessageHeader(c: *const Client, header: OutMessage.Header) Writer.Error!void

参数

c: *const Client
header: OutMessage.Header

错误

WriteFailed

详细诊断信息见 Writer 实现。

std.zig.Client.serveRunFuzzTestMessage

函数

第 167 行

pub fn serveRunFuzzTestMessage( c: *const Client, test_names: []const []const u8, kind: std.Build.abi.fuzz.LimitKind, amount_or_instance: u64, ) !void

参数

c: *const Client
test_names: []const []const u8
kind: std.Build.abi.fuzz.LimitKind
amount_or_instance: u64

std.zig.Client.serveRunTest

函数

第 158 行

pub fn serveRunTest(c: *const Client, index: u32) !void

参数

c: *const Client
index: u32

std.zig.Client.std

别名

第 3 行

别名目标 std

std.zig.Client.Writer

别名

第 11 行

别名目标 std.Io.Writer

源码

std/zig/Client.zig

const Client = @This();

const std = @import("std");
const Io = std.Io;
const Allocator = std.mem.Allocator;
const assert = std.debug.assert;
const Configuration = std.Build.Configuration;
const OutMessage = std.zig.Client.Message;
const InMessage = std.zig.Server.Message;
const Reader = Io.Reader;
const Writer = Io.Writer;

in: *Reader,
out: *Writer,

pub const Message = struct {
    pub const Header = extern struct {
        tag: Tag,
        /// 仅消息体的大小,不包括此 Header。
        bytes_len: u32,
    };

    pub const Tag = enum(u32) {
        /// 通知编译器正常关闭。
        /// 无函数体。
        exit,
        /// 通知编译器检测源码文件变化,并更新受影响的输出编译产物。
        /// 若某个编译产物是正在作为子进程运行的可执行文件,则编译器先等待其退出,再进行更新。
        /// 无消息体。
        ///
        ///
        ///
        update,
        /// 告知编译器将可执行文件作为子进程执行。
        /// 无消息体。
        run,
        /// 通知编译器检测源文件变化,
        /// 并更新受影响的输出编译产物。
        /// 若某个编译产物是正在作为子进程运行的
        /// 可执行文件,编译器将执行
        /// 热代码替换。
        /// 无消息体。
        hot_update,
        /// 向测试运行器请求所有可运行单元测试的元数据。
        /// 服务器将以 `test_metadata` 消息响应。
        /// 无消息体。
        query_test_metadata,
        /// 要求测试运行器执行特定测试。
        /// 消息体为 u32 测试索引。
        run_test,
        /// 要求测试运行器开始无限次模糊测试一组测试,或对每个测试执行指定
        /// 次数。发送后,唯一允许的消息是 `new_fuzz_input`。
        ///
        /// 消息体如下:
        /// - 一个 u8 测试限制种类,std.Build.api.fuzz.LimitKind
        /// - 一个 u64 值,含义取决于 FuzzLimitKind,是限制数量或实例标识符
        /// - 一个 u32 测试数量,后跟 n 个元素,每个元素包含:
        ///   - 一个 u32 测试名称长度
        ///   - 一个具有上述长度的测试名称
        start_fuzzing,
        /// 消息体格式与 Server 中相同。
        new_fuzz_input,
        /// 主体为 Arg 序列
        args,

        /// 请求服务器运行步骤列表。
        /// 消息体为 `BuildSteps`。
        /// 此消息仅适用于构建系统协议。
        bsp_build_steps = 0x80000000,

        _,
    };

    pub const Arg = enum(u8) {
        /// 尾随内容:
        /// * string: [:0]u8,
        string,
        /// 尾随内容:
        /// * string: [:0]u8,
        prefix,
        /// 尾随内容:
        /// * string: [:0]u8,
        suffix,
        /// 尾随数据:
        /// * handle: Handle,
        input_file,
        /// 尾随数据:
        /// * handle: Handle,
        input_dir,
        /// 尾随数据:
        /// * handle: Handle,
        input_file_content,
        /// 尾随数据:
        /// * handle: Handle,
        output_file,
        /// 尾随数据:
        /// * handle: Handle,
        output_dir,
    };

    /// 尾随数据:
    /// * step_indices: [step_count]std.Build.Configuration.Step.Index,
    pub const BuildSteps = extern struct {
        step_count: u32,
        flags: Flags,

        pub const Flags = packed struct(u32) {
            /// 仅当服务器声明支持文件监视时,
            /// 才可启用。
            watch: bool,
            reserved: u31 = 0,
        };
    };

    comptime {
        assert(@sizeOf(std.Build.abi.fuzz.LimitKind) == 1);
    }
};

pub fn receiveMessage(c: *const Client) Reader.Error!InMessage.Header {
    return c.in.takeStruct(InMessage.Header, .little);
}

/// 假定 `c.in` 是 `multi_reader` 中的读取器。
/// 成功时,保证响应消息体缓存在 `c.in` 中。
pub fn receiveMessageWithMultiReader(
    c: *Client,
    multi_reader: *Io.File.MultiReader,
    timeout: Io.Timeout,
) (Io.File.MultiReader.Error || Io.Timeout.Error)!InMessage.Header {
    while (c.in.bufferedLen() < @sizeOf(InMessage.Header)) {
        multi_reader.fill(64, timeout) catch |err| switch (err) {
            error.Canceled,
            error.Timeout,
            error.ConcurrencyUnavailable,
            error.EndOfStream,
            => |e| return e,
        };
    }
    const header = c.in.takeStruct(InMessage.Header, .little) catch unreachable;
    while (c.in.bufferedLen() < header.bytes_len) {
        try multi_reader.fill(header.bytes_len - c.in.bufferedLen(), timeout);
    }
    try multi_reader.checkAnyError();
    return header;
}

/// 不要忘记刷新!
pub fn serveMessageHeader(c: *const Client, header: OutMessage.Header) Writer.Error!void {
    try c.out.writeStruct(header, .little);
}

pub fn serveBodylessMessage(c: *const Client, tag: OutMessage.Tag) Writer.Error!void {
    try c.serveMessageHeader(.{ .tag = tag, .bytes_len = 0 });
    try c.out.flush();
}

pub fn serveRunTest(c: *const Client, index: u32) !void {
    try c.serveMessageHeader(.{
        .tag = .run_test,
        .bytes_len = @sizeOf(u32),
    });
    try c.out.writeInt(u32, index, .little);
    try c.out.flush();
}

pub fn serveRunFuzzTestMessage(
    c: *const Client,
    test_names: []const []const u8,
    kind: std.Build.abi.fuzz.LimitKind,
    amount_or_instance: u64,
) !void {
    try c.serveMessageHeader(.{
        .tag = .start_fuzzing,
        .bytes_len = 1 + 8 + 4 + count: {
            var bytes_len: u32 = @intCast(test_names.len * 4);
            for (test_names) |name| {
                bytes_len += @intCast(name.len);
            }
            break :count bytes_len;
        },
    });
    try c.out.writeByte(@backingInt(kind));
    try c.out.writeInt(u64, amount_or_instance, .little);
    try c.out.writeInt(u32, @intCast(test_names.len), .little);
    for (test_names) |test_name| {
        try c.out.writeInt(u32, @intCast(test_name.len), .little);
        try c.out.writeAll(test_name);
    }
    try c.out.flush();
}

pub fn serveBuildSteps(
    c: *const Client,
    steps: []const Configuration.Step.Index,
    flags: OutMessage.BuildSteps.Flags,
) !void {
    try c.serveMessageHeader(.{
        .tag = .bsp_build_steps,
        .bytes_len = @intCast(@sizeOf(OutMessage.BuildSteps) + steps.len * @sizeOf(Configuration.Step.Index)),
    });
    const body: OutMessage.BuildSteps = .{
        .step_count = @intCast(steps.len),
        .flags = flags,
    };
    try c.out.writeStruct(body, .little);
    try c.out.writeSliceEndian(Configuration.Step.Index, steps, .little);
    try c.out.flush();
}