Profiling, Optimization, Hardening

// This program demonstrates performance measurement and comparison of different
// sorting algorithms using Zig's built-in Timer for benchmarking.
const std = @import("std");

// Number of elements to sort in each benchmark run
const sample_count = 1024;

/// Generates a deterministic array of random u32 values for benchmarking.
/// Uses a fixed seed to ensure reproducible results across multiple runs.
/// @return: Array of 1024 pseudo-random u32 values
fn generateData() [sample_count]u32 {
    var data: [sample_count]u32 = undefined;
    // Initialize PRNG with fixed seed for deterministic output
    var prng = std.Random.DefaultPrng.init(0xfeed_beef_dead_cafe);
    var random = prng.random();
    // Fill each array slot with a random 32-bit unsigned integer
    for (&data) |*slot| {
        slot.* = random.int(u32);
    }
    return data;
}

/// Measures the execution time of a sorting function on a copy of the input data.
/// Creates a scratch buffer to avoid modifying the original data, allowing
/// multiple measurements on the same dataset.
/// @param sortFn: Compile-time sorting function to benchmark
/// @param source: Source data to sort (remains unchanged)
/// @return: Elapsed time in nanoseconds
fn measureSort(
    comptime sortFn: anytype,
    source: []const u32,
) !u64 {
    // Create scratch buffer to preserve original data
    var scratch: [sample_count]u32 = undefined;
    std.mem.copyForwards(u32, scratch[0..], source);

    // Start high-resolution timer immediately before sort operation
    var timer = try std.time.Timer.start();
    // Execute the sort with ascending comparison function
    sortFn(u32, scratch[0..], {}, std.sort.asc(u32));
    // Capture elapsed nanoseconds
    return timer.read();
}

pub fn main() !void {
    // Generate shared dataset for all sorting algorithms
    var dataset = generateData();

    // Benchmark each sorting algorithm on identical data
    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..]);

    // Display raw timing results along with build mode
    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});

    // Calculate relative performance metrics using block sort as baseline
    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;

    // Display comparative analysis showing speedup/slowdown factors
    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});
}

// This program demonstrates how compile-time configuration affects binary size
// by conditionally enabling debug tracing based on the build mode.
const std = @import("std");
const builtin = @import("builtin");

// Compile-time flag that enables tracing only in Debug mode
// This demonstrates how dead code elimination works in release builds
const enable_tracing = builtin.mode == .Debug;

// Computes a FNV-1a hash for a given word
// FNV-1a is a fast, non-cryptographic hash function
// @param word: The input byte slice to hash
// @return: A 64-bit hash value
fn checksumWord(word: []const u8) u64 {
    // FNV-1a 64-bit offset basis
    var state: u64 = 0xcbf29ce484222325;
    
    // Process each byte of the input
    for (word) |byte| {
        // XOR with the current byte
        state ^= byte;
        // Multiply by FNV-1a 64-bit prime (with wrapping multiplication)
        state = state *% 0x100000001b3;
    }
    return state;
}

pub fn main() !void {
    // Sample word list to demonstrate the checksum functionality
    const words = [_][]const u8{ "profiling", "optimization", "hardening", "zig" };
    
    // Accumulator for combining all word checksums
    var digest: u64 = 0;
    
    // Process each word and combine their checksums
    for (words) |word| {
        const word_sum = checksumWord(word);
        // Combine checksums using XOR
        digest ^= word_sum;
        
        // Conditional tracing that will be compiled out in release builds
        // This demonstrates how build mode affects binary size
        if (enable_tracing) {
            std.debug.print("trace: {s} -> {x}\n", .{ word, word_sum });
        }
    }

    // Output the final result along with the current build mode
    // Shows how the same code behaves differently based on compilation settings
    std.debug.print(
        "mode={s} digest={x}\n",
        .{
            @tagName(builtin.mode),
            digest,
        },
    );
}

// This example demonstrates input validation and error handling patterns in Zig,
// showing how to create guarded data processing pipelines with proper bounds checking.

const std = @import("std");

// Custom error set for parsing and validation operations
const ParseError = error{
    EmptyInput,      // Returned when input contains only whitespace or is empty
    InvalidNumber,   // Returned when input cannot be parsed as a valid number
    OutOfRange,      // Returned when parsed value is outside acceptable bounds
};

/// Parses and validates a text input as a u32 limit value.
/// Ensures the value is between 1 and 10,000 inclusive.
/// Whitespace is automatically trimmed from input.
fn parseLimit(text: []const u8) ParseError!u32 {
    // Remove leading and trailing whitespace characters
    const trimmed = std.mem.trim(u8, text, " \t\r\n");
    if (trimmed.len == 0) return error.EmptyInput;

    // Attempt to parse as base-10 unsigned 32-bit integer
    const value = std.fmt.parseInt(u32, trimmed, 10) catch return error.InvalidNumber;
    
    // Enforce bounds: reject zero and values exceeding maximum threshold
    if (value == 0 or value > 10_000) return error.OutOfRange;
    return value;
}

/// Applies a throttling limit to a work queue, ensuring safe processing bounds.
/// Returns the actual number of items that can be processed, which is the minimum
/// of the requested limit and the available work length.
fn throttle(work: []const u8, limit: u32) ParseError!usize {
    // Precondition: limit must be positive (enforced at runtime in debug builds)
    std.debug.assert(limit > 0);

    // Guard against empty work queues
    if (work.len == 0) return error.EmptyInput;

    // Calculate safe processing limit by taking minimum of requested limit and work size
    // Cast is safe because we're taking the minimum value
    const safe_limit = @min(limit, @as(u32, @intCast(work.len)));
    return safe_limit;
}

// Test: Verify that valid numeric strings are correctly parsed
test "valid limit parses" {
    try std.testing.expectEqual(@as(u32, 750), try parseLimit("750"));
}

// Test: Ensure whitespace-only input is properly rejected
test "empty input rejected" {
    try std.testing.expectError(error.EmptyInput, parseLimit("   \n"));
}

// Test: Verify throttling respects the parsed limit and work size
test "in-flight throttling respects guard" {
    const limit = try parseLimit("32");
    // Work length (4) is less than limit (32), so expect work length
    try std.testing.expectEqual(@as(usize, 4), try throttle("hard", limit));
}

// Test: Validate multiple inputs meet the maximum threshold requirement
// Demonstrates compile-time iteration for testing multiple scenarios
test "validate release configurations" {
    const inputs = [_][]const u8{ "8", "9999", "500" };
    // Compile-time loop unrolls test cases for each input value
    inline for (inputs) |value| {
        const parsed = try parseLimit(value);
        // Ensure parsed values never exceed the defined maximum
        try std.testing.expect(parsed <= 10_000);
    }
}