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()carriesnoaliason 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 Tfunction has nothing for it to alias, so it too isnoalias.
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:
| Attribute | Means | Lets LLVM… |
|---|---|---|
readonly | the body never writes through this pointer, and never lets it escape | keep a load of it hoisted out of a loop |
writeonly | the body writes through it but never reads its target, and never lets it escape | drop a redundant load |
captures(none) (LLVM 21’s spelling of nocapture) | the pointer never escapes the call | reuse the caller’s storage across the call |
nonnull | the pointer is one of the owning or borrowing shapes that is never null | delete 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 handle | speculate a load out of a branch or loop |
align N | it has known alignment, from a dereferenceable layout | pick the aligned load or store form |
noundef | every parameter is initialised at the call site | fold 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. Aboolload is[0, 2), acharload is[0, 0x110000), and the array-length header load is[0, i64::MAX). LLVM then folds away redundant comparisons (if (b > 2)on abool) 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 (everylethas an initialiser, and struct literals zero-fill). LLVM can then foldselectand 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:
noaliason 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 addressesNlive bytes or is null. Theor_nullform is required because an allocator may refuse. A plain parameter never receivesdereferenceable_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:
mainis 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 acoldentry 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
invokeor alandingpadpair. 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:
| Mode | Set by | LLVM flags on float ops | Effect |
|---|---|---|---|
Contract | the default, or @float(contract) | contract | A 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) | none | Bare IEEE-754. Even the contraction is refused. |
Fast | @float(fast) | nnan ninf nsz arcp contract afn reassoc | Every 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!rangeon 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!rangeeven when its bounds are known. !invariant.loadon 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 markednoalias, but proving it needs a whole-program aliasing analysis that is not built. dereferenceable_or_nullon a parameter. A nullable parameter earns nodereferenceableat 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
- Arithmetic strength reduction — the division and peephole rewrites these facts sit alongside.
- Memory placement — the ownership system whose extra information all of this exploits.
- SIMD and auto-vectorisation — what the alias and range facts unlock for vector loops.
- Optimisations overview — the complete census.