Module Ir.Kernel_code_cache

capacity_bytes is read on every publish and find, so a configuration read lazily by the caller applies from first use.

The hex digest of parts, each length-prefixed, so no two different lists collide by concatenation.

publish c ~entries ~bytes retains each value under its key, as one group of bytes (the caller's weight: compiled bytes where the backend can measure them), evicting the oldest groups while the retained total exceeds the capacity. The values of one group typically share one compiled program and differ in the symbol each kernel was compiled under. A key already present is re-pointed; the older group then no longer owns it, and its eviction leaves it be.

Exposed for tests (gh-ocannl-1700): runs f with every cache this process has created -- every backend's -- emptied, so a compile inside reuses nothing an earlier compile published, then puts back on return or exception what each one held on entry, discarding what f published (a cache created inside ends empty). A value handed out inside stays valid, as after an eviction. Scopes nest. Not for a compile running concurrently on another domain: that one may publish into a cache while it is being restored. A test that needs a cold cache uses this rather than compiling something no earlier compile of the process rendered.

programs_for split n is how many programs n kernels of one option list compile as: min max_programs (n / min_kernels), at least 1, at most n.

chunks k idxs is idxs cut into k contiguous runs, balanced by count (the first t * n / k .. (t + 1) * n / k for each t), empty runs dropped.

Runs f with split in place of whatever a backend's configuration would give (current_split_override), for tests that compare a split compile with a whole one in one process.

A backend that can split its compiles records each compile, whether or not it split -- with its kernel code cache disabled too -- so a test gates its split claims on split_capable_compiles rather than on a backend name.

Programs resolve has compiled through its concurrent path in this process.

One batch's kernels, by index: keys.(i) is kernel i's key, options.(i) the compiler option list it compiles under, symbols.(i) the name the current rendering gives it. Answers, per kernel, the program holding its code and the symbol to look it up by -- the symbol it was compiled under, which a hit may have taken from another name (gh-ocannl-1525: the key does not depend on a segment kernel's positional index, kernel_token).

Every kernel is looked up first without lock; if any missed, the misses are looked up again under it (another domain may just have published them) and the remaining ones compiled there: one representative per distinct key (the first in batch order; the others share its program and symbol), grouped by option list in batch order, compile_group ~group:k ~n_groups opts idxs once per group, returning the program and its weight. A group is published only after its compile returned, so one that raises publishes nothing (earlier groups stay published) and the exception propagates; the next compile of those kernels compiles them afresh. before_compile runs under the lock ahead of the compiles, also when nothing is left to compile -- which happens under the lock only with always_lock (a caller that writes per-compile artifacts even for an all-hit batch). The kernels the lookups answered are added to the enclosing Compile_cost.with_census's kernels_reused, once per call (gh-ocannl-1667).

With concurrent (gh-ocannl-1603), each option list's representatives are cut into programs_for concurrent.split chunks. When none is cut, the compile is the one above, through compile_group. When any is, every program of the batch -- numbered in batch order, n_groups counting them all -- is prepared, then compiled at once (the first on the calling domain, the others on domains of their own, every one joined before resolve returns or raises), still under lock; then each one that succeeded is finished and published in batch order, and the first failure in batch order goes to reraise with its backtrace. So the partition changes neither a key nor a published value's meaning: a kernel's program holds its own code under its own option list, beside fewer companions.

The name a fissioned routine's segment kernel i is given (Backends: <routine>__seg<i>).

What a kernel's own name contributes to its canonical text: the name without the positional index segment_kernel_name appends (<routine>__seg<i> becomes <routine>__seg); any other name as it is. The routine's name stays in the key because it can decide whether the text compiles at all -- a routine named after a declaration the prelude's headers make is refused -- and a hit must not answer for text that would not compile; the segment index never can, and a candidate that adds or removes a segment shifts every later one's (gh-ocannl-1525).

canonical_kernel kernel_text is the text a kernel's key is taken over: one kernel's C text with the names it OWNS renamed to ocannl_k<n>, numbered by first occurrence, and its own name (when kernel_name is given) replaced by its kernel_token. The renamed tokens are:

• a loop or static-index symbol as Ir.Indexing.symbol_ident spells it (i then digits);
• a scope-local (v, digits, _, anything), suffix included;
• a name in bound: what the renderer declares for the kernel's tensor nodes (parameters, locals), bare or disambiguated;
• a name derived from one of those by a derivations template (prefix, suffix) -- prefix ^ base ^ suffix with base in bound, a symbol, or digits -- the emitter's own derived locals (C_syntax.minted_derivations).

Never renamed: a name in keep or free; an identifier after ., -> or :: (a member or a qualified name); anything inside [[...]] (an attribute), a preprocessor line, or a string or character literal. If bound meets free, or holds a name in the implementation's reserved namespace (__x, _X) -- a node declared under a name that is also a language, builtin, vendor or predefined-macro name, whose other occurrences might be its free meaning, as with a macro, which no declaration shadows -- no bound name is renamed: such a kernel may not compile at all, and its key must not reach the code of a twin that did.

Why this is sound: every renamed name is bound in the kernel (declared there, and a declaration shadows any outer meaning of its name throughout its scope; parameters are passed by position; the kernel is looked up through the symbol the cache stores), and distinct tokens get distinct names, so two kernels whose canonical texts are equal are equal up to a renaming of their own bindings, which neither their meaning nor their machine code depends on. Comments are renamed like code.

Why (gh-ocannl-1314, gh-ocannl-1525): symbols, scope ids and minted tile nodes come from process-wide counters, node names are disambiguated over the whole batch (n<id>_<label> whenever a label repeats), and segment kernels are named by position, so two candidates of one search render an unchanged kernel with other names. A difference in anything else costs a miss, never a wrong hit.