Module Context.Backends

gh-ocannl-344 pool-allocator planner. Lays out (size, alignment) allocations (in order) into pools so no pool's bumped extent exceeds cap bytes (the uint32 4 GB per-pool ceiling when large_models = false). Returns each item's (segment_index, byte_offset) and the byte size of each segment. Raises Ir.Utils.User_error (naming what and debug_name i) when a single item exceeds cap. Exposed for unit testing the segmenting/cap behavior with synthetic sizes.

gh-ocannl-489 liveness-aware pool layout: lays out (size, alignment, precision_class, live_span) allocations into ONE pool where two allocations may overlap iff both carry a live span, the spans are disjoint (closed intervals) and the precision classes are equal. A None span means always-live (conflicts with everything). Greedy by decreasing size, deterministic. Returns per-item byte offsets (in input order) and the pool's total size, or None when the layout exceeds cap (callers fall back to plan_pool_segments). Exposed for unit testing the coloring with synthetic sizes.

gh-ocannl-498: score the peak footprint of a lowered routine under its own placements, with the same machinery the allocator uses — the default schedule and fission, the gh-ocannl-489 live spans, and plan_arena_offsets over the working group. This is the cost side Ir.Low_level.flip_candidates does not carry: the recompute-cost bound says what inlining a node costs, this says what it saves. Meaningful only with config buffer_aliasing on; without it every node is always-live and the score degenerates to bump packing.

Scored over the routine's whole in-context node set rather than a context's allocation delta, so the number depends only on the code and the placements — the precondition for a deterministic selector (Memory_budget.fit). It is therefore a model of the peak, not a prediction of Context.get_used_memory: the real allocator skips nodes a prior context already holds, and the driver page-rounds pool bases. Enumeration is canonical (by Ir.Tnode.t.uid) so the greedy coloring is reproducible across processes.

Frees the pools that are specific to the context -- not contained in the parent context, and not per-device constants. Idempotent (guarded by the context's finalized flag), and freeing is per-pool_id rather than per-node: one pool holds several nodes. If cleanup raises after a strict prefix of pools, retry skips that prefix and frees only the remainder.

This is NOT optional if the memory matters (gh-ocannl-550, correcting the note that used to stand here). A pool's backend buffer is never garbage-collected, because the backend's private (device_id, pool_id) -> base table is a module-level strong root holding every slab it allocated; dropping that entry -- which only this function does -- is what makes the buffer collectable at all (and eagerly frees it where the backend has a raw deallocator). Measured: a schedule search accumulated one unfreed pool per candidate to 12 GB while the OCaml GC ran normally throughout, unloading code modules (which sit behind no such table) as it went.

Context.release is the front-end entry point; prefer it over calling this directly.

The shared lowering front half of backend compile: forks the lineage state (Low_level.copy_optimize_ctx, so the compile's decisions stay hermetic), derives the routine name, wires the debug-file callbacks, and runs Assignments.lower. Exposed for analyze-only consumers (gh-560: Context.decision_surface) that read the optimized code's decision surface without backend codegen.

The implemented backends. Constructors statically imply the corresponding singleton module (Cc -> Cc_b, ...).

enumerate derives all_of_backend, every backend OCANNL has, so that a check wanting "the set of backends" reads it off the type instead of restating it. The vocabulary of the ; ocannl-backend: dune marker is such a check: test/operations/marker_backend_vocabulary holds it equal to List.map all_of_backend ~f:backend_name plus "none", which is what stops it agreeing with a list that has stopped being this one (gh-ocannl-689).

The backend corresponding to backend_name, or if omitted, selected via the global backend setting. Non-generative: the same backend value (hence the same singleton state) each call.

Inverse of get_backend's name parsing.

The singleton module as an existentially-packed first-class module, for generic consumers that thread a single backend through (the raw-API tests, Parallel). Code that must re-correlate two contexts later (e.g. Context.copy) should use wrapped_context instead: this projection erases the type components.

A backend singleton's module at known type components -- the package type the generic dispatchers here are written against, and the annotation a ctx_op/ctx_query closure needs to unpack its module argument.

Everything a wrapped_context constructor statically implies: which backend it is, its singleton module at that constructor's type components, and the constructor itself (to rebuild the wrapper around a derived context). One record per backend, so the correspondence Cc_ctx <-> Cc <-> Cc_b is written once rather than once per dispatcher.

A wrapped context with its type components recovered as locally abstract types.

Two wrapped contexts correlated: Same_backend recovers the type equality that lets a same-backend transfer dispatch to the backend's device_to_device, while Cross_backend is every mismatched pair.

The backend_impl the backend constructor implies.

The backend_impl and backend context a wrapped context carries.

Correlate two wrapped contexts, recovering their type equality when they come from the same backend. Context.copy is the caller: a same-backend pair can dispatch to device_to_device, a cross-backend one must go through a host round-trip.

A fresh root context (empty optimize_ctx) on the backend's device ordinal (default 0). Raises when the backend's hardware or library is unavailable.

A context-transforming backend operation, polymorphic over the backend's type components so with_backend can rebuild the same wrapped_context constructor around the result.

A read-only backend operation; like ctx_op but leaves the context untouched.