Module Ir.Schedule_cache

Which fresh symbol of a schedule op a Minted reference names.

A process-independent name for a symbol occurring in a schedule. Base i is the i-th For_loop binder in preorder of the optimized code the schedule applies to; Static k the k-th static index; Minted (op, role) the fresh symbol in role of the op-th (0-based) op of the same saved schedule.

Schedule.optop with symbols replaced by sym_refs and tensor nodes by their canonical first-occurrence index.

The canonical identity of one Low_level.optimized value: the digest, the loop-binder and static-symbol numbering, and the tensor-node numbering.

Walks the optimized code once in preorder, numbering For_loop binders, first-occurrence tensor nodes (their dims, precision, hoisted-packing eligibility Schedule.hoistable_constant — schedule validity depends on operand constancy, gh-ocannl-470 — and effective placement class from the compile's Ir.Low_level.optimize_ctx — identical code over Local scratch vs an On_device buffer generates different kernels, so same-code different-placement programs must not share cache keys — all enter the digest), and rendering the canonical form. with_placements = false omits the placement classes, giving the structural identity: placement classes can render differently across compilation lineages on byte-identical code, so per-segment schedule matching in fissioned replays keys on structure only. The binder/tensor-node numbering is identical either way. static_indices must be the same list the code was lowered with (Indexing.bound_symbols of the compile's bindings).

What one compilation lineage brings to a node's placement decision, as canonicalize_source renders it for its own lineage: the node's effective placement (a prior decision, or the declared intent Tnode.Placements.get falls back to), whether that placement is a heuristic cap's — flippable back by Context.decide_inline, where the same mode imposed by legality or intent is not, so two lineages agreeing on the mode can still pose different refinement surfaces — and the inline / footprint preferences recorded in the lineage's optimize_ctx. Exposed so a caller can tag a further lineage that shapes its decision through node_tag: Train.tune_placements tags the timing context's, whose lineage the arms are measured in.

The identity of the placement decision problem the lowering answered (gh-ocannl-786): the same walk as canonicalize, over the raw program the specialization was decided over (Ir.Low_level.optimized.source) rather than the decided code, with each node tagged by what the lineage brought to the decision (lineage_tag: effective placement, cap flippability, and the inline / footprint preferences of opt's optimize_ctx). lineage is the placements of the CONTEXT the lowering was decided from (Context.placements) — opt's own table holds this specialization's decisions too, which are exactly what a decision recorded against this identity is. Every node the raw code sets or reads is numbered, so a decision can address a node the default policy inlines away from the decided code; tn_of_ref resolves the number back. node_tag adds what the caller's own decision space distinguishes per node — for Train.tune_placements, whether the node is in the loss's embedded set arm B materializes, since two calls over one computation with different losses pose different problems. Used as the key of the placement-decision store.

Hex digest of the canonical rendering. Equal digests mean structurally identical code, hence interchangeable canonical numberings.

false when the code contains constructs the canonical rendering cannot capture (Staged_compilation closures, unbound or shadowed loop symbols). Incomplete canonical forms must not be used as disk-cache keys (distinct programs could collide); within one process they still support to_saved/of_saved round-trips.

The tensor node at a canonical index. Raises Invalid_argument on out-of-range.

Serializes a schedule built against the registry's compile (e.g. by Schedule.default_gpu), recording each op's minted symbols in the returned registry (op indices continue from the number of ops already recorded in the input registry, so extensions of replayed prefixes stay consistent). Raises Invalid_argument when an op references a symbol or tensor node the registry cannot resolve.

Replays a saved schedule against a (fresh) compile's canonical form: base and static references resolve through canonical, minting ops go through the Schedule builders and their fresh symbols are recorded for later references. Raises Invalid_argument on dangling references (canonical mismatch — always guard with digest equality first).

A filename-safe short digest of the current Ir.Numerics policy (Ir.Numerics.get, so it tracks Ir.Numerics.set_policy). The policy is not a property of the code — it is consulted at codegen and by the autotune tile-shape choice — so it cannot enter digest, yet a schedule tuned under one policy must never replay under another (gh-ocannl-568: a default-flags run replaying a tf32-tuned tensorized winner measured 5.9x slower than not tuning at all, its mma rendering degraded to the scalar fallback). Hence it enters cache_key and entry.

A filename-safe short digest of the codegen environment (gh-ocannl-572): everything consulted when a kernel is rendered, compiled or dispatched, which happens after the lowered code that digest names — so, exactly like numerics_tag, these are invisible to the digest while changing the kernel or what a timing measures, and a winner crowned under one such regime must not replay under another. Three layers: the process-wide gates (the index and pool-slot width large_models, buffer_aliasing's restrict suppression, and the effective routine-logging predicate — which includes the log_level > 1 threshold, so a verbosity bump alone never churns keys — together with the settings that only matter once logging reaches the kernel (prefer_backend_uniformity's logging spelling, the stream-log routing); the whole limits record, which describes the device candidates are generated, rendered and timed against; and, inside it, the backend's own Ir.Backend_intf.hardware_limits.codegen_tag.

Bumped when the canonical rendering or the saved-schedule format changes; stale entries are ignored by lookup.

The autotuner's configured timing objective (autotune_timing), normalized to the spelling a cache key carries (gh-ocannl-755). What cache_key uses when its caller supplies none — so a caller with no resolved mode of its own keys against the one a search in this process would use, rather than restating a default that could drift. An unknown spelling passes through: the setting is validated where it is acted on, and this only has to keep unlike regimes apart.

The named components a cache_key is built from, in order: "digest", "backend", "numerics", "codegen", "pool", "device", "timing". The list drives cache_key rather than describing it, so it is a complete and current enumeration of the cache's identity — which is what the digest-completeness registry classifies configuration keys against (gh-ocannl-572, test/operations/digest_completeness).

None if the concrete timing identity is unavailable; all cache I/O with None is a no-op, including directory creation, locking and regime changes. Otherwise a filename-safe cache key: the digest, the backend name, numerics_tag of the current numerics policy, codegen_tag of the codegen configuration (including limits.codegen_tag, the compiling backend's own contribution), the worker-pool signature (limits.worker_pool_tag, gh-ocannl-530: CPU crowns do not transfer across pools), and the autotuner's timing objective (objective, defaulting to objective_tag).

The objective is a key component because the two objectives crown DIFFERENT candidates (gh-ocannl-755, measured): an entry crowned under isolated timing is not the answer to a search asking about queued timing, and the times it stores are readings of a different quantity, which a replay would copy into the reading process's report under its own label. CUDA/HIP queued keys carry policy generation 2 (gh-ocannl-892), invalidating winners measured under the old depth-200/short-batch regime without invalidating the unchanged cc/Metal regimes. objective is for the caller that resolved a mode explicitly rather than from configuration (Autotune.tune's ?timing); everyone else wants the default. The backend-supplied components arrive as the whole limits record rather than one optional argument each, so a component added there reaches every call site instead of defaulting to absent at the ones that were not updated (gh-ocannl-572). The mandatory timing_identity separately identifies concrete device capabilities and optional observed toolchain metadata; it does not change construction limits or promise complete runtime/driver provenance.

Version of the filename-key regime recorded once per cache directory (gh-ocannl-835). Bump it when the schema of key_components changes. This is independent of entry_version, which versions the payload stored at one key.

The directory-local file containing cache_regime_version. Exposed as part of the on-disk cache format, including for tools and synthetic cache-directory tests; callers should not edit a live cache's stamp.

The permanent record-lock file shared by cache-opening processes. Exposed as part of the on-disk cache format for synthetic cache-directory tests; callers must never unlink a live cache's lock file.

Writes the entry to dir/key.sexp, creating dir (and parents) if missing. Publication goes through Utils.Atomic_file, so concurrent writers tolerate each other (last write wins) and a failed write or commit removes its own staging artifact and leaves an earlier complete entry intact. Before writing, cache-open serializes participating processes on a permanent lock file: an older or absent regime stamp sweeps every .sexp entry and is atomically replaced by the current stamp; a malformed or newer stamp refuses the operation without changing its stamp or entries. Holding that lock through the write prevents a concurrent regime transition from deleting the new entry. A filesystem refusal is not propagated: the cache is an optimization, and an entry that could not be written is a future miss rather than a failed run.

None on missing file, unparsable content, version/digest mismatch, or a refused cache-open. Process-level failures (Out_of_memory, Sys.Break, Stack_overflow) propagate rather than reading as a miss (gh-ocannl-786): an interrupt during a lookup must not start the search the lookup was about to spare.

Together with store this participates in the same permanent record lock and regime-stamp protocol described there, and sweeps the cache directory's crash-stale staging files (Utils.Atomic_file.cleanup_stale_once) once per directory per process. Every participating reader and writer holds the lock through its entry I/O, so same-version processes race benignly and an older participating binary refuses after a newer one advances the stamp. The OS releases the record lock on process death; the lock file is never unlinked, avoiding an inode-replacement race. A binary predating this protocol does not participate and must not share a live directory during an upgrade.

One accepted flip of the greedy inline refinement: the node by its canonicalize_source index, and the direction (Context.decide_materialized / Context.decide_inline / Context.decide_footprint).

What shipped: arm A as the default policy decided it, arm B with every embedded node of the loss materialized (re-derived from the loss at replay, so the nodes need no structural address), or arm A refined by the accepted flips in chain order.

Bumped when placement_entry or canonicalize_source's rendering changes; stale entries are ignored by lookup_placements.

cache_key over a canonicalize_source identity, in the placement store's own filename space.

store's protocol, for a placement entry.

lookup's protocol, for a placement entry.

The on_ship label of a decision: "A", "B" or "flip".