Module Tolk_metal

Metal GPU device backend.

Tolk_metal provides a Tolk.Device.t that executes compiled kernels on Apple Metal GPUs. Construct a device with create and interact with it through the Tolk.Device interface.

For batched multi-kernel execution, Icb encodes a sequence of compute dispatches into a Metal indirect command buffer that can be replayed with a single GPU submission.

Kernel compilation

Kernels are compiled in two stages. The compiler first attempts offline compilation via Apple's private MTLCompiler framework (source to MTLB binary). When that framework is unavailable, it falls back to runtime source compilation through the Metal API.

Environment variables

  • METAL_FAST_MATH — when set to a non-zero integer, enables fast-math mode for runtime source compilation (the fallback path). Defaults to 0 (disabled).

Device

val create : string -> Tolk.Device.t

create name is a Metal device identified by name.

The device uses the system default Metal GPU, an LRU-cached shared-memory allocator with blit-based buffer transfers, and a Metal renderer built from the device's Metal GPU family. An Stdlib.at_exit handler synchronizes in-flight work and releases the underlying Metal device, command queue, and shared event.

Raises Failure if no Metal GPU is available (e.g. running in a VM or on unsupported hardware).

Device state

module State : sig ... end

Indirect command buffers

An indirect command buffer (ICB) pre-encodes a fixed sequence of compute dispatches that can be replayed with a single GPU submission. Buffers and dispatch dimensions can be updated between replays without re-encoding the full command sequence.

Typical usage:

  1. Icb.create to allocate the ICB.
  2. Icb.encode for each kernel in the batch.
  3. Icb.execute to submit.
  4. Icb.update_buffer / Icb.update_dispatch then Icb.execute for subsequent iterations.
  5. Icb.release when done.
module Icb : sig ... end