性能与内联

// 此文件演示Zig的内联语义和编译时执行特性。
// 它展示了`inline`关键字和`@call`内置函数如何控制
// 函数在编译时与运行时的评估时机和方式。

const std = @import("std");

// 使用递归计算第n个斐波那契数。
// `inline`关键字强制此函数在所有调用点被内联，
// 而`comptime n`参数确保值可以在编译时计算。
// 这种组合允许结果作为编译时常量可用。
inline fn fib(comptime n: usize) usize {
    return if (n <= 1) n else fib(n - 1) + fib(n - 2);
}

// 使用递归计算n的阶乘。
// 与`fib`不同，此函数未标记为`inline`，因此编译器
// 根据优化启发式算法决定是否内联它。
// 它可以在编译时或运行时调用。
fn factorial(n: usize) usize {
    return if (n <= 1) 1 else n * factorial(n - 1);
}

// 演示具有comptime参数的inline函数
// 将编译时执行传播到其调用点。
// 整个计算在comptime块内的编译时发生。
test "inline fibonacci propagates comptime" {
    comptime {
        const value = fib(10);
        try std.testing.expectEqual(@as(usize, 55), value);
    }
}

// 演示带有`.compile_time`修饰符的`@call`内置函数。
// 这强制函数调用在编译时评估，
// 尽管`factorial`未标记为`inline`且接受非comptime参数。
test "@call compile_time modifier" {
    const result = @call(.compile_time, factorial, .{5});
    try std.testing.expectEqual(@as(usize, 120), result);
}

// 验证非内联函数仍可在运行时调用。
// 输入是运行时值，因此计算在执行期间发生。
test "runtime factorial still works" {
    const input: usize = 6;
    const value = factorial(input);
    try std.testing.expectEqual(@as(usize, 720), value);
}

const std = @import("std");
const builtin = @import("builtin");

// 运行每个基准变体的迭代次数
const iterations: usize = 5_000_000;

// 演示内联性能影响的简单混合函数。
// 使用位旋转和算术运算创建非平凡的工作负载，
// 优化器可能根据调用修饰符以不同方式处理。
fn mix(value: u32) u32 {
    // 与类素数常量异或后左旋7位
    const rotated = std.math.rotl(u32, value ^ 0x9e3779b9, 7);
    // 使用环绕算术应用额外混合以防止编译时求值
    return rotated *% 0x85eb_ca6b +% 0xc2b2_ae35;
}

// 使用指定的调用修饰符在紧循环中运行混合函数。
// 这允许直接比较不同内联策略如何影响性能。
fn run(comptime modifier: std.builtin.CallModifier) u32 {
    var acc: u32 = 0;
    var i: usize = 0;
    while (i < iterations) : (i += 1) {
        // @call内置函数让我们在调用点显式控制内联行为
        acc = @call(modifier, mix, .{acc});
    }
    return acc;
}

pub fn main() !void {
    // 基准测试1：让编译器决定是否内联（默认启发式）
    var timer = try std.time.Timer.start();
    const auto_result = run(.auto);
    const auto_ns = timer.read();

    // 基准测试2：在每个调用点强制内联
    timer = try std.time.Timer.start();
    const inline_result = run(.always_inline);
    const inline_ns = timer.read();

    // 基准测试3：防止内联，始终发出函数调用
    timer = try std.time.Timer.start();
    const never_result = run(.never_inline);
    const never_ns = timer.read();

    // 验证所有三种策略产生相同的结果
    std.debug.assert(auto_result == inline_result);
    std.debug.assert(auto_result == never_result);

    // 显示优化模式和迭代次数以确保可重现性
    std.debug.print(
        "optimize-mode={s} iterations={}\n",
        .{
            @tagName(builtin.mode),
            iterations,
        },
    );
    // 报告每个调用修饰符的计时结果
    std.debug.print("auto call   : {d} ns\n", .{auto_ns});
    std.debug.print("always_inline: {d} ns\n", .{inline_ns});
    std.debug.print("never_inline : {d} ns\n", .{never_ns});
}

const std = @import("std");

// 每个向量的并行操作数
const lanes = 4;
// 处理4个f32值同时使用SIMD的向量类型
const Vec = @Vector(lanes, f32);

// 从切片加载4个连续的f32值到SIMD向量中。
// 调用者必须确保start + 3在边界内。
fn loadVec(slice: []const f32, start: usize) Vec {
    return .{
        slice[start + 0],
        slice[start + 1],
        slice[start + 2],
        slice[start + 3],
    };
}

// 使用标量操作计算两个f32切片的点积。
// 这是基线实现，一次处理一个元素。
fn dotScalar(values_a: []const f32, values_b: []const f32) f32 {
    std.debug.assert(values_a.len == values_b.len);
    var sum: f32 = 0.0;
    // 乘以对应元素并累积求和
    for (values_a, values_b) |a, b| {
        sum += a * b;
    }
    return sum;
}

// 使用SIMD向量化计算点积以提高性能。
// 一次处理4个元素，然后将向量累加器归约为标量。
// 要求输入长度是通道数（4）的倍数。
fn dotVectorized(values_a: []const f32, values_b: []const f32) f32 {
    std.debug.assert(values_a.len == values_b.len);
    std.debug.assert(values_a.len % lanes == 0);

    // 用零初始化累加器向量
    var accum: Vec = @splat(0.0);
    var index: usize = 0;
    // 每次迭代使用SIMD处理4个元素
    while (index < values_a.len) : (index += lanes) {
        const lhs = loadVec(values_a, index);
        const rhs = loadVec(values_b, index);
        // 执行按元素乘法并添加到累加器
        accum += lhs * rhs;
    }

    // 将累加器向量的所有通道求和为单个标量值
    return @reduce(.Add, accum);
}

// 验证向量化实现产生与标量版本相同的结果。
test "vectorized dot product matches scalar" {
    const lhs = [_]f32{ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 };
    const rhs = [_]f32{ 8.0, 7.0, 6.0, 5.0, 4.0, 3.0, 2.0, 1.0 };
    const scalar = dotScalar(&lhs, &rhs);
    const vector = dotVectorized(&lhs, &rhs);
    // 允许小的浮点误差容忍度
    try std.testing.expectApproxEqAbs(scalar, vector, 0.0001);
}