性能分析、优化与加固

// 此程序演示使用Zig内置计时器进行性能测量和比较不同排序算法。
const std = @import("std");

// 每个基准运行中要排序的元素数量
const sample_count = 1024;

/// 为基准测试生成确定性随机u32值数组。
/// 使用固定种子确保跨多次运行的结果可重现。
/// @return: 1024个伪随机u32值的数组
fn generateData() [sample_count]u32 {
    var data: [sample_count]u32 = undefined;
    // 用固定种子初始化PRNG以生成确定性输出
    var prng = std.Random.DefaultPrng.init(0xfeed_beef_dead_cafe);
    var random = prng.random();
    // 用随机32位无符号整数填充每个数组槽
    for (&data) |*slot| {
        slot.* = random.int(u32);
    }
    return data;
}

/// 测量排序函数在输入数据副本上的执行时间。
/// 创建临时缓冲区以避免修改原始数据，允许
/// 对同一数据集进行多次测量。
/// @param sortFn: 要基准测试的编译时排序函数
/// @param source: 要排序的源数据（保持不变）
/// @return: 以纳秒为单位的经过时间
fn measureSort(
    comptime sortFn: anytype,
    source: []const u32,
) !u64 {
    // 创建临时缓冲区以保留原始数据
    var scratch: [sample_count]u32 = undefined;
    std.mem.copyForwards(u32, scratch[0..], source);

    // 在排序操作前立即启动高分辨率计时器
    var timer = try std.time.Timer.start();
    // 使用升序比较函数执行排序
    sortFn(u32, scratch[0..], {}, std.sort.asc(u32));
    // 捕获经过的纳秒数
    return timer.read();
}

pub fn main() !void {
    // 为所有排序算法生成共享数据集
    var dataset = generateData();

    // 在相同数据上对每个排序算法进行基准测试
    const block_ns = try measureSort(std.sort.block, dataset[0..]);
    const heap_ns = try measureSort(std.sort.heap, dataset[0..]);
    const insertion_ns = try measureSort(std.sort.insertion, dataset[0..]);

    // 显示原始计时结果以及构建模式
    std.debug.print("optimize-mode={s}\n", .{@tagName(@import("builtin").mode)});
    std.debug.print("block sort     : {d} ns\n", .{block_ns});
    std.debug.print("heap sort      : {d} ns\n", .{heap_ns});
    std.debug.print("insertion sort : {d} ns\n", .{insertion_ns});

    // 使用块排序作为基线计算相对性能指标
    const baseline = @as(f64, @floatFromInt(block_ns));
    const heap_speedup = baseline / @as(f64, @floatFromInt(heap_ns));
    const insertion_slowdown = @as(f64, @floatFromInt(insertion_ns)) / baseline;

    // 显示显示加速/减速因子的比较分析
    std.debug.print("heap speedup over block: {d:.2}x\n", .{heap_speedup});
    std.debug.print("insertion slowdown vs block: {d:.2}x\n", .{insertion_slowdown});
}

// 此程序演示了编译时配置如何影响二进制文件大小
// 通过根据构建模式有条件地启用调试跟踪。
const std = @import("std");
const builtin = @import("builtin");

// 编译时标志，仅在 Debug 模式下启用跟踪
// 这演示了死代码消除在发布构建中的工作方式
const enable_tracing = builtin.mode == .Debug;

// 计算给定单词的 FNV-1a 哈希值
// FNV-1a 是一种快速、非密码学的哈希函数
// @param word: 要哈希的输入字节切片
// @return: 64 位哈希值
fn checksumWord(word: []const u8) u64 {
    // FNV-1a 64 位偏移基数
    var state: u64 = 0xcbf29ce484222325;

    // 处理输入的每个字节
    for (word) |byte| {
        // 与当前字节进行异或
        state ^= byte;
        // 乘以 FNV-1a 64 位素数（带环绕乘法）
        state = state *% 0x100000001b3;
    }
    return state;
}

pub fn main() !void {
    // 示例单词列表以演示校验和功能
    const words = [_][]const u8{ "profiling", "optimization", "hardening", "zig" };

    // 组合所有单词校验和的累加器
    var digest: u64 = 0;

    // 处理每个单词并组合其校验和
    for (words) |word| {
        const word_sum = checksumWord(word);
        // 使用 XOR 组合校验和
        digest ^= word_sum;

        // 条件跟踪，将在发布构建中编译掉
        // 这演示了构建模式如何影响二进制文件大小
        if (enable_tracing) {
            std.debug.print("trace: {s} -> {x}\n", .{ word, word_sum });
        }
    }

    // 输出最终结果以及当前构建模式
    // 展示了相同的代码如何根据编译设置表现不同
    std.debug.print(
        "mode={s} digest={x}\n",
        .{
            @tagName(builtin.mode),
            digest,
        },
    );
}

// 此示例演示了 Zig 中的输入验证和错误处理模式，
// 展示了如何创建带有正确边界检查的受控数据处理管道。

const std = @import("std");

// 用于解析和验证操作的自定义错误集
const ParseError = error{
    EmptyInput, // 当输入仅包含空白或为空时返回
    InvalidNumber, // 当输入无法解析为有效数字时返回
    OutOfRange, // 当解析值超出可接受范围时返回
};

// / 将文本输入解析并验证为 u32 限制值。
// / 确保值在 1 到 10,000 之间（含）。
// / 输入中的空白会自动去除。
fn parseLimit(text: []const u8) ParseError!u32 {
    // 移除前导和尾随的空白字符
    const trimmed = std.mem.trim(u8, text, " \t\r\n");
    if (trimmed.len == 0) return error.EmptyInput;

    // 尝试解析为基数为 10 的无符号 32 位整数
    const value = std.fmt.parseInt(u32, trimmed, 10) catch return error.InvalidNumber;

    // 强制边界：拒绝零值和超出最大阈值的值
    if (value == 0 or value > 10_000) return error.OutOfRange;
    return value;
}

// / 对工作队列应用节流限制，确保安全的处理边界。
// / 返回可处理的实际项目数，即请求限制和可用工作长度的最小值。
fn throttle(work: []const u8, limit: u32) ParseError!usize {
    // 前置条件：限制必须为正数（在调试构建中在运行时强制执行）
    std.debug.assert(limit > 0);

    // 防止空工作队列
    if (work.len == 0) return error.EmptyInput;

    // 通过取请求限制和工作大小的最小值来计算安全处理限制
    // 转换是安全的，因为我们取的是最小值
    const safe_limit = @min(limit, @as(u32, @intCast(work.len)));
    return safe_limit;
}

// 测试：验证有效的数字字符串是否正确解析
test "valid limit parses" {
    try std.testing.expectEqual(@as(u32, 750), try parseLimit("750"));
}

// 测试：确保仅包含空白的输入被正确拒绝
test "empty input rejected" {
    try std.testing.expectError(error.EmptyInput, parseLimit("   \n"));
}

// 测试：验证节流尊重解析的限制和工作大小
test "in-flight throttling respects guard" {
    const limit = try parseLimit("32");
    // 工作长度 (4) 小于限制 (32)，因此期望工作长度
    try std.testing.expectEqual(@as(usize, 4), try throttle("hard", limit));
}

// 测试：验证多个输入符合最大阈值要求
// 演示编译时迭代以测试多种场景
test "validate release configurations" {
    const inputs = [_][]const u8{ "8", "9999", "500" };
    // 编译时循环展开每个输入值的测试用例
    inline for (inputs) |value| {
        const parsed = try parseLimit(value);
        // 确保解析值永不超过定义的最大值
        try std.testing.expect(parsed <= 10_000);
    }
}