Axle v0.22.0

What the compiler tells LLVM

An optimiser can only do what it can prove. Two loads through two pointers can be reordered, hoisted out of a loop, or vectorised — but only if the optimiser knows the pointers don’t overlap. In C, it usually can’t know, so it assumes the worst and emits defensive code.

Axle has a structural advantage: its ownership system knows things C’s type system never records. An own T argument aliases nothing. A Shared<T> field is a live object of a known size. A dynamic array’s length header is written once and never changes. The compiler turns each of these facts into an LLVM attribute or a piece of metadata stamped onto the IR, so the backend can optimise as aggressively as if you’d hand-annotated everything.

None of this changes what your program does — it changes what the optimiser is allowed to assume, which is often the difference between a vectorised loop and a scalar one. This is a big part of why two look-alike programs can compile very differently. This page is the honest inventory: what gets stamped, and what does not.

Who decides the facts

Each fact is decided once, by a sema pass, and recorded on the HIR. The codegen side only reads the record and writes the matching LLVM attribute or metadata. No codegen pass re-derives a fact from the shape of the HIR, so a claim cannot be stronger in the IR than the analysis proved.

No-alias: “these pointers don’t overlap”

The single most valuable fact for an optimiser is that two pointers can’t touch the same memory. Axle stamps it where the ownership system guarantees it:

  • A freshly allocated array or object is based on no pre-existing pointer, so the allocator’s return slot carries noalias — LLVM knows a store through it can’t disturb anything the caller already holds.
  • A function that returns a freshly-minted new T() carries noalias on its result, the same malloc-style contract: the returned pointer is not reachable any other way. A function that merely returns an existing object (return self.field;) does not get it — that pointer might alias the caller’s own storage.
  • The lone pointer parameter of an own T function has nothing for it to alias, so it too is noalias.

You can also ask for it directly with @noalias on a parameter.

Parameter facts: what a function does to its pointers

For each pointer parameter, a sema pass walks the body once and records what the function actually does with it. It never guesses from the type or the ownership keyword: a plain borrowed self still writes its own fields, so the keyword alone would be a miscompile. The attributes stamped:

AttributeMeansLets LLVM…
readonlythe body never writes through this pointer, and never lets it escapekeep a load of it hoisted out of a loop
writeonlythe body writes through it but never reads its target, and never lets it escapedrop a redundant load
captures(none) (LLVM 21’s spelling of nocapture)the pointer never escapes the callreuse the caller’s storage across the call
nonnullthe pointer is one of the owning or borrowing shapes that is never nulldelete the null check on every downstream use
dereferenceable(N)it addresses at least N valid bytes of a sized user class; stamped only on a non-null pointer, and never for a weak handlespeculate a load out of a branch or loop
align Nit has known alignment, from a dereferenceable layoutpick the aligned load or store form
noundefevery parameter is initialised at the call sitefold selects and phis without a poison escape hatch

Each of these is a proof, not a hope: a wrong readonly would let -O2 delete a store you needed, so the analysis defaults to the conservative answer (assume written, assume captured) for anything it can’t model. A pointer that is not statically known to be non-null gets no dereferenceable or align: the bytes it might address are not known to exist.

A dynamic array parameter never gets writeonly. The bounds guard reads the array’s length header through the pointer, a read the HIR does not record, so the walk cannot prove the pointer is write-only.

Type-based alias analysis: disjoint fields

Beyond individual pointers, the compiler tells LLVM which kinds of access can’t overlap, via type-based alias metadata (!tbaa) on every typed load and store. Two accesses tagged with distinct types — or two distinct fields of the same object, at known offsets — provably don’t alias, so a loop that reads one field and writes another can be reordered, CSE’d, or vectorised.

Where a field access names a genuine obj.field whose parent type and byte offset are exactly known, the compiler emits a struct-path tag that marks point.x and point.y as disjoint. Other typed accesses use a per-scalar tag. On array-heavy code this can unlock a reordering or a vectorisation LLVM would otherwise leave on the table. The size of the win is entirely workload-dependent; treat it as “this unblocks an optimisation”, not a fixed percentage.

Load facts: range, immutability, definedness

On individual loads, the compiler attaches what it has proven about the value they produce:

  • !range — set on the loads whose storage constrains the value. A bool load is [0, 2), a char load is [0, 0x110000), and the array-length header load is [0, i64::MAX). LLVM then folds away redundant comparisons (if (b > 2) on a bool) and can build tighter jump tables. The bound is a property of how the language stores the value, so it holds on every execution of the load, which is what lets LLVM move the load speculatively. A runtime type id does not get a !range: it is a hash of the class name and spans the whole word.
  • !invariant.load — a value that never changes after it is first set: the runtime type id of an object, and a dynamic array’s length header in a program where no buffer is ever grown in place. LLVM can hoist such a load clean out of a loop. A program that grows a buffer in place rewrites the header, so the claim is dropped program-wide and each bounds check reloads the length.
  • !noundef — every typed scalar load is defined, because Axle requires initialisation at declaration (every let has an initialiser, and struct literals zero-fill). LLVM can then fold select and phi simplifications against the value without a “could be poison” escape hatch.
  • !nonnull, !align, !dereferenceable — the load-site mirrors of the parameter attributes above, for a pointer loaded out of a field whose nullability and layout are known.

Call-site and return facts

Two attributes are stamped on call results rather than on parameters:

  • noalias on a return when the callee returns a freshly minted object on every path (the malloc-style contract described above).
  • dereferenceable_or_null(N) on the return of a direct call to an allocator, where the result addresses N live bytes or is null. The or_null form is required because an allocator may refuse. A plain parameter never receives dereferenceable_or_null.

Cold-path placement

The compiler also tells LLVM which branches are unlikely, via branch weights (!prof). The throw path after an exception poll, the divide-by-zero, bounds-check and out-of-memory guards, and the null branch of a ?? fallback are all tagged cold, so LLVM lays them off the hot instruction-cache line and prioritises the common path for register allocation. A function is cold when every path through it throws, or when it is declared @heat(cold); a declared-cold function is also never inlined.

Not everything LLVM infers about coldness is right, so the compiler re-asserts two invariants on the finished module, after the optimisation pipeline has run:

  • main is not cold. LLVM’s profile-guided heuristics can mark an entry point cold when the module gives it no callers to weigh it against, and a cold entry point is one the backend schedules as never-taken. The attribute is cleared.
  • A body with no exception-handling pad carries no personality. Axle’s exception model is polling, not unwinding: an exception is a value written to a thread-local slot and tested after each call, so no function emits an invoke or a landingpad pair. A personality routine left on such a body is unwinding machinery nothing can reach.

One attribute is deliberately never stripped: noreturn. Unlike coldness, it is a fact about the body: every path through the function exits the process, or never returns. A value-returning function whose every path calls exit keeps it.

Floating-point fast-math

Float instructions carry a fast-math flag bundle driven by the function’s floating-point mode. The three modes are:

ModeSet byLLVM flags on float opsEffect
Contractthe default, or @float(contract)contractA multiply and an add may fuse into one fma, which is why an a*x + y loop can become one FMA per element. Reassociation stays forbidden, so results stay predictable.
Strict@float(strict)noneBare IEEE-754. Even the contraction is refused.
Fast@float(fast)nnan ninf nsz arcp contract afn reassocEvery relaxation: reordering, reciprocal division, and assumptions that no operand is NaN or infinite.

Contract is the default, so which operations fuse depends on the CPU the build targets: one binary always gives the same bits, but a build for a CPU with FMA and one for the portable baseline may differ in the last bit of the same computation. A program that needs the same bits on every target writes @float(strict).

The full bundle is never applied by default, because it can change the last bit of a result, and a floating-point division is never turned into a reciprocal multiply unless the function asks for fast. Under fast, LLVM may fold a comparison such as x != x to a constant, so a NaN test written with arithmetic is unreliable there. The standard library’s isNaN, isFinite and isInfinite read the bit encoding instead, so no flag can relax them. See the annotations reference.

Limitations

Everything above ships. What follows is what the compiler leaves conservative, so you don’t count on it:

  • Enum-tag and type-id !range. A tag’s bound is known in principle, because it indexes the variant list, but the compiler does not stamp a !range on enum-tag loads today. A type id is a hash spread over the whole word, so it can never carry a useful !range.
  • General-integer and loop-induction !range. The interval analysis computes these bounds, but announces them at the site that owns them (@llvm.assume, which is control-dependent) rather than publishing them as a per-load fact that could hoist out of the branch which established it. A general integer load therefore carries no !range even when its bounds are known.
  • !invariant.load on your own immutable fields. Proving a field is never written after construction needs an alias analysis the compiler does not perform. A field reachable through an aliased pointer stays writable, so only the runtime’s own always-immutable loads (array length, type id) carry it. Vtable loads are not annotated either, since virtual dispatch is not yet wired to them.
  • Scoped !noalias. Two borrowed pointers that don’t overlap could in principle be marked noalias, but proving it needs a whole-program aliasing analysis that is not built.
  • dereferenceable_or_null on a parameter. A nullable parameter earns no dereferenceable at all, because the layout facts are gated on the pointer being non-null.

In every one of these cases the compiler emits the conservative IR — correct, just not as aggressively optimised as it could eventually be. None of them is a correctness gap; each is a proof the compiler does not attempt.

See also

optimisationllvmattributesmetadataalias-analysis