Module optimization

Expand description

The single source of truth for compiler optimization toggles.

Every optimization the compiler can perform has exactly one row in REGISTRY, naming it, giving it a human label and a ## No <Keyword> decorator keyword, recording which execution paths it touches, whether it emits unsafe Rust, how it trades memory for speed, and its dependencies and conflicts with other optimizations.

A live choice of which optimizations are on is an OptimizationConfig — a single u64 bitset, one bit per Opt. The default is “everything on” (tuned for speed); disabling everything yields plain, boring Rust.

This lives in logicaffeine_language (not the compiler) because the parser maps ## No <Keyword> decorators to Opts, so the type must be visible here; the compiler and JIT see it transitively.

Modules§

path: Execution-path tags (bitmask) recording where an optimization applies.

Structs§

FiredOptimizations: Which optimizations actually FIRED during a single compile — one bit per Opt, the same bit layout as OptimizationConfig. An optimization is “fired” when it actually changed the program or emitted its optimized form for this compile, as distinct from merely being enabled. Populated only while a firing trace is active (see logicaffeine_compile’s traced compile entry points); the normal compile path never records into it.
HotswapConfig: “When does each allowed opt run” — the sibling to OptimizationConfig (HOTSWAP §8). mode picks the escalation policy, thresholds the rungs, force_tier pins a fixed tier for deterministic tests, and pins overrides individual opts.
NormalizeReport: What normalize changed, so a UI can explain auto-disabled toggles.
OptMeta: One row of the optimization registry — the complete static description of a single optimization. Adding an optimization means adding one Opt variant and one row here; nothing else hardcodes the list.
OptNode: One node of a program’s optimization relationship tree: an optimization that is in play for that program, with its nesting depth and its edges.
OptimizationConfig: A live choice of which optimizations are enabled — one bit per Opt.
PinSet: Per-opt tier pins, indexed by Opt discriminant. None ⇒ use the cost-derived tier. Copy so HotswapConfig stays cheap to thread through the run path.
TierThresholds: Call/back-edge counts at which a unit enters each tier (HOTSWAP §5). Defaults: don’t optimize code that runs once (T1 at 8); amortize whole-function analyses only once recurring (T2 at 32); pay the cloning passes only on genuinely hot kernels (T3 at 100, aligned with the existing native-tier threshold).

Enums§

MemClass: How an optimization trades memory against speed.
Opt: Every optimization the compiler can toggle. The discriminant is the bit index used by OptimizationConfig, so the order here is stable and must not be reordered casually (it also defines conflict-resolution precedence: an earlier variant wins a conflict against a later one).
OptCost: How expensive an optimization pass is to RUN on the live path — the lever the tiered optimizer uses to decide WHEN (at which hotness tier) to pay for it. Orthogonal to MemClass (which is about the OUTPUT’s memory cost). The derived Ord makes a tier gate a single comparison: Cheap < Medium < Heavy is exactly the tier-inclusion order T1 ⊂ T2 ⊂ T3.
OptRole: Why an optimization appears in a program’s relationship_tree.
Pin: A per-opt tier override (HOTSWAP §8 ## Tier <kw> <eager|t1|t2|t3|never>).
Profile: A named optimization preset.
Reason: Why normalize flipped an optimization off.
Scope: Where a ## No <X> decorator for this optimization may legitimately appear.
Tier: A hotness tier — how much optimization budget a unit has earned (HOTSWAP §4.1). Each tier pays for strictly more than the one below; T3 with an all-on config reproduces today’s whole-program optimize_for_run, bit-for-bit (the compatibility + soundness anchor). The mechanism that escalates a unit through the tiers (call/back-edge counters, thresholds) lives in the VM; this is just the policy the optimizer reads.
TierMode: WHEN each allowed optimization runs, as opposed to WHICH are allowed (OptimizationConfig). The sibling policy of HOTSWAP §8: the bitset says what is permitted; this says at what hotness tier each permitted opt is paid for. Kept separate from OptimizationConfig (which is serialized / merged per-function / normalized) so tier state never pollutes the “which opts” bitset.

Constants§

OPT_COUNT: The number of Opt variants — the width of a PinSet. Derived from the last variant so it tracks the enum automatically (guarded by a test against REGISTRY.len()).

Statics§

REGISTRY: The complete optimization registry: exactly one row per Opt, in discriminant order. Earlier rows win conflicts against later rows.

Functions§

admits: Whether opt runs at tier under cfg: it must be enabled in the config AND cost no more than the tier’s budget. The tier→opt-set mapping is therefore DERIVED from the registry, never hardcoded — adding an opt with a cost slots it into the right tier automatically (HOTSWAP §4.2).
admits_pinned: admits with per-opt pins applied: a pin overrides the cost-derived tier (HOTSWAP §8). A disabled opt (!cfg.is_on) never runs regardless of pin, so ## No <opt> always wins over ## Tier <opt> eager.
by_keyword: Look up an optimization by its decorator keyword (case-insensitive).
decorate_source: Produce a copy of src with a file-level ## No <keyword> decorator inserted (just before ## Main, where the parser folds it into the program-wide config) for each disabled-optimization keyword. This is what the benchmarks UI shows on the Logos source when a toggle is flipped off; compiling the result applies the same config the toggle represents.
decorate_tiers: Produce a copy of src with a file-level ## Tier <keyword> <value> decorator inserted (just before ## Main, where the parser collects program-level tier pins) for each (keyword, value) pair. The tiering analog of decorate_source: the benchmarks UI injects these to pin an optimization to a tier exactly as it injects ## No <X> to disable one. value is one of eager|t1|t2|t3|never.
pin_from_str: Parse one pin value: eager, never, or a tier token (see [parse_tier]). The surface the ## Tier <opt> <value> parser and LOGOS_TIER_PIN both resolve.
relationship_tree: The complete optimization chain for one program, derived deterministically from a single all-optimizations-on evaluation plus the static registry graph — no differential toggling in the hot path. fired is the set that fired; preempted is the (winner, loser) BLOCKER pairs that occurred; dependencies is the (dependent, dep) per-program DEPENDENCY pairs (one optimization only fired because another was on) — all three come from the baked per-program graph (compile::optimization_graph).