Performance & Inlining

// This file demonstrates Zig's inline semantics and compile-time execution features.
// It shows how the `inline` keyword and `@call` builtin can control when and how
// functions are evaluated at compile-time versus runtime.

const std = @import("std");

/// Computes the nth Fibonacci number using recursion.
/// The `inline` keyword forces this function to be inlined at all call sites,
/// and the `comptime n` parameter ensures the value can be computed at compile-time.
/// This combination allows the result to be available as a compile-time constant.
inline fn fib(comptime n: usize) usize {
    return if (n <= 1) n else fib(n - 1) + fib(n - 2);
}

/// Computes the factorial of n using recursion.
/// Unlike `fib`, this function is not marked `inline`, so the compiler
/// decides whether to inline it based on optimization heuristics.
/// It can be called at either compile-time or runtime.
fn factorial(n: usize) usize {
    return if (n <= 1) 1 else n * factorial(n - 1);
}

// Demonstrates that an inline function with comptime parameters
// propagates compile-time execution to its call sites.
// The entire computation happens at compile-time within the comptime block.
test "inline fibonacci propagates comptime" {
    comptime {
        const value = fib(10);
        try std.testing.expectEqual(@as(usize, 55), value);
    }
}

// Demonstrates the `@call` builtin with `.compile_time` modifier.
// This forces the function call to be evaluated at compile-time,
// even though `factorial` is not marked `inline` and takes non-comptime parameters.
test "@call compile_time modifier" {
    const result = @call(.compile_time, factorial, .{5});
    try std.testing.expectEqual(@as(usize, 120), result);
}

// Verifies that a non-inline function can still be called at runtime.
// The input is a runtime value, so the computation happens during execution.
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");

// Number of iterations to run each benchmark variant
const iterations: usize = 5_000_000;

/// A simple mixing function that demonstrates the performance impact of inlining.
/// Uses bit rotation and arithmetic operations to create a non-trivial workload
/// that the optimizer might handle differently based on call modifiers.
fn mix(value: u32) u32 {
    // Rotate left by 7 bits after XORing with a prime-like constant
    const rotated = std.math.rotl(u32, value ^ 0x9e3779b9, 7);
    // Apply additional mixing with wrapping arithmetic to prevent compile-time evaluation
    return rotated *% 0x85eb_ca6b +% 0xc2b2_ae35;
}

/// Runs the mixing function in a tight loop using the specified call modifier.
/// This allows direct comparison of how different inlining strategies affect performance.
fn run(comptime modifier: std.builtin.CallModifier) u32 {
    var acc: u32 = 0;
    var i: usize = 0;
    while (i < iterations) : (i += 1) {
        // The @call builtin lets us explicitly control inlining behavior at the call site
        acc = @call(modifier, mix, .{acc});
    }
    return acc;
}

pub fn main() !void {
    // Benchmark 1: Let the compiler decide whether to inline (default heuristics)
    var timer = try std.time.Timer.start();
    const auto_result = run(.auto);
    const auto_ns = timer.read();

    // Benchmark 2: Force inlining at every call site
    timer = try std.time.Timer.start();
    const inline_result = run(.always_inline);
    const inline_ns = timer.read();

    // Benchmark 3: Prevent inlining, always emit a function call
    timer = try std.time.Timer.start();
    const never_result = run(.never_inline);
    const never_ns = timer.read();

    // Verify all three strategies produce identical results
    std.debug.assert(auto_result == inline_result);
    std.debug.assert(auto_result == never_result);

    // Display the optimization mode and iteration count for reproducibility
    std.debug.print(
        "optimize-mode={s} iterations={}\n",
        .{
            @tagName(builtin.mode),
            iterations,
        },
    );
    // Report timing results for each call modifier
    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");

// Number of parallel operations per vector
const lanes = 4;
// Vector type that processes 4 f32 values simultaneously using SIMD
const Vec = @Vector(lanes, f32);

/// Loads 4 consecutive f32 values from a slice into a SIMD vector.
/// The caller must ensure that start + 3 is within bounds.
fn loadVec(slice: []const f32, start: usize) Vec {
    return .{
        slice[start + 0],
        slice[start + 1],
        slice[start + 2],
        slice[start + 3],
    };
}

/// Computes the dot product of two f32 slices using scalar operations.
/// This is the baseline implementation that processes one element at a time.
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;
    // Multiply corresponding elements and accumulate the sum
    for (values_a, values_b) |a, b| {
        sum += a * b;
    }
    return sum;
}

/// Computes the dot product using SIMD vectorization for improved performance.
/// Processes 4 elements at a time, then reduces the vector accumulator to a scalar.
/// Requires that the input length is a multiple of the lane count (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);

    // Initialize accumulator vector with zeros
    var accum: Vec = @splat(0.0);
    var index: usize = 0;
    // Process 4 elements per iteration using SIMD
    while (index < values_a.len) : (index += lanes) {
        const lhs = loadVec(values_a, index);
        const rhs = loadVec(values_b, index);
        // Perform element-wise multiplication and add to accumulator
        accum += lhs * rhs;
    }

    // Sum all lanes of the accumulator vector into a single scalar value
    return @reduce(.Add, accum);
}

// Verifies that the vectorized implementation produces the same result as the scalar version.
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);
    // Allow small floating-point error tolerance
    try std.testing.expectApproxEqAbs(scalar, vector, 0.0001);
}