Module Tolk.Realize

Common dispatch interface.

optimize_local_size ~device prg global_size rawbufs finds the local workgroup size that minimises execution time for prg with global_size.

Enumerates all valid local sizes (each dimension drawn from powers of two up to 1024, total product at most 1024), tries each twice in random order, and returns the fastest.

When the first buffer in rawbufs also appears later in the list, a temporary buffer is allocated to avoid clobbering output during measurement.

Raises Invalid_argument if every candidate fails.

Kernel compilation and dispatch.

buffer_copy ~device ~total_sz ~dest_device ~src_device is a runner that copies data between buffers. It uses the destination allocator's native transfer hook when Device.Buffer.supports_transfer holds, otherwise it falls back to a host-memory bounce. dest_device and src_device are device names used in the display string.

Raises Invalid_argument if the two buffers differ in size or dtype, or if the argument list does not contain exactly two buffers.

pm_compile ~device ~to_program linear rewrites every kernel Tolk_uop.Ops.t.Call in linear whose body is a Tolk_uop.Ops.t.Sink into a call whose body is the compiled Tolk_uop.Ops.t.Program returned by to_program. Tolk_uop.Ops.t.Slice and Tolk_uop.Ops.t.Copy calls are left unchanged.

Compiled programs are cached by the kernel's semantic key and the device, so kernels that differ only by diagnostic tags share one compilation.

capturing is the schedule-capture registry. While non-empty, Schedule.create_linear_with_vars hands each linearized schedule and its variable bindings to the head entry and returns an empty Tolk_uop.Ops.t.Linear instead of planning the schedule for execution. Jit.call installs its capturer here for the duration of the capture run.

The type for concrete buffers named by call arguments.

Maps buffer UOps to concrete device buffers.

Execution context threaded through a LINEAR run: symbolic variable values, the input buffer nodes that Tolk_uop.Ops.t.Param slots index into, and the JIT and wait flags.

exec_context ?var_vals ?input_uops ?jit ?wait () builds a context. All fields default to empty or false.

resolve_buffer binding ctx node is the concrete buffer named by call argument node: a Tolk_uop.Ops.t.Param resolves through ctx.input_uops; a Tolk_uop.Ops.t.Slice is an offset view of its resolved source (per underlying device when the source is multi-device); a Tolk_uop.Ops.t.Buffer is resolved through binding; a Tolk_uop.Ops.t.Mselect indexes one shard of its multi-device source; a Tolk_uop.Ops.t.Mstack joins its per-device sources into a multi-device buffer.

Raises Invalid_argument on an unbound parameter, a symbolic slice offset, or a node that does not name a buffer.

resolve binding ctx node is resolve_buffer for a node that names a single-device buffer.

Raises Invalid_argument if node names a multi-device buffer, and in the resolve_buffer failure cases.

run_linear ~device ~to_program binding ?var_vals ?input_uops ?jit ?wait linear executes each Tolk_uop.Ops.t.Call in the Tolk_uop.Ops.t.Linear linear in order.

When jit is false (default), linear is first compiled with pm_compile, turning each kernel Tolk_uop.Ops.t.Sink body into a Tolk_uop.Ops.t.Program; when jit is true, linear is assumed already compiled. Each call is then dispatched on its body: a Tolk_uop.Ops.t.Program is launched with launch dimensions and scalar arguments read from its Tolk_uop.Uop.program_info and a device handle built from its compiled binary; a Tolk_uop.Ops.t.Slice binds a view of its resolved source into binding; a Tolk_uop.Ops.t.Copy transfers between its resolved buffers; a Tolk_uop.Ops.t.Custom_function named "graph" records its LINEAR body into the device's Device.Graph on first execution and replays that graph afterwards, patching per run every buffer argument whose resolution changed (arguments reaching a Tolk_uop.Ops.t.Param slot or a binding reseeded through Buffers.seed), variable values, and symbolic launch dimensions. Buffer arguments are resolved with resolve_buffer, so Tolk_uop.Ops.t.Param slots index into input_uops.

A call whose arguments resolve to multi-device buffers executes once per device position: a kernel launches its one compiled program on each device with the device index bound to the _device_num variable, and a copy transfers each per-device pair (natively when the devices share a backend, through a host bounce otherwise).

wait is forced to true when DEBUG >= 2.

graph_launches counts batched graph launches dispatched through Device.Graph execs, including each graph's recording launch. A cumulative observability counter for tests and debugging.