tobogganSe connecter

louise

The Louise language: compiler, runtime, std, tooling

Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.

51 lignes · 6722 octetsBrut · Historique

ADR 0013: Numeric code: uniform values, specialised evidence

Status: Accepted by the project owner on 2026-10-12; proposed 2026-10-09 (issue #61); needs engineering review (#44).

Context

  • Values are uniform (ADR 0002): every value is one 64-bit word. Int is a tagged 63-bit immediate, promoted to a big integer block on overflow (ADR 0014); Float is a heap block; so is all other data.
  • Traits are dictionaries (ADR 0007): x + 1 on Int reads the Num<Int> dictionary, projects its add closure and calls it. ADR 0007 left "known Impl evidence at monomorphic call sites can be specialised later". Since issue #34, a dictionary without constraints is static data, but every method call still went through a closure.
  • The question (roadmap M2): should numeric code be monomorphised, that is, compiled per type with unboxed Int and Float in C locals, or keep the uniform representation?

Measurements

Made before deciding, before big integers (ADR 0014) and multi-shot resumptions (ADR 0017) were merged under this work, on tests/bench, release builds with clang 22, one scheduler thread, pinned to performance cores. Counts are user-space instructions and cycles from the CPU's counters, best of 5 interleaved runs (wall time on this shared machine varies by ±15%).

Where arith spent its time: 51% of its cycles were in the closure entries of Num<Int> and Ord<Int> methods, 11% in calls of tl_int_compare. The tagged arithmetic itself was a small part.

Dictionaries known at compile time, step by step (cycles, change from the state before the step series):

Steparithdicteffectslists
Methods of constant dictionaries called directly, trivial ones inlined−27%−21%−34%−11%
… and constrained functions specialised for constant dictionaries−71%−22%−33%−8%
… and Int comparison, multiplication and division inline in louise_rt.h−84%−30%−40%−18%

What unboxing Int would add: arith's two hot functions written by hand in C, once as generated today (tagged values, after the steps above) and once with int64_t locals, with the same control flow (reduction counter, overflow checks, yield checks). The unboxed version ran 8% more cycles (307M against 284M) and 14% more instructions. Int is 63-bit, so unboxed arithmetic needs explicit range checks, while tagged arithmetic gets them from the 64-bit overflow flag; dup and drop of a tagged int are one predicted branch. Since ADR 0014, an overflow promotes to a big integer, which an unboxed int64_t cannot hold: unboxed code would also need a boxed fallback.

What unboxing Float would add: tests/bench/floats (a new benchmark) spent 88% of its cycles allocating and freeing the result of each operation. Unboxed doubles would make such loops several times faster.

Decision

  1. v1 keeps the uniform representation. No type-directed monomorphisation, and no second representation of values.

  2. Known evidence is specialised instead (implemented, louise_core::evidence). A Core-to-Core pass, run by the C backend before Perceus:

    • calls of methods projected from constant dictionaries become direct calls;
    • methods whose body is one extern call or primitive on their parameters are inlined;
    • a constrained function called with constant dictionaries gets a copy for that combination, in which the same applies; recursion reuses its copy. At most one copy per function of the program, in total;
    • the projections and dictionary reads left unused are removed.

    This is monomorphisation over dictionaries, not over representations: values stay uniform, so nothing else changes (Perceus, unwinding, sending, the ABI).

  3. Float stays boxed in v1. Its cost is the allocator's fast path, made cheaper in issue #61 (floats: −39%).

  4. Int's primitives are inline in louise_rt.h: equality, comparison, multiplication, division and remainder join addition and subtraction. (Issue #47 did this with big-integer slow paths, which replaced this issue's version with panics.)

Consequences

  • Generic numeric code called at known types runs like monomorphic code: arith −71% cycles, dict −34%, effects −43% against the v1 chain built with clang (with the runtime changes of issue #61; see tests/bench/README.md).
  • Code does not grow: the specialised C of http_demo is 10% smaller (4 copies; the closure-call sequences they replace were longer), and compiles 12% faster.
  • The interpreter runs Core as lowered. The differential tests therefore check the pass against unspecialised programs. LOUISE_NO_SPECIALISE=1 turns it off, to compare or to bisect a miscompilation.
  • Preemption points differ from the interpreter's. The interpreter counts every call as a reduction; inlined methods (and functions that never unwind, ADR 0003 Revision 2's implementation note) no longer count. With LOUISE_THREADS=1 the native order stays deterministic, but a program whose output depends on where actors are preempted may print in another order than in the interpreter. No tests/run program does.
  • Not specialised: dictionaries built from constraints (Ord<List<Int>> from Ord<Int>), and dictionaries captured by closures (list.sum passes its Num to a lambda). Both could be added to the same pass. (Dictionaries built from constant ones are specialised since issue #278: ADR 0043's note of 2026-10-23.)
  • Float-heavy code stays slow compared with languages that unbox doubles.

Alternatives considered

  • Monomorphisation with unboxed values (MLton, Rust). Core is untyped (types are erased by lowering), so it needs types in Core or specialisation before lowering. Unboxed values then need boxing where they meet generic code, Perceus and unwinding that know which locals are not references, and a second calling convention. For Int it measured slower; for Float it would pay off, but floats are rare in the programs v1 targets (servers, actors). To revisit with a float-heavy use case.
  • NaN-boxing floats. It changes the encoding of every value (pointers and ints included), the ABI and the sanitizer story. Rejected for v1.
  • Devirtualisation without copies. Generic functions stay slow (arith −27% instead of −71%).
  • Specialising in the interpreter too. It would speed up louise run, but the interpreter is the reference the native backend is tested against.