Skip to content
Standard libraryZig 0.17.0Official documentation
Sourcestd/zig/Client.zig

Source line 1

Fields

in: *Reader
out: *Writer

std.zig.Client.Allocator

alias

Source line 5

Alias of std.mem.Allocator

std.zig.Client.assert

alias

Source line 6

Alias of std.debug.assert

std.zig.Client.Client

alias

Source line 1

Alias of std.zig.Client

std.zig.Client.Configuration

alias

Source line 7

Alias of std.Build.Configuration

std.zig.Client.InMessage

alias

Source line 9

Alias of std.zig.Server.Message

std.zig.Client.Io

alias

Source line 4

Alias of std.Io

std.zig.Client.Message

namespace

Source line 16

std.zig.Client.Message.Arg

container

Source line 74

Fields

string

Trailing:

  • string: [:0]u8,
prefix

Trailing:

  • string: [:0]u8,
suffix

Trailing:

  • string: [:0]u8,
input_file

Trailing:

  • handle: Handle,
input_dir

Trailing:

  • handle: Handle,
input_file_content

Trailing:

  • handle: Handle,
output_file

Trailing:

  • handle: Handle,
output_dir

Trailing:

  • handle: Handle,

std.zig.Client.Message.BuildSteps

container

Source line 103

Trailing:

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

Fields

step_count: u32
flags: Flags

std.zig.Client.Message.BuildSteps.Flags

container

Source line 107

Fields

watch: bool

Can only be enabled when the server declared support for file watching.

reserved: u31 = 0

std.zig.Client.Message.Header

container

Source line 17

Fields

tag: Tag
bytes_len: u32

Size of the body only; does not include this Header.

std.zig.Client.Message.Tag

container

Source line 23

Fields

exit

Tells the compiler to shut down cleanly. No body.

update

Tells the compiler to detect changes in source files and update the affected output compilation artifacts. If one of the compilation artifacts is an executable that is running as a child process, the compiler will wait for it to exit before performing the update. No body.

run

Tells the compiler to execute the executable as a child process. No body.

hot_update

Tells the compiler to detect changes in source files and update the affected output compilation artifacts. If one of the compilation artifacts is an executable that is running as a child process, the compiler will perform a hot code swap. No body.

query_test_metadata

Ask the test runner for metadata about all the unit tests that can be run. Server will respond with a test_metadata message. No body.

run_test

Ask the test runner to run a particular test. The message body is a u32 test index.

start_fuzzing

Ask the test runner to start fuzzing a set of test forever or each for a given amount of iterations. After this is sent, the only allowed message is new_fuzz_input.

The message body is:

  • a u8 test limit kind (std.Build.api.fuzz.LimitKind)
  • a u64 value whose meaning depends on FuzzLimitKind (either a limit amount or an instance id)
  • a u32 number of tests followed by n elements of
    • a u32 test name len.
    • a test name with the above length
new_fuzz_input

The message body has the same format as in Server.

args

Body is a sequence of Arg

bsp_build_steps = 0x80000000

Asks the server to run a list of steps. Body is a BuildSteps. This message only applies to the build system protocol.

_

std.zig.Client.OutMessage

alias

Source line 8

Alias of std.zig.Client.Message

std.zig.Client.Reader

alias

Source line 10

Alias of std.Io.Reader

std.zig.Client.receiveMessage

function

Source line 120

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

Parameters

c: *const Client

Errors

EndOfStream
ReadFailed

See the Reader implementation for detailed diagnostics.

std.zig.Client.receiveMessageWithMultiReader

function

Source line 126

Assumes that c.in is a reader in multi_reader. Guarantees that the response body will be buffered in c.in on success.

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

Parameters

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

std.zig.Client.serveBodylessMessage

function

Source line 153

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

Parameters

c: *const Client
tag: OutMessage.Tag

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.zig.Client.serveBuildSteps

function

Source line 193

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

Parameters

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

std.zig.Client.serveMessageHeader

function

Source line 149

Don't forget to flush!

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

Parameters

c: *const Client
header: OutMessage.Header

Errors

WriteFailed

See the Writer implementation for detailed diagnostics.

std.zig.Client.serveRunFuzzTestMessage

function

Source line 167

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

Parameters

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

std.zig.Client.serveRunTest

function

Source line 158

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

Parameters

c: *const Client
index: u32

std.zig.Client.std

alias

Source line 3

Alias of std

std.zig.Client.Writer

alias

Source line 11

Alias of std.Io.Writer

Source code

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,
        /// Size of the body only; does not include this Header.
        bytes_len: u32,
    };

    pub const Tag = enum(u32) {
        /// Tells the compiler to shut down cleanly.
        /// No body.
        exit,
        /// Tells the compiler to detect changes in source files and update the
        /// affected output compilation artifacts.
        /// If one of the compilation artifacts is an executable that is
        /// running as a child process, the compiler will wait for it to exit
        /// before performing the update.
        /// No body.
        update,
        /// Tells the compiler to execute the executable as a child process.
        /// No body.
        run,
        /// Tells the compiler to detect changes in source files and update the
        /// affected output compilation artifacts.
        /// If one of the compilation artifacts is an executable that is
        /// running as a child process, the compiler will perform a hot code
        /// swap.
        /// No body.
        hot_update,
        /// Ask the test runner for metadata about all the unit tests that can
        /// be run. Server will respond with a `test_metadata` message.
        /// No body.
        query_test_metadata,
        /// Ask the test runner to run a particular test.
        /// The message body is a u32 test index.
        run_test,
        /// Ask the test runner to start fuzzing a set of test forever or each for a given amount of
        /// iterations. After this is sent, the only allowed message is `new_fuzz_input`.
        ///
        /// The message body is:
        /// - a u8 test limit kind (std.Build.api.fuzz.LimitKind)
        /// - a u64 value whose meaning depends on FuzzLimitKind (either a limit amount or an instance id)
        /// - a u32 number of tests followed by n elements of
        ///   - a u32 test name len.
        ///   - a test name with the above length
        start_fuzzing,
        /// The message body has the same format as in Server.
        new_fuzz_input,
        /// Body is a sequence of Arg
        args,

        /// Asks the server to run a list of steps.
        /// Body is a `BuildSteps`.
        /// This message only applies to the build system protocol.
        bsp_build_steps = 0x80000000,

        _,
    };

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

    /// Trailing:
    /// * 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) {
            /// Can only be enabled when the server declared support for file
            /// watching.
            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);
}

/// Assumes that `c.in` is a reader in `multi_reader`.
/// Guarantees that the response body will be buffered in `c.in` on success.
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;
}

/// Don't forget to flush!
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();
}