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).

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", "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).

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. 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). Callers time kernels on a concrete device, so include anything else that distinguishes performance environments in backend (e.g. a device id) if needed.

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.

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.

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.