Last updated: 2026-09-07
Metal Runtime
Metal Command
Metal command buffer wrapper — dispatch recording and GPU synchronization.
This module is the low-level bridge between ZINC's compute dispatchers and the Objective-C Metal shim. It records compute work, barriers, and timing mode so higher-level inference code can stay backend-agnostic.
4 exports shown
enum
CommandEncoderMode
pub const CommandEncoderMode = enum(u8)Encoder policy used when opening a Metal compute command buffer.
struct
MetalCommand
pub const MetalCommand = structA recorded command buffer that encodes compute dispatches for the GPU.
Methods
14method
MetalCommand.setTimingLabel
pub fn setTimingLabel(self: *MetalCommand, label: []const u8) voidAttach a one-dispatch timing label consumed by `ZINC_METAL_KERNEL_TIMING`.
The timing aggregator copies the bytes before this label can go stale.
method
MetalCommand.clearTimingLabel
pub fn clearTimingLabel(self: *MetalCommand) voidNo public doc comment yet.
method
MetalCommand.dispatch
pub fn dispatch( self: *MetalCommand, pipe: *const MetalPipeline, grid: [3]u32, block: [3]u32, bufs: []const *const MetalBuffer, push_data: ?*const anyopaque, push_size: usize, ) voidEncode a compute dispatch binding buffers, push constants, grid, and block sizes.
method
MetalCommand.dispatchV2
pub fn dispatchV2( self: *MetalCommand, pipe: *const MetalPipeline, grid: [3]u32, block: [3]u32, bufs: []const *const MetalBuffer, push_data: ?*const anyopaque, push_size: usize, push_idx: u32, ) voidDispatch with explicit push constant buffer index.
SPIRV-Cross compiled shaders place push constants at a specific buffer index (often 0 or 1). Data buffers in `bufs` are bound at all other indices in order, skipping push_idx.
method
MetalCommand.dispatchV2WithTgMem
pub fn dispatchV2WithTgMem( self: *MetalCommand, pipe: *const MetalPipeline, grid: [3]u32, block: [3]u32, bufs: []const *const MetalBuffer, push_data: ?*const anyopaque, push_size: usize, push_idx: u32, tg_mem_size: u32, ) voidDispatch with explicit threadgroup memory allocation.
method
MetalCommand.barrier
pub fn barrier(self: *MetalCommand) voidInsert a memory barrier ensuring all prior dispatches complete before subsequent ones.
method
MetalCommand.barrierBuffers
pub fn barrierBuffers(self: *MetalCommand, bufs: []const *const MetalBuffer) voidInsert a resource-scoped memory barrier for the listed buffers.
method
MetalCommand.barrierResourceBuffers
pub fn barrierResourceBuffers(self: *MetalCommand, bufs: []const *const MetalBuffer) voidInsert a true resource-scoped barrier.
Use only when later work depends on the listed buffers and independent prior dispatches should stay free to overlap on a concurrent encoder.
method
MetalCommand.commitAndWait
pub fn commitAndWait(self: *MetalCommand) voidCommit the command buffer to the GPU and block until execution completes.
method
MetalCommand.commitAsync
pub fn commitAsync(self: *MetalCommand) voidCommit the command buffer for async GPU execution; call `wait` later to synchronize.
method
MetalCommand.wait
pub fn wait(self: *MetalCommand) voidBlock until an async-committed command buffer finishes execution.
method
MetalCommand.waitGpuDurationNs
pub fn waitGpuDurationNs(self: *MetalCommand) u64Wait for completion and return Metal's GPU execution duration.
method
MetalCommand.releaseCompleted
pub fn releaseCompleted(self: *MetalCommand) voidRelease an async command buffer that is known to be completed by a later queue-ordered wait.
The shim falls back to waiting if it is still pending.
method
MetalCommand.gpuDurationNs
pub fn gpuDurationNs(self: *const MetalCommand) u64Return Metal-reported GPU execution time for a completed async command.
function
beginCommand
pub fn beginCommand(ctx: ?*shim.MetalCtx) !MetalCommandAllocate a new command buffer from the given Metal context.
function
beginCommandWithMode
pub fn beginCommandWithMode(ctx: ?*shim.MetalCtx, mode: CommandEncoderMode) !MetalCommandAllocate a command buffer using the requested encoder/barrier policy.