Per-ISA code, hints and floats

when selects declarations per target at compile time, optimizer hints are predeclared functions and attributes, and float code is strict unless a function relaxes it with @fp.

Markdown version of this page

This page is specified in section 8 of the language specification, marked provisional.

#Per-target code with when

when tests the compile-time constants isa, os, arch and any constant set on the command line (-D name=value). It works around declarations and inside function bodies, and replaces a textual preprocessor: every branch is parsed on every target, and nothing is substituted as text. A when depends only on target constants, never on another declaration's body, which keeps compilation parallel and deterministic.

u64 popcnt(u64 x) {
    when isa >= .bmi2 {
        ret x86.popcnt64(x);
    } else when arch == .aarch64 {
        ret arm.cnt64(x);
    } else {
        u64 n = 0;
        v := x;
        for v != 0 {
            v &= v - 1;
            n += 1;
        }
        ret n;
    }
}

A when can also choose a constant:

when isa == .avx512 {
    W :: 16;
} else {
    W :: 8;
}

Raw instructions are functions in per-architecture modules (x86.*, arm.*) and are legal only in a branch that selects that architecture.

#Hints

Hints are predeclared functions and attributes, not keywords:

FormMeaning
likely(c) unlikely(c)Expected branch direction
assume(c)c holds here; the optimizer may rely on it. A function states what it requires of its callers with assume lines in its header (section 9.1)
unreachable()Control never gets here
prefetch(p)Bring the cache line at p in
is_const(x)True if x is known at compile time
@range(lo, hi) on a parameterThe value lies in lo..=hi
@hot @coldCall frequency, for layout and inlining
@inline @noinlineForce or forbid inlining
@opt(speed) @opt(size)What to optimize the function for
@align(n)Alignment of a record or a function
@hot @inline
bool probe([]u64 keys, @range(0, 1023) u32 slot, u64 key) {
    prefetch(&keys[slot + 8]);
    if likely(keys[slot] == key) { ret true; }
    if unlikely(keys[slot] == 0) { ret false; }
    assume(slot < keys.len);
    ret probe_slow(keys, slot, key);
}
@cold @noinline
bool probe_slow([]u64 keys, u32 slot, u64 key) {

assume(c) inside a body is a hint. A function states what it requires of its callers with assume lines in its header; see Contracts.

An attribute's ( opens its arguments, unless the group starts with a type, has a comma directly inside it, and is followed by fn or by a name and (. So @inline (f32, bool) find(u64 key) is a function with a tuple return type, and @align(64) rec A { } has an argument.

#Floating point

Float code is strict by default: operations happen in source order and nothing is fused, so results are bit-identical on every target. A function relaxes this with @fp(...):

FlagAllows
strictNothing (the default)
fmaFusing a * b + c into one multiply-add
reassocReordering sums and products
recipx / y as x * (1 / y), approximate reciprocal and rsqrt
nonanAssuming no NaN or infinity
fastAll of the above

The function below allows fusing and reordering, which a vectorized float sum needs.

@fp(fma, reassoc)
f32 dot([]f32 a, []f32 b) {
    f32 s = 0;
    vec i in 0..a.len {
        s += a[i] * b[i];
    }
    ret s;
}

A vec loop that accumulates floats needs reassoc; without it the loop is a compile error. fma(a, b, c) is always one fused multiply-add, whatever the flags.

f32 lerp(f32 a, f32 b, f32 t) {
    ret fma(t, b - a, a);
}

Float literals are 3.14, 1e9 and 1.5e-3; a fraction needs a digit after the dot, so 0..n is an integer followed by ... There are no literal suffixes: convert with f32(1).

#Raw assembly

asm { } holds raw instructions up to the matching }. For now its content must consist of valid Lane tokens, and its syntax is still an open question.

nul pause() {
    asm { pause }
}