Struct MetalCapture 

pub struct MetalCapture { /* private fields */ }

A live programmatic capture session backed by an MTLCaptureScope.

Construct via MetalCapture::from_env. Pair begin / end calls around the unit of work to capture (e.g. a single forward pass). Drop runs end defensively in case the caller forgets, so a panic mid-forward-pass still flushes a partial trace.

Implementations

impl MetalCapture

pub fn from_env(device: &MlxDevice) -> Option<Self>

Initialize a capture from the env vars MLX_METAL_CAPTURE (output path) and METAL_CAPTURE_ENABLED (Apple’s framework-level permission gate).

Returns Some(MetalCapture) only when ALL of:

1. MLX_METAL_CAPTURE is set to a non-empty path,
2. The capture manager supports MTLCaptureDestination::GpuTraceDocument,
3. start_capture succeeds (which requires METAL_CAPTURE_ENABLED=1 or running under Xcode), and
4. The process-global one-shot latch [CAPTURE_CONSUMED] has not yet flipped to true.

On any failure path returns None after a one-shot stderr warning describing the cause. The caller is expected to ignore the None and proceed without capture — never panic.

pub fn begin(&mut self)

Open the capture scope. Idempotent: a second begin without an intervening end is a no-op so callers can wrap nested forward passes safely.

Call at the start of the unit of work to capture (e.g. GraphExecutor::begin — see graph.rs wire-up).

pub fn end(&mut self)

Close the capture scope and stop the underlying MTLCaptureManager. After end returns the .gputrace file is finalized and openable in Xcode.

Idempotent. Calling end without a preceding begin is a no-op (defensive — ensures Drop after a panic between construction and begin doesn’t endScope an unopened scope).

Trait Implementations

impl Drop for MetalCapture

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.