tiny.profiling.execute

1const std = @import("std");2const sys = @import("sys");34const catalog = @import("catalog.zig");56const wait_poll_ms: u64 = 2;7const maximum_grace_ms: u64 = 60_000;89pub const default_termination_grace_ms: u64 = 100;1011pub const zig_env_var = "TINY_PROFILE_ZIG";12pub const build_flag = "-fno-incremental";1314pub const Zig = struct {15    executable: []const u8,16};1718pub const GroupStatus = enum {19    exited,20    stopped,21    timed_out,22};2324pub const GroupIsolation = enum {25    child,26    process_group,27};2829pub const GroupReceipt = struct {30    status: GroupStatus,31    isolation: GroupIsolation,32    pid: u64,33    term: ?sys.process.Termination,34    elapsed_ns: u64,35    terminate_sent: bool,36    kill_sent: bool,37};3839pub const Group = struct {40    child: sys.process.Child,41    child_id: sys.process.Child.Id,42    started_monotonic_ns: i128,43    term: ?sys.process.Termination = null,44    isolation: GroupIsolation,4546    pub fn active(self: *const Group) bool {47        return self.child.id != null;48    }49};5051pub fn zig(environ_map: ?*const sys.process.Environ.Map) Zig {52    const env = environ_map orelse return .{ .executable = "zig" };53    return .{54        .executable = env.get(zig_env_var) orelse "zig",55    };56}5758const test_zig: Zig = .{ .executable = "zig" };5960pub const default_optimize: std.builtin.OptimizeMode = .fast;6162pub fn optimizeBuildArg(mode: std.builtin.OptimizeMode) []const u8 {63    return switch (mode) {64        .debug => "-Doptimize=debug",65        .safe => "-Doptimize=safe",66        .fast => "-Doptimize=fast",67        .small => "-Doptimize=small",68    };69}7071const retain_root_symbols_args = [_][]const u8{72    "-Dproduct-strip-binaries=false",73    "-Dtool-strip-binaries=false",74};7576pub const Result = struct {77    exit_code: i64,78    wall_ns: u64,79    resource_usage_source: ?sys.process.ResourceUsageSource = null,80    maxrss_kib: ?i64 = null,81    user_s: ?f64 = null,82    system_s: ?f64 = null,83    minor_page_faults: ?u64 = null,84    major_page_faults: ?u64 = null,85    voluntary_context_switches: ?u64 = null,86    involuntary_context_switches: ?u64 = null,87    pid: ?u64 = null,88};8990pub const CommandResult = struct {91    command: []const u8,92    argv: []const []const u8,93    cwd: ?[]const u8,94    stdout_path: []const u8,95    stderr_path: []const u8,96    execution: Result,97};9899pub const ArtifactEnv = struct {100    stdout: []const u8,101    stderr: []const u8,102    bench_jsonl: []const u8,103    coz_jsonl: []const u8,104    coz_analysis: []const u8,105    tracy_jsonl: []const u8,106    tracy_summary: []const u8,107    allocations: []const u8,108};109110pub const Scope = enum {111    step,112    binary,113    mixed,114115    pub fn parse(value: []const u8) ?Scope {116        if (std.mem.eql(u8, value, "step")) return .step;117        if (std.mem.eql(u8, value, "binary")) return .binary;118        if (std.mem.eql(u8, value, "mixed")) return .mixed;119        return null;120    }121122    pub fn name(self: Scope) []const u8 {123        return @tagName(self);124    }125126    pub fn directFor(self: Scope, workload: catalog.Workload) bool {127        return switch (self) {128            .step => false,129            .binary => true,130            .mixed => workload.requiresDirectExecution(),131        };132    }133};134135pub const Plan = struct {136    setup_argv: ?[]const []const u8 = null,137    argv: []const []const u8,138    cwd: ?[]const u8 = null,139    direct: bool = false,140    missing_bin: bool = false,141};142143pub fn plan(144    allocator: std.mem.Allocator,145    zig_command: Zig,146    workload: catalog.Workload,147    forwarded: []const []const u8,148    direct: bool,149    build_args: []const []const u8,150) !Plan {151    if (direct) {152        if (workload.bin) |bin| {153            const setup_scope = bin.scope(workload.package);154            const setup_argv = try buildArgv(155                allocator,156                zig_command,157                bin.step,158                build_args,159                workload.buildOptionsFor(setup_scope),160                isRootScope(setup_scope),161                &.{},162                false,163            );164            var argv: std.ArrayList([]const u8) = .empty;165            try argv.append(allocator, bin.path);166            try argv.appendSlice(allocator, bin.args);167            if (workload.forwards_args and forwarded.len != 0) try argv.appendSlice(allocator, forwarded);168            const scope = bin.scope(workload.package);169            return .{170                .setup_argv = setup_argv,171                .argv = try argv.toOwnedSlice(allocator),172                .cwd = if (std.mem.eql(u8, scope, ".")) null else scope,173                .direct = true,174            };175        }176        return .{177            .argv = try childArgv(allocator, zig_command, workload, forwarded, build_args),178            .cwd = workload.cwd,179            .missing_bin = true,180        };181    }182    return .{183        .argv = try childArgv(allocator, zig_command, workload, forwarded, build_args),184        .cwd = workload.cwd,185    };186}187188pub fn childArgv(189    allocator: std.mem.Allocator,190    zig_command: Zig,191    workload: catalog.Workload,192    forwarded: []const []const u8,193    build_args: []const []const u8,194) ![]const []const u8 {195    const scope = workload.cwd orelse ".";196    return try buildArgv(197        allocator,198        zig_command,199        workload.step,200        build_args,201        workload.buildOptionsFor(scope),202        isRootScope(scope),203        forwarded,204        workload.forwards_args,205    );206}207208fn buildArgv(209    allocator: std.mem.Allocator,210    zig_command: Zig,211    step: []const u8,212    build_args: []const []const u8,213    package_options: []const []const u8,214    root_build: bool,215    forwarded: []const []const u8,216    forwards_args: bool,217) ![]const []const u8 {218    if (root_build) std.debug.assert(package_options.len == 0);219    const root_count: usize = if (root_build) retain_root_symbols_args.len else 0;220    const forwarded_count: usize = if (forwards_args and forwarded.len != 0)221        forwarded.len + 1222    else223        0;224    const argv = try allocator.alloc(225        []const u8,226        4 + build_args.len + package_options.len + root_count + forwarded_count,227    );228    argv[0] = zig_command.executable;229    argv[1] = "build";230    argv[2] = build_flag;231    argv[3] = step;232    @memcpy(argv[4 .. 4 + build_args.len], build_args);233    var index = 4 + build_args.len;234    @memcpy(argv[index..][0..package_options.len], package_options);235    index += package_options.len;236    if (root_build) {237        @memcpy(238            argv[index..][0..retain_root_symbols_args.len],239            retain_root_symbols_args[0..],240        );241        index += retain_root_symbols_args.len;242    }243    if (forwarded_count != 0) {244        argv[index] = "--";245        index += 1;246        for (forwarded, 0..) |arg, forwarded_index| {247            argv[index + forwarded_index] = arg;248        }249    }250    return argv;251}252253fn isRootScope(scope: []const u8) bool {254    return std.mem.eql(u8, scope, ".");255}256257pub fn commandText(allocator: std.mem.Allocator, cwd: ?[]const u8, setup_argv: ?[]const []const u8, argv: []const []const u8) ![]const u8 {258    var out: std.Io.Writer.Allocating = .init(allocator);259    errdefer out.deinit();260    const grouped = cwd != null or setup_argv != null;261    if (cwd) |path| {262        try out.writer.print("(cd {s} && ", .{path});263    } else if (grouped) {264        try out.writer.writeByte('(');265    }266    if (setup_argv) |setup| {267        try writeArgv(&out.writer, setup);268        try out.writer.writeAll(" && ");269    }270    try writeArgv(&out.writer, argv);271    if (grouped) try out.writer.writeByte(')');272    return try out.toOwnedSlice();273}274275fn writeArgv(writer: *std.Io.Writer, argv: []const []const u8) !void {276    for (argv, 0..) |arg, index| {277        if (index != 0) try writer.writeByte(' ');278        try writer.writeAll(arg);279    }280}281282pub const BenchControl = struct {283    causal: bool = false,284    min_time_ns: ?u64 = null,285    filter: ?[]const u8 = null,286};287288pub fn environmentWithOverrides(289    allocator: std.mem.Allocator,290    base_env: ?*const sys.process.Environ.Map,291    overrides: []const catalog.EnvironmentOverride,292) !sys.process.Environ.Map {293    try catalog.validateEnvironment(overrides);294    var result = if (base_env) |actual|295        try actual.clone(allocator)296    else297        sys.process.Environ.Map.init(allocator);298    errdefer result.deinit();299    for (overrides) |entry| {300        if (entry.value) |value| {301            try result.put(entry.name, value);302        } else {303            _ = result.swapRemove(entry.name);304        }305    }306    return result;307}308309pub fn spawnGroup(310    process_io: std.Io,311    options: sys.process.SpawnOptions,312) !Group {313    std.debug.assert(options.argv.len != 0);314    var grouped_options = options;315    grouped_options.pgid = childProcessGroup();316    const started_monotonic_ns = sys.time.nanoTimestamp();317    var child = try sys.process.spawn(process_io, grouped_options);318    errdefer sys.process.killAndReap(&child, process_io);319    const child_id = child.id orelse return error.MissingChildProcessId;320    return .{321        .child = child,322        .child_id = child_id,323        .started_monotonic_ns = started_monotonic_ns,324        .isolation = if (grouped_options.pgid == null)325            .child326        else327            .process_group,328    };329}330331pub fn pollGroup(group: *Group) !?sys.process.Termination {332    std.debug.assert(group.active());333    const outcome = (try sys.process.waitNoHang(group.child_id)) orelse334        return null;335    group.child.id = null;336    group.term = outcome.term;337    return outcome.term;338}339340pub fn awaitGroupUntil(341    group: *Group,342    process_io: std.Io,343    deadline_monotonic_ns: i128,344    grace_ms: u64,345) !GroupReceipt {346    std.debug.assert(group.active());347    while (true) {348        if (sys.time.nanoTimestamp() >= deadline_monotonic_ns) {349            return stopGroupAs(group, process_io, grace_ms, .timed_out);350        }351        if (try pollGroup(group)) |_| {352            return groupReceipt(group, .exited, false, false);353        }354        sys.time.sleepMilliseconds(wait_poll_ms);355    }356}357358pub fn stopGroup(359    group: *Group,360    process_io: std.Io,361    grace_ms: u64,362) !GroupReceipt {363    return stopGroupAs(group, process_io, grace_ms, .stopped);364}365366pub fn deadlineNanoseconds(start_monotonic_ns: i128, timeout_ms: u64) i128 {367    const timeout_ns = @as(i128, @intCast(timeout_ms)) * std.time.ns_per_ms;368    return start_monotonic_ns + timeout_ns;369}370371fn stopGroupAs(372    group: *Group,373    process_io: std.Io,374    grace_ms: u64,375    status: GroupStatus,376) !GroupReceipt {377    std.debug.assert(grace_ms <= maximum_grace_ms);378    if (!group.active()) {379        return groupReceipt(group, status, false, false);380    }381    if (group.isolation == .child) {382        return stopChildAs(group, process_io, grace_ms, status);383    }384    const terminate_sent = try signalGroup(group.child_id, .terminate);385    if (!terminate_sent) {386        group.term = try sys.process.wait(&group.child, process_io);387        return groupReceipt(group, status, false, false);388    }389    sys.time.sleepMilliseconds(grace_ms);390    const kill_sent = try signalGroup(group.child_id, .kill);391    group.term = try sys.process.wait(&group.child, process_io);392    return groupReceipt(group, status, true, kill_sent);393}394395fn stopChildAs(396    group: *Group,397    process_io: std.Io,398    grace_ms: u64,399    status: GroupStatus,400) !GroupReceipt {401    sys.process.requestTermination(&group.child, process_io);402    const deadline = deadlineNanoseconds(sys.time.nanoTimestamp(), grace_ms);403    while (sys.time.nanoTimestamp() < deadline) {404        if (try pollGroup(group)) |_| {405            return groupReceipt(group, status, true, false);406        }407        sys.time.sleepMilliseconds(wait_poll_ms);408    }409    sys.process.killAndReap(&group.child, process_io);410    return groupReceipt(group, status, true, true);411}412413fn signalGroup(414    child_id: sys.process.Child.Id,415    signal: sys.process.ChildSignal,416) !bool {417    sys.process.signalChildGroup(child_id, signal) catch |err| switch (err) {418        error.ProcessNotFound => return false,419        else => return err,420    };421    return true;422}423424fn groupReceipt(425    group: *const Group,426    status: GroupStatus,427    terminate_sent: bool,428    kill_sent: bool,429) GroupReceipt {430    const finished_monotonic_ns = sys.time.nanoTimestamp();431    return .{432        .status = status,433        .isolation = group.isolation,434        .pid = @intCast(group.child_id),435        .term = group.term,436        .elapsed_ns = @intCast(@max(437            finished_monotonic_ns - group.started_monotonic_ns,438            0,439        )),440        .terminate_sent = terminate_sent,441        .kill_sent = kill_sent,442    };443}444445fn childProcessGroup() @TypeOf(446    @as(sys.process.SpawnOptions, undefined).pgid,447) {448    return switch (comptime sys.process.childSignalPolicy()) {449        .unsupported => null,450        .linux_syscall, .posix_host => 0,451    };452}453454pub fn runChild(455    allocator: std.mem.Allocator,456    process_io: std.Io,457    base_env: ?*const sys.process.Environ.Map,458    cwd: ?[]const u8,459    argv: []const []const u8,460    artifacts: ArtifactEnv,461    trace_allocations: bool,462    tracy: bool,463    control: BenchControl,464) !Result {465    const stdout_file = try sys.fs.createFile(artifacts.stdout, .{ .truncate = true, .read = true });466    defer sys.fs.closeHandle(stdout_file);467    const stderr_file = try sys.fs.createFile(artifacts.stderr, .{ .truncate = true, .read = true });468    defer sys.fs.closeHandle(stderr_file);469    try resetArtifact(artifacts.bench_jsonl);470    try resetArtifact(artifacts.coz_jsonl);471    try resetArtifact(artifacts.coz_analysis);472    try resetArtifact(artifacts.tracy_jsonl);473    try resetArtifact(artifacts.tracy_summary);474    try resetArtifact(artifacts.allocations);475476    var env = if (base_env) |actual| try actual.clone(allocator) else null;477    defer if (env) |*actual| actual.deinit();478    if (env) |*actual| {479        try putArtifactEnv(actual, artifacts, trace_allocations, tracy, control);480    }481482    const start = sys.time.nanoTimestamp();483    var child = sys.process.spawn(process_io, .{484        .argv = argv,485        .environ_map = if (env) |*actual| actual else null,486        .cwd = if (cwd) |path| .{ .path = path } else .inherit,487        .stdin = .inherit,488        .stdout = .{ .file = stdout_file },489        .stderr = .{ .file = stderr_file },490        .request_resource_usage_statistics = false,491    }) catch |err| {492        try writeSpawnFailure(stderr_file, err);493        return spawnFailureResult(start, err);494    };495    errdefer sys.process.killAndReap(&child, process_io);496    const pid: u64 = @intCast(child.id orelse return error.MissingChildProcessId);497    return try awaitChild(process_io, &child, start, pid);498}499500pub fn runCommand(501    process_io: std.Io,502    base_env: ?*const sys.process.Environ.Map,503    cwd: ?[]const u8,504    argv: []const []const u8,505    stdout_path: []const u8,506    stderr_path: []const u8,507) !Result {508    const stdout_file = try sys.fs.createFile(stdout_path, .{ .truncate = true, .read = true });509    defer sys.fs.closeHandle(stdout_file);510    const stderr_file = try sys.fs.createFile(stderr_path, .{ .truncate = true, .read = true });511    defer sys.fs.closeHandle(stderr_file);512513    const start = sys.time.nanoTimestamp();514    var child = sys.process.spawn(process_io, .{515        .argv = argv,516        .environ_map = base_env,517        .cwd = if (cwd) |path| .{ .path = path } else .inherit,518        .stdin = .inherit,519        .stdout = .{ .file = stdout_file },520        .stderr = .{ .file = stderr_file },521        .request_resource_usage_statistics = false,522    }) catch |err| {523        try writeSpawnFailure(stderr_file, err);524        return spawnFailureResult(start, err);525    };526    errdefer sys.process.killAndReap(&child, process_io);527    const pid: u64 = @intCast(child.id orelse return error.MissingChildProcessId);528    return try awaitChild(process_io, &child, start, pid);529}530531pub fn runRecordedCommand(532    allocator: std.mem.Allocator,533    process_io: std.Io,534    base_env: ?*const sys.process.Environ.Map,535    cwd: ?[]const u8,536    argv: []const []const u8,537    stdout_path: []const u8,538    stderr_path: []const u8,539) !CommandResult {540    return .{541        .command = try commandText(allocator, cwd, null, argv),542        .argv = argv,543        .cwd = cwd,544        .stdout_path = stdout_path,545        .stderr_path = stderr_path,546        .execution = try runCommand(547            process_io,548            base_env,549            cwd,550            argv,551            stdout_path,552            stderr_path,553        ),554    };555}556557fn awaitChild(558    process_io: std.Io,559    child: *sys.process.Child,560    start: i128,561    pid: u64,562) !Result {563    if (child.id) |child_pid| {564        while (true) {565            const outcome = try sys.process.waitNoHang(child_pid);566            if (outcome) |finished| {567                child.id = null;568                return resultFromTerm(start, pid, finished.term, finished.usage);569            }570            sys.time.sleepMilliseconds(wait_poll_ms);571        }572    }573574    const term = try sys.process.wait(child, process_io);575    return resultFromTerm(start, pid, term, .{});576}577578pub fn putArtifactEnv(579    env: *sys.process.Environ.Map,580    artifacts: ArtifactEnv,581    trace_allocations: bool,582    tracy: bool,583    control: BenchControl,584) !void {585    try env.put("BENCH_JSONL", artifacts.bench_jsonl);586    try env.put("BENCH_COZ_JSONL", artifacts.coz_jsonl);587    try env.put("BENCH_COZ_ANALYSIS_JSON", artifacts.coz_analysis);588    try putOrScrub(env, "BENCH_TRACY_JSONL", if (tracy) artifacts.tracy_jsonl else null);589    try putOrScrub(env, "BENCH_TRACY_SUMMARY_JSONL", if (tracy) artifacts.tracy_summary else null);590    try putOrScrub(env, "TINY_PROFILE_ALLOCATIONS_PATH", if (trace_allocations) artifacts.allocations else null);591    try putOrScrub(env, "BENCH_COZ_EXPERIMENTS", if (control.causal) "1" else null);592    var min_time_buffer: [20]u8 = undefined;593    const min_time_text: ?[]const u8 = if (control.min_time_ns) |ns|594        std.fmt.bufPrint(&min_time_buffer, "{d}", .{ns}) catch unreachable595    else596        null;597    try putOrScrub(env, "BENCH_MIN_TIME_NS", min_time_text);598    try putOrScrub(env, "BENCH_FILTER", control.filter);599}600601fn putOrScrub(env: *sys.process.Environ.Map, key: []const u8, value: ?[]const u8) !void {602    if (value) |actual| {603        try env.put(key, actual);604    } else {605        _ = env.swapRemove(key);606    }607}608609fn resetArtifact(path: []const u8) !void {610    const file = try sys.fs.createFile(path, .{ .truncate = true });611    sys.fs.closeHandle(file);612}613614fn resultFromTerm(615    start_ns: i128,616    pid: ?u64,617    term: sys.process.Termination,618    usage: sys.process.ResourceUsage,619) Result {620    const end_ns = sys.time.nanoTimestamp();621    const wall_ns: u64 = @intCast(@max(end_ns - start_ns, 0));622    return .{623        .pid = pid,624        .exit_code = sys.process.exitCode(term),625        .wall_ns = wall_ns,626        .resource_usage_source = usage.source,627        .maxrss_kib = usage.maxrss_kib,628        .user_s = usage.user_s,629        .system_s = usage.system_s,630        .minor_page_faults = usage.minor_page_faults,631        .major_page_faults = usage.major_page_faults,632        .voluntary_context_switches = usage.voluntary_context_switches,633        .involuntary_context_switches = usage.involuntary_context_switches,634    };635}636637fn writeSpawnFailure(file: std.Io.File, err: anyerror) !void {638    var buffer: [256]u8 = undefined;639    var writer = file.writer(sys.fs.debugIo(), &buffer);640    try writer.interface.print("spawn failed: {s}\n", .{@errorName(err)});641    try writer.interface.flush();642}643644fn spawnFailureResult(start_ns: i128, err: anyerror) Result {645    const end_ns = sys.time.nanoTimestamp();646    return .{647        .exit_code = spawnFailureExitCode(err),648        .wall_ns = @intCast(@max(end_ns - start_ns, 0)),649    };650}651652fn spawnFailureExitCode(err: anyerror) i64 {653    return switch (err) {654        error.AccessDenied => 126,655        else => 127,656    };657}658659test "profiling execution builds child argv with forwarded args only when supported" {660    const allocator = std.testing.allocator;661    const forwarded = &.{ "--test-filter", "x" };662663    const with_forwarding = try childArgv(664        allocator,665        test_zig,666        catalog.find("choir.compiler").?,667        forwarded,668        &.{"-Doptimize=fast"},669    );670    defer allocator.free(with_forwarding);671    try std.testing.expectEqualSlices(672        []const u8,673        &.{674            "zig",675            "build",676            "-fno-incremental",677            "choir-compiler-bench",678            "-Doptimize=fast",679            retain_root_symbols_args[0],680            retain_root_symbols_args[1],681            "--",682            "--test-filter",683            "x",684        },685        with_forwarding,686    );687688    const without_forwarding = try childArgv(689        allocator,690        test_zig,691        catalog.find("gpalloc.allocator").?,692        forwarded,693        &.{"-Doptimize=fast"},694    );695    defer allocator.free(without_forwarding);696    try std.testing.expectEqualSlices(697        []const u8,698        &.{699            "zig",700            "build",701            "-fno-incremental",702            "gpalloc-bench",703            "-Doptimize=fast",704            retain_root_symbols_args[0],705            retain_root_symbols_args[1],706        },707        without_forwarding,708    );709}710711test "profiling execution resolves the invoking Zig build command from the environment" {712    const allocator = std.testing.allocator;713    var env = sys.process.Environ.Map.init(allocator);714    defer env.deinit();715716    try std.testing.expectEqualStrings("zig", zig(null).executable);717    try std.testing.expectEqualStrings("zig", zig(&env).executable);718    try env.put(zig_env_var, "/opt/zig/zig");719    try std.testing.expectEqualStrings("/opt/zig/zig", zig(&env).executable);720721    const argv = try childArgv(722        allocator,723        zig(&env),724        catalog.find("gpalloc.allocator").?,725        &.{},726        &.{"-Doptimize=fast"},727    );728    defer allocator.free(argv);729    try std.testing.expectEqualStrings("/opt/zig/zig", argv[0]);730    try std.testing.expectEqualStrings("-fno-incremental", argv[2]);731}732733test "profiling execution formats cwd commands" {734    const allocator = std.testing.allocator;735    const workload = catalog.find("gpalloc.driver").?;736    const argv = try childArgv(737        allocator,738        test_zig,739        workload,740        &.{},741        &.{"-Doptimize=safe"},742    );743    defer allocator.free(argv);744    const text = try commandText(allocator, workload.cwd, null, argv);745    defer allocator.free(text);746    try std.testing.expectEqualStrings(747        "(cd lib/gpalloc && zig build -fno-incremental bench-driver -Doptimize=safe)",748        text,749    );750}751752test "profiling execution gives package build options only to package-scoped builds" {753    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);754    defer arena_state.deinit();755    const arena = arena_state.allocator();756    const opt_in = catalog.find("tldr.linker").?;757    try std.testing.expectEqualSlices([]const u8, &.{"-Dprofiling=true"}, opt_in.package_build_options);758759    const root_step = try plan(arena, test_zig, opt_in, &.{}, false, &.{"-Doptimize=fast"});760    try std.testing.expect(root_step.cwd == null);761    try std.testing.expectEqualSlices(762        []const u8,763        &.{764            "zig",765            "build",766            "-fno-incremental",767            "tldr-bench",768            "-Doptimize=fast",769            retain_root_symbols_args[0],770            retain_root_symbols_args[1],771        },772        root_step.argv,773    );774775    const direct = try plan(arena, test_zig, opt_in, &.{}, true, &.{"-Doptimize=fast"});776    try std.testing.expectEqualStrings("lib/tldr", direct.cwd.?);777    try std.testing.expectEqualSlices(778        []const u8,779        &.{ "zig", "build", "-fno-incremental", "bench-bin", "-Doptimize=fast", "-Dprofiling=true" },780        direct.setup_argv.?,781    );782783    const default = catalog.find("gpalloc.allocator").?;784    try std.testing.expectEqual(@as(usize, 0), default.package_build_options.len);785    const default_direct = try plan(arena, test_zig, default, &.{}, true, &.{"-Doptimize=fast"});786    try std.testing.expectEqualStrings("lib/gpalloc", default_direct.cwd.?);787    try std.testing.expectEqualSlices(788        []const u8,789        &.{ "zig", "build", "-fno-incremental", "bench-bin", "-Doptimize=fast" },790        default_direct.setup_argv.?,791    );792793    var local = opt_in;794    local.bin = null;795    local.cwd = opt_in.package;796    local.step = opt_in.localStep();797    const local_step = try plan(arena, test_zig, local, &.{}, false, &.{});798    try std.testing.expectEqualSlices(799        []const u8,800        &.{ "zig", "build", "-fno-incremental", "bench", "-Dprofiling=true" },801        local_step.argv,802    );803}804805test "profiling execution scope parses user names" {806    try std.testing.expectEqual(Scope.step, Scope.parse("step").?);807    try std.testing.expectEqual(Scope.binary, Scope.parse("binary").?);808    try std.testing.expectEqual(Scope.mixed, Scope.parse("mixed").?);809    try std.testing.expect(Scope.parse("whole-step") == null);810    const ordinary_binary = catalog.find("mprompt.smoke").?;811    const ordinary_step = catalog.find("choir.versus").?;812    const configured = catalog.Workload{813        .name = "configured",814        .package = "fixture",815        .step = "fixture-test",816        .summary = "direct execution fixture",817        .tier = .smoke,818        .surface = .benchmark,819        .environment = &.{.{ .name = "FIXTURE_DIRECT", .value = "1" }},820    };821    try std.testing.expect(!Scope.step.directFor(ordinary_binary));822    try std.testing.expect(Scope.binary.directFor(ordinary_binary));823    try std.testing.expect(!Scope.mixed.directFor(ordinary_binary));824    try std.testing.expect(!Scope.mixed.directFor(ordinary_step));825    try std.testing.expect(Scope.mixed.directFor(configured));826    try std.testing.expectEqualStrings(827        "-Doptimize=small",828        optimizeBuildArg(.small),829    );830}831832test "profiling execution formats setup phases into command text" {833    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);834    defer arena_state.deinit();835    const allocator = arena_state.allocator();836    const setup = [_][]const u8{ "zig", "build", "-fno-incremental", "bench-bin" };837    const argv = [_][]const u8{ "zig-out/bin/mprompt-bench", "--workers", "128" };838    const text = try commandText(allocator, "lib/mprompt", &setup, &argv);839    try std.testing.expectEqualStrings("(cd lib/mprompt && zig build -fno-incremental bench-bin && zig-out/bin/mprompt-bench --workers 128)", text);840}841842test "profiling execution plans direct workloads through their binaries" {843    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);844    defer arena_state.deinit();845    const allocator = arena_state.allocator();846    const workload = catalog.Workload{847        .name = "example.bench",848        .package = "lib/example",849        .step = "example-bench",850        .summary = "example",851        .tier = .smoke,852        .surface = .benchmark,853        .forwards_args = true,854        .bin = .{ .path = "zig-out/bin/example-bench", .args = &.{"--count"} },855    };856857    const direct = try plan(858        allocator,859        .{ .executable = "/opt/zig/zig" },860        workload,861        &.{},862        true,863        &.{ "-Doptimize=fast", "-Dcpu=x86_64_v3" },864    );865    try std.testing.expect(direct.direct);866    try std.testing.expect(!direct.missing_bin);867    try std.testing.expectEqualStrings("lib/example", direct.cwd.?);868    try std.testing.expectEqualSlices(869        []const u8,870        &.{871            "/opt/zig/zig",872            "build",873            "-fno-incremental",874            "bench-bin",875            "-Doptimize=fast",876            "-Dcpu=x86_64_v3",877        },878        direct.setup_argv.?,879    );880    try std.testing.expectEqualSlices([]const u8, &.{ "zig-out/bin/example-bench", "--count" }, direct.argv);881882    const forwarded = try plan(allocator, test_zig, workload, &.{"--fast"}, true, &.{});883    try std.testing.expectEqualSlices([]const u8, &.{ "zig-out/bin/example-bench", "--count", "--fast" }, forwarded.argv);884885    const whole_step = try plan(886        allocator,887        test_zig,888        workload,889        &.{},890        false,891        &.{"-Doptimize=fast"},892    );893    try std.testing.expect(!whole_step.direct);894    try std.testing.expect(whole_step.setup_argv == null);895    try std.testing.expectEqualSlices(896        []const u8,897        &.{898            "zig",899            "build",900            "-fno-incremental",901            "example-bench",902            "-Doptimize=fast",903            retain_root_symbols_args[0],904            retain_root_symbols_args[1],905        },906        whole_step.argv,907    );908}909910test "profiling execution plans root-scoped binaries at the repository root" {911    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);912    defer arena_state.deinit();913    const allocator = arena_state.allocator();914    const workload = catalog.Workload{915        .name = "example.rooted",916        .package = "lib/example",917        .step = "example-bench",918        .summary = "example",919        .tier = .smoke,920        .surface = .benchmark,921        .bin = .{ .step = "example-bench-bin", .path = "zig-out/bin/example-bench", .cwd = "." },922    };923    const direct = try plan(924        allocator,925        test_zig,926        workload,927        &.{},928        true,929        &.{"-Doptimize=small"},930    );931    try std.testing.expect(direct.direct);932    try std.testing.expect(direct.cwd == null);933    try std.testing.expectEqualSlices(934        []const u8,935        &.{936            "zig",937            "build",938            "-fno-incremental",939            "example-bench-bin",940            "-Doptimize=small",941            retain_root_symbols_args[0],942            retain_root_symbols_args[1],943        },944        direct.setup_argv.?,945    );946    try std.testing.expectEqualSlices([]const u8, &.{"zig-out/bin/example-bench"}, direct.argv);947}948949test "profiling execution marks direct plans without binaries" {950    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);951    defer arena_state.deinit();952    const allocator = arena_state.allocator();953    const workload = catalog.Workload{954        .name = "example.nobin",955        .package = "lib/example",956        .step = "example-bench",957        .summary = "example",958        .tier = .smoke,959        .surface = .benchmark,960    };961    const planned = try plan(962        allocator,963        test_zig,964        workload,965        &.{},966        true,967        &.{"-Doptimize=fast"},968    );969    try std.testing.expect(planned.missing_bin);970    try std.testing.expect(!planned.direct);971    try std.testing.expect(planned.setup_argv == null);972    try std.testing.expectEqualSlices(973        []const u8,974        &.{975            "zig",976            "build",977            "-fno-incremental",978            "example-bench",979            "-Doptimize=fast",980            retain_root_symbols_args[0],981            retain_root_symbols_args[1],982        },983        planned.argv,984    );985}986987test "profiling execution only exports requested in-process trace paths" {988    const allocator = std.testing.allocator;989    const artifacts = ArtifactEnv{990        .stdout = "stdout.txt",991        .stderr = "stderr.txt",992        .bench_jsonl = "bench.jsonl",993        .coz_jsonl = "bench.coz.jsonl",994        .coz_analysis = "bench.coz.analysis.json",995        .tracy_jsonl = "bench.tracy.jsonl",996        .tracy_summary = "bench.tracy.summary.jsonl",997        .allocations = "allocations.jsonl",998    };9991000    var default_env = sys.process.Environ.Map.init(allocator);1001    defer default_env.deinit();1002    try putArtifactEnv(&default_env, artifacts, false, false, .{});1003    try std.testing.expect(default_env.get("BENCH_COZ_EXPERIMENTS") == null);1004    try std.testing.expectEqualStrings("bench.jsonl", default_env.get("BENCH_JSONL").?);1005    try std.testing.expect(default_env.get("BENCH_TRACY_JSONL") == null);1006    try std.testing.expect(default_env.get("TINY_PROFILE_ALLOCATIONS_PATH") == null);10071008    var trace_env = sys.process.Environ.Map.init(allocator);1009    defer trace_env.deinit();1010    try putArtifactEnv(&trace_env, artifacts, true, true, .{ .causal = true });1011    try std.testing.expectEqualStrings("1", trace_env.get("BENCH_COZ_EXPERIMENTS").?);1012    try std.testing.expectEqualStrings("allocations.jsonl", trace_env.get("TINY_PROFILE_ALLOCATIONS_PATH").?);1013    try std.testing.expectEqualStrings("bench.tracy.jsonl", trace_env.get("BENCH_TRACY_JSONL").?);1014    try std.testing.expectEqualStrings("bench.tracy.summary.jsonl", trace_env.get("BENCH_TRACY_SUMMARY_JSONL").?);1015    try std.testing.expect(trace_env.get("BENCH_MIN_TIME_NS") == null);1016    try std.testing.expect(trace_env.get("BENCH_FILTER") == null);1017}10181019test "profiling execution exports benchmark controls" {1020    const allocator = std.testing.allocator;1021    const artifacts = ArtifactEnv{1022        .stdout = "stdout.txt",1023        .stderr = "stderr.txt",1024        .bench_jsonl = "bench.jsonl",1025        .coz_jsonl = "bench.coz.jsonl",1026        .coz_analysis = "bench.coz.analysis.json",1027        .tracy_jsonl = "bench.tracy.jsonl",1028        .tracy_summary = "bench.tracy.summary.jsonl",1029        .allocations = "allocations.jsonl",1030    };10311032    var env = sys.process.Environ.Map.init(allocator);1033    defer env.deinit();1034    try putArtifactEnv(&env, artifacts, false, false, .{1035        .causal = true,1036        .min_time_ns = 30_000_000_000,1037        .filter = "small alloc",1038    });1039    try std.testing.expectEqualStrings("1", env.get("BENCH_COZ_EXPERIMENTS").?);1040    try std.testing.expectEqualStrings("30000000000", env.get("BENCH_MIN_TIME_NS").?);1041    try std.testing.expectEqualStrings("small alloc", env.get("BENCH_FILTER").?);1042}10431044test "profiling execution scrubs stale bench control variables from the parent" {1045    const allocator = std.testing.allocator;1046    const artifacts = ArtifactEnv{1047        .stdout = "stdout.txt",1048        .stderr = "stderr.txt",1049        .bench_jsonl = "bench.jsonl",1050        .coz_jsonl = "bench.coz.jsonl",1051        .coz_analysis = "bench.coz.analysis.json",1052        .tracy_jsonl = "bench.tracy.jsonl",1053        .tracy_summary = "bench.tracy.summary.jsonl",1054        .allocations = "allocations.jsonl",1055    };10561057    var env = sys.process.Environ.Map.init(allocator);1058    defer env.deinit();1059    try env.put("BENCH_COZ_EXPERIMENTS", "1");1060    try env.put("BENCH_MIN_TIME_NS", "30000000000");1061    try env.put("BENCH_FILTER", "small alloc");1062    try env.put("BENCH_TRACY_JSONL", "stale.tracy.jsonl");1063    try env.put("BENCH_TRACY_SUMMARY_JSONL", "stale.tracy.summary.jsonl");1064    try env.put("TINY_PROFILE_ALLOCATIONS_PATH", "stale.jsonl");10651066    try putArtifactEnv(&env, artifacts, false, false, .{});1067    try std.testing.expect(env.get("BENCH_COZ_EXPERIMENTS") == null);1068    try std.testing.expect(env.get("BENCH_MIN_TIME_NS") == null);1069    try std.testing.expect(env.get("BENCH_FILTER") == null);1070    try std.testing.expect(env.get("BENCH_TRACY_JSONL") == null);1071    try std.testing.expect(env.get("BENCH_TRACY_SUMMARY_JSONL") == null);1072    try std.testing.expect(env.get("TINY_PROFILE_ALLOCATIONS_PATH") == null);1073}10741075test "profiling execution applies bounded set and unset child environment overrides" {1076    const allocator = std.testing.allocator;1077    var parent = sys.process.Environ.Map.init(allocator);1078    defer parent.deinit();1079    try parent.put("HOME", "/parent");1080    try parent.put("FIXTURE_OBSERVATION_PATH", "/stale");1081    try parent.put("KEPT", "yes");10821083    var child = try environmentWithOverrides(allocator, &parent, &.{1084        .{ .name = "HOME", .value = "/fixture" },1085        .{ .name = "FIXTURE_OBSERVATION_PATH" },1086    });1087    defer child.deinit();1088    try std.testing.expectEqualStrings("/fixture", child.get("HOME").?);1089    try std.testing.expect(child.get("FIXTURE_OBSERVATION_PATH") == null);1090    try std.testing.expectEqualStrings("yes", child.get("KEPT").?);1091    try std.testing.expectEqualStrings("/parent", parent.get("HOME").?);1092    try std.testing.expectEqualStrings(1093        "/stale",1094        parent.get("FIXTURE_OBSERVATION_PATH").?,1095    );1096}10971098test "profiling execution records child spawn failures" {1099    var tmp = std.testing.tmpDir(.{});1100    defer tmp.cleanup();1101    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1102    defer arena_state.deinit();1103    const allocator = arena_state.allocator();1104    const root = try std.fs.path.join(allocator, &.{ ".zig-cache", "tmp", tmp.sub_path[0..] });1105    const artifacts = ArtifactEnv{1106        .stdout = try std.fs.path.join(allocator, &.{ root, "stdout.txt" }),1107        .stderr = try std.fs.path.join(allocator, &.{ root, "stderr.txt" }),1108        .bench_jsonl = try std.fs.path.join(allocator, &.{ root, "bench.jsonl" }),1109        .coz_jsonl = try std.fs.path.join(allocator, &.{ root, "bench.coz.jsonl" }),1110        .coz_analysis = try std.fs.path.join(allocator, &.{ root, "bench.coz.analysis.json" }),1111        .tracy_jsonl = try std.fs.path.join(allocator, &.{ root, "bench.tracy.jsonl" }),1112        .tracy_summary = try std.fs.path.join(allocator, &.{ root, "bench.tracy.summary.jsonl" }),1113        .allocations = try std.fs.path.join(allocator, &.{ root, "allocations.jsonl" }),1114    };1115    const result = try runChild(1116        allocator,1117        std.testing.io,1118        null,1119        null,1120        &.{"definitely-missing-tiny-profile-child"},1121        artifacts,1122        false,1123        false,1124        .{},1125    );1126    try std.testing.expectEqual(@as(i64, 127), result.exit_code);1127    try std.testing.expect(result.pid == null);1128    const stderr = try sys.fs.readFileAlloc(allocator, artifacts.stderr, 4096);1129    try std.testing.expect(std.mem.indexOf(u8, stderr, "spawn failed:") != null);1130}11311132test "profiling execution records the waited child PID" {1133    var tmp = std.testing.tmpDir(.{});1134    defer tmp.cleanup();1135    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);1136    defer arena_state.deinit();1137    const allocator = arena_state.allocator();1138    const root = try tmp.parent_dir.realPathFileAlloc(1139        std.testing.io,1140        tmp.sub_path[0..],1141        allocator,1142    );1143    const stdout_path = try std.fs.path.join(allocator, &.{ root, "stdout.txt" });1144    const stderr_path = try std.fs.path.join(allocator, &.{ root, "stderr.txt" });1145    const execution = try runCommand(1146        std.testing.io,1147        null,1148        null,1149        &.{"/bin/true"},1150        stdout_path,1151        stderr_path,1152    );1153    try std.testing.expect((execution.pid orelse 0) > 0);1154    try std.testing.expectEqual(@as(i64, 0), execution.exit_code);1155}11561157test "profiling execution result retains an explicit process identity" {1158    const result = resultFromTerm(1159        0,1160        42,1161        .{ .exited = 0 },1162        .{},1163    );1164    try std.testing.expectEqual(@as(?u64, 42), result.pid);1165}11661167test "profiling execution returns a completed process group receipt" {1168    var group = try spawnGroup(std.testing.io, .{1169        .argv = &.{"/bin/true"},1170        .stdin = .ignore,1171        .stdout = .ignore,1172        .stderr = .ignore,1173    });1174    const receipt = try awaitGroupUntil(1175        &group,1176        std.testing.io,1177        deadlineNanoseconds(sys.time.nanoTimestamp(), 1_000),1178        10,1179    );1180    try std.testing.expectEqual(GroupStatus.exited, receipt.status);1181    try std.testing.expectEqual(GroupIsolation.process_group, receipt.isolation);1182    try std.testing.expectEqual(@as(i64, 0), sys.process.exitCode(receipt.term.?));1183    try std.testing.expect(!receipt.terminate_sent);1184    try std.testing.expect(!receipt.kill_sent);1185    try expectProcessGone(@intCast(receipt.pid));1186}11871188test "profiling execution times out and reaps its process group" {1189    var group = try spawnGroup(std.testing.io, .{1190        .argv = &.{ "/bin/sh", "-c", "trap '' TERM; while :; do :; done" },1191        .stdin = .ignore,1192        .stdout = .ignore,1193        .stderr = .ignore,1194    });1195    const receipt = try awaitGroupUntil(1196        &group,1197        std.testing.io,1198        deadlineNanoseconds(sys.time.nanoTimestamp(), 20),1199        10,1200    );1201    try std.testing.expectEqual(GroupStatus.timed_out, receipt.status);1202    try std.testing.expectEqual(GroupIsolation.process_group, receipt.isolation);1203    try std.testing.expect(receipt.terminate_sent);1204    try std.testing.expect(receipt.kill_sent);1205    try std.testing.expect(receipt.term != null);1206    try expectProcessGone(@intCast(receipt.pid));1207}12081209test "profiling execution timeout stops a resistant descendant" {1210    var tmp = std.testing.tmpDir(.{});1211    defer tmp.cleanup();1212    const allocator = std.testing.allocator;1213    const root = try tmp.parent_dir.realPathFileAlloc(1214        std.testing.io,1215        tmp.sub_path[0..],1216        allocator,1217    );1218    defer allocator.free(root);1219    const pid_path = try std.fs.path.join(allocator, &.{ root, "descendant.pid" });1220    defer allocator.free(pid_path);1221    var group = try spawnGroup(std.testing.io, .{1222        .argv = &.{1223            "/bin/sh",1224            "-c",1225            "trap '' TERM; /bin/sh -c \"trap '' TERM; while :; do :; done\" & " ++1226                "echo $! > \"$1\"; wait",1227            "tiny-process-group-fixture",1228            pid_path,1229        },1230        .stdin = .ignore,1231        .stdout = .ignore,1232        .stderr = .ignore,1233    });1234    defer if (group.active()) {1235        _ = stopGroup(&group, std.testing.io, 10) catch {};1236    };1237    try waitForPath(pid_path);1238    const receipt = try awaitGroupUntil(1239        &group,1240        std.testing.io,1241        deadlineNanoseconds(sys.time.nanoTimestamp(), 20),1242        20,1243    );1244    try std.testing.expectEqual(GroupStatus.timed_out, receipt.status);1245    try std.testing.expect(receipt.kill_sent);1246    const pid_text = try sys.fs.readFileAlloc(allocator, pid_path, 64);1247    defer allocator.free(pid_text);1248    const descendant_pid = try std.fmt.parseInt(1249        sys.process.ProcessId,1250        std.mem.trim(u8, pid_text, " \t\r\n"),1251        10,1252    );1253    try expectProcessExited(descendant_pid);1254    try expectProcessGone(@intCast(receipt.pid));1255}12561257/// An orphan's adopting supervisor owns reaping its zombie entry.1258fn expectProcessExited(process_id: sys.process.ProcessId) !void {1259    std.debug.assert(process_id > 0);1260    for (0..100) |_| {1261        const observed = sys.process.inspect.info(process_id) catch |err| switch (err) {1262            error.ProcessNotFound => return,1263            else => return err,1264        };1265        if (!observed.alive) return;1266        sys.time.sleepMilliseconds(5);1267    }1268    return error.TestExpectedProcessExit;1269}12701271fn waitForPath(path: []const u8) !void {1272    std.debug.assert(path.len != 0);1273    var attempt: u8 = 0;1274    while (attempt < 200) : (attempt += 1) {1275        if (sys.fs.exists(path)) return;1276        sys.time.sleepMilliseconds(5);1277    }1278    return error.ProcessFixtureDidNotStart;1279}12801281fn expectProcessGone(process_id: sys.process.ProcessId) !void {1282    std.debug.assert(process_id > 0);1283    var attempt: u8 = 0;1284    while (attempt < 100) : (attempt += 1) {1285        if (!try sys.process.processAlive(process_id)) return;1286        sys.time.sleepMilliseconds(5);1287    }1288    try std.testing.expect(false);1289}

1pub const execute = @import("execute.zig");