# 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.

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.

```lane
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:

```lane
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:

| Form | Meaning |
|---|---|
| `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 parameter | The value lies in `lo..=hi` |
| `@hot` `@cold` | Call frequency, for layout and inlining |
| `@inline` `@noinline` | Force or forbid inlining |
| `@opt(speed)` `@opt(size)` | What to optimize the function for |
| `@align(n)` | Alignment of a record or a function |

```lane
@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);
}
```

```lane
@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](/docs/contracts.md).

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(...)`:

| Flag | Allows |
|---|---|
| `strict` | Nothing (the default) |
| `fma` | Fusing `a * b + c` into one multiply-add |
| `reassoc` | Reordering sums and products |
| `recip` | `x / y` as `x * (1 / y)`, approximate reciprocal and rsqrt |
| `nonan` | Assuming no NaN or infinity |
| `fast` | All of the above |

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

```lane
@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.

```lane
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.

```lane
nul pause() {
    asm { pause }
}
```
