Implement @branchHint and new @export usage

[mlugg]

This PR is just #21206 and #21191 rebased and rolled into one, to avoid doing two separate updates to zig1.wasm.

[andrewrk]

Don't forget to type up those release notes 🙏

[mlugg]

Release Notes

@export Operand is Now a Pointer

This release of Zig simplifies the @export builtin. In previous versions of Zig, this builtin's first operand syntactically appeared to be the value which was to be exported, which was restricted to an identifier or field access of a local variable or container-level declaration. This system was unnecessarily restrictive, and moreover, syntactically confusing and inconsistent; it is reasonable to export constant comptime-known values, and this usage implied that the value was somehow being exported, whereas in reality its address was the relevant piece of information. To resolve this, @export has a new usage which closely mirrors that of @extern; its first operand is a pointer, which points to the data being exported. In most cases, solving this will just consist of adding a & operator:

const foo: u32 = 123;
test "@export" {
    @export(foo, .{ .name = "bar" });
}

-->

const foo: u32 = 123;
test "@export" {
    @export(&foo, .{ .name = "bar" });
}

New @branchHint Builtin, Replacing @setCold

In high-performance code, it is sometimes desirable to hint to the optimizer which branch of a condition is more likely; this can allow more efficient machine code to be generated. Some languages offer this through a "likely" annotation on a boolean condition; for instance, GCC and Clang implement the __builtin_expect function. Zig 0.14.0 introduces a mechanism to communicate this information: the new @branchHint(comptime hint: std.builtin.BranchHint) builtin. This builtin, rather than modifying a condition, appears as the first statement in a block to communicate whether control flow is likely to reach the block in question:

fn warnIf(cond: bool, message: []const u8) void {
    if (cond) {
        @branchHint(.unlikely); // we expect warnings to *not* happen most of the time!
        std.log.warn("{s}", message);
    }
}
const std = @import("std");

The BranchHint type is as follows:

pub const BranchHint = enum(u3) {
    /// Equivalent to no hint given.
    none,
    /// This branch of control flow is more likely to be reached than its peers.
    /// The optimizer should optimize for reaching it.
    likely,
    /// This branch of control flow is less likely to be reached than its peers.
    /// The optimizer should optimize for not reaching it.
    unlikely,
    /// This branch of control flow is unlikely to *ever* be reached.
    /// The optimizer may place it in a different page of memory to optimize other branches.
    cold,
    /// It is difficult to predict whether this branch of control flow will be reached.
    /// The optimizer should avoid branching behavior with expensive mispredictions.
    unpredictable,
};

As well as being the first statement of a block behind a condition, @branchHint is also permitted as the first statement of any function. The expectation is that the optimizer may propagate likelihood information to branches containing these calls; for instance, if a given branch of control flow always calls a function which is marked @branchHint(.unlikely), then the optimizer may assume that the branch in question is unlikely to be reached.

This feature combined with the existence of the .cold variant of BranchHint means that the old @setCold builtin, which could be used to communicate that a function is unlikely to ever be called, becomes redundant. Therefore, @setCold has been removed in favor of @branchHint. In most cases, the migration will be very simple; just replace @setCold(true) with @branchHint(.cold):

fn foo() void {
    @setCold(true);
    // ...
}

-->

fn foo() void {
    @branchHint(.cold);
    // ...
}

However, remember that @branchHint must be the first statement in the enclosing block, which in this case is the function. This restriction did not exist for @setCold, so non-trivial usages may require small refactors:

fn foo(comptime x: u8) void {
    if (x == 0) {
        @setCold(true);
    }
    // ...
}

-->

fn foo(comptime x: u8) void {
    @branchHint(if (x == 0) .cold else .none);
    // ...
}