Axle v0.22.0

Inlining, tail calls, and whole-program merge

Calling a function costs more than the work inside it: the CPU pushes the arguments and a return address, jumps away, runs the body, and jumps back. For a one-line accessor that overhead can dwarf the actual computation — and worse, a call is a wall the optimiser can’t see past, so everything on the far side has to be assumed to do anything.

Axle attacks both problems: it removes the call where it can, and where a call remains, it tries to make sure the optimiser can still see through it. Three mechanisms, all automatic.

Inlining small bodies

Inlining pastes a function’s body into the caller at the call site, so x = size(p) becomes x = p.len — no jump, and the surrounding optimiser now reasons about x as the field itself. Every function is classified at compile time into one of four inline hints:

HintSet whenWhat the backend receives
AlwaysThe body has at most 16 statements (counted at every nesting depth), or the author wrote @inline(always). A body of at most 8 statements is folded at every site. A larger one is folded only while a global growth budget holds.alwaysinline for an authored @inline(always); inlinehint otherwise, so the cost model still weighs each call site.
HintThe body, after its own Always callees are expanded into it, has at most 32 statements.inlinehint. The optimiser should prefer inlining.
NoneAnything larger.No inline attribute; the cost model decides on its own.
NeverThe body was split out of a caller by the compiler, or the source declares @heat(cold) or @inline(never).noinline. A veto that outranks the size tiers.

The reasoning behind the split is the cost model. From -O1 LLVM’s inliner runs and sees what the statement count cannot: how many sites call the body, how hot they are, and how large the caller has grown. Forcing an inline there would remove that judgement, and every small helper would be copied into every caller. At -O0 no LLVM pass runs, so these hints have no effect; only the optimised levels read them.

A function on a direct call cycle is never marked Always, because alwaysinline on a recursive function is an error. The same holds for a function that uses the arena, because folding it would merge two arena scopes.

The trade-off is code size: paste a large body into a thousand call sites and the binary balloons. The full rule, and the four-tier decision it implements, are in Inlining and tail calls.

Self-tail-recursion becomes a loop

A tail call is the last thing a function does — return f(args) with nothing left to compute after f returns. When a function tail-calls itself, the recursion is really a loop in disguise, and Axle rewrites it into one before LLVM ever sees it — so a deep recursion runs at constant stack depth by construction, not by optimiser goodwill:

fn fact(n : i64, acc : i64) : i64 {
    if (n <= 1) { return acc; }
    return fact(n - 1, acc * n);
}

fn main() : i32 {
    return fact(5, 1) as i32 - 120;   // 120 - 120 = 0
}

Dump this with --emit=llvm and there is no recursive call left: fact is a single-block loop whose induction values are plain φ nodes, a compare, and a back-edge. The recursion became O(1) stack frames instead of O(depth) — a deep input that would have overflowed the stack now runs fine.

The rewrite fires only when it is provably equivalent:

  • the function is a free function or a static method (no implicit receiver);
  • the body returns on every path, so the loop can only exit through a return;
  • every parameter can be reassigned by a plain value copy. An own parameter is refused, because overwriting it would leak the value it owns. A borrowed class parameter qualifies;
  • the self-call sits at the function’s top level or inside plain if branches. It is never inside an inner loop, where the back-jump would target the wrong loop, nor inside a try, synchronized or defer, where jumping back would skip the cleanup.

Two details matter for soundness. The new argument values are computed into temporaries from the old parameters before any parameter is overwritten, so fact(n - 1, acc * n) reads the old n in both arguments. And a self-call that fails one of the gates stays an ordinary call; the exact conditions are in Inlining and tail calls.

The LLVM tail qualifier

For a return f(args) that the loop rewrite does not claim, such as a call to a different function or mutual recursion, the compiler stamps the LLVM tail qualifier. It lets the optimiser reuse the caller’s dead frame for the jump.

The qualifier is applied only when every argument is a by-value scalar (numbers, bool, char, unit). A pointer into the caller’s frame could be clobbered once that frame is reused, and a string, array, Shared<T> or class argument carries an address. Only the canonical shape return f(args) is considered; a call wrapped in further arithmetic is not moved into tail position. The qualifier is a permission, not a guarantee: LLVM may or may not reuse the frame. Details and the safety argument are in Inlining and tail calls.

The whole program is one module

Here is the part that sets Axle apart from most compiled languages. In a typical toolchain, a call into the standard library or the language runtime is a wall: the body lives in a separately-compiled archive, so the inliner, loop-invariant hoisting, and dead-store elimination all have to assume the worst about what happens across that call.

In Axle they don’t. The standard library — the function bodies themselves, shipped as LLVM bitcode — is merged into your module’s IR before the optimiser runs. There is then one IR unit (your code, the stdlib bodies, the folded runtime leaves) and one optimiser pass over all of it. mem2reg, the inliner, LICM, dead-store elimination, GVN, and the vectoriser all see straight through the stdlib boundary.

This is not ThinLTO: there’s no separate link-time step and no cross-module summary index — just a plain IR merge followed by the ordinary pass pipeline, at the same -O level you asked for.

On top of the merge, the runtime functions you hit on nearly every line of string-heavy or Shared<T>-heavy code are also compiled as self-contained, inlinable IR and folded in as available_externally definitions. At -O2 and above on the host target, LLVM can inline them to a few instructions right where you call them. Below that level, or when cross-compiling to a non-host target, those leaves stay ordinary calls. The fold is a release-build win, and debug builds keep clean stack traces and fast compiles. The folded copy is only inlining metadata: the real symbol still lives in the runtime archive, so nothing changes when the fold does not apply. The full mechanism is in Runtime and stdlib inlining.

Where it stops — honestly

  • Large bodies aren’t force-inlined. Past the size tiers the decision is LLVM’s cost model, which can decline. Inlining everything would bloat the binary and thrash the instruction cache.
  • The self-recursion rewrite only covers direct self-calls that pass the gates above. Mutual recursion and calls with pointer-shaped arguments get the tail qualifier, which is a permission LLVM may or may not act on, not the guaranteed loop.
  • Leaf folding is a host-target, -O2-and-above feature. Cross-compiled or debug builds keep the plain cross-boundary call. It is correct, just not inlined.

Limits / Uncabled

FeatureStateDetail or workaround
Guaranteed tail calls (musttail)Not stamped. The strict form needs matching ABIs and stack discipline that the front end does not verify.Write the recursion as a self-call that meets the gates above, so it becomes a loop.
Inlining a function called through a function valueThe call stays a call; the callee’s hint cannot be applied at a site the compiler does not resolve.Call the function by name where the call cost matters.

See also

optimisationinliningtail-callsltoruntime