aruminium — API specification

pure Rust driver for Apple Metal GPU. direct objc_msgSend FFI, zero external dependencies, only macOS system frameworks.

concepts

lifecycle

source  ->  compile  ->  pipeline  ->  encode  ->  commit  ->  complete
  MSL      MTLLibrary   pipeline    encoder    cmdBuf      GPU done

device

apple mapping

buffer

CPU/GPU memory region. two storage modes:

• shared (default) — zero-copy, CPU and GPU share physical memory. no lock/unlock needed. contents pointer cached at creation.
• private — GPU-only, higher bandwidth for inter-kernel buffers. CPU cannot read/write. use blit encoder to copy data in/out.

apple mapping

library

compiled shader code from MSL source text.

apple mapping

function

a single shader entry point extracted from a library.

compute pipeline

compiled GPU state — function + hardware config.

apple mapping

command queue

overhead hierarchy (low to high):

commands_autoreleased   — zero overhead, requires pool
commands_unchecked      — no null check, unretained refs
commands_fast           — unretained refs, null checked
commands_unretained     — autoreleased, null checked
commands                — retained, safe, standard

apple mapping

command buffer

apple mapping

compute encoder

apple mapping

blit encoder

apple mapping

compute dispatcher

pre-resolved IMP dispatch engine for inference hot loops. resolves all ObjC method implementations at construction — every dispatch call goes through direct function pointers, bypassing objc_msgSend entirely.

batch

provided to batch closures. same IMP-resolved hot path.

gpu future

handle for committed but not yet completed command buffer.

pipelining pattern

let mut prev = None;
for pass in passes {
    let handle = disp.batch_async(|batch| { ... });
    if let Some(h) = prev { h.wait(); }
    prev = Some(handle);
}
if let Some(h) = prev { h.wait(); }

overlap GPU execution of batch N with CPU encoding of batch N+1.

texture

GPU image data. wraps id<MTLTexture>.

apple mapping

synchronization

fence

GPU work tracking within a single command buffer.

event

synchronization between command buffers on same device.

shared event

CPU/GPU synchronization with monotonic counter.

conversion

fp16<->f32 via inline NEON assembly (aarch64) with software fallback.

tail: 8/iter NEON, then scalar fallback.

autorelease pool

autorelease_pool(|| {
    // autoreleased ObjC objects valid here
})

required when using unretained/autoreleased command buffer and encoder variants.

errors

DeviceNotFound              no Metal GPU available
BufferCreationFailed(String) buffer allocation failed
LibraryCompilationFailed(String) MSL compilation error
FunctionNotFound(String)    shader function not in library
PipelineCreationFailed(String) pipeline creation error
CommandBufferError(String)  command buffer execution error
EncoderCreationFailed       encoder creation failed
QueueCreationFailed         command queue creation failed
TextureCreationFailed(String) texture creation failed
Io(io::Error)               filesystem error

execution model

• one pipeline = one compiled shader function
• command buffers submitted atomically via commit
• GPU executes command buffers in order per queue
• multiple queues enable concurrent GPU work
• shared buffers need no synchronization between command buffer boundaries
• private buffers need blit encoder for CPU data transfer
• dispatch_threads handles non-uniform grids automatically
• dispatch_threadgroups requires manual grid division
• Dispatch bypasses objc_msgSend for hot-loop performance

driver stack

aruminium crate (objc_msgSend FFI + IMP resolution)
  -> Metal.framework (linked at build time)
    -> GPU driver
      -> GPU hardware

Metal.framework is public. linked via #[link(name = "Metal", kind = "framework")]. core path: objc_msgSend with transmuted function pointers. hot path: pre-resolved IMP via class_getMethodImplementation.

render pipeline

RenderPipeline struct exists (wraps id<MTLRenderPipelineState>). no render encoder yet — compute-only driver.