Struct CommandBuffer 

pub struct CommandBuffer { /* private fields */ }

Work being recorded for the GPU: one concurrent compute encoder, with memory barriers inserted only where a dispatch depends on an earlier one.

Implementations

impl CommandBuffer

pub unsafe fn dispatch( &mut self, pipeline: &Pipeline, args: &[Arg<'_>], threads: usize, ) -> Result<()>

Encodes pipeline over threads threads (a 1-D grid) with args bound to slots 0..args.len(). The threadgroup size is derived from the pipeline’s limits.

Arguments are validated (slot count, inline size, offsets within their buffers, Arg::Same targets, ordering with other command buffers), but what the kernel does with them is not: nuvec cannot see which elements a kernel touches.

Safety

The kernel, run over this grid, must access each bound buffer only within its length from the bound offset (and write only the buffers bound with Arg::Write or Arg::Same). An out-of-bounds access reads or writes memory that other buffers, possibly referenced by safe code, own.

pub unsafe fn dispatch_groups( &mut self, pipeline: &Pipeline, args: &[Arg<'_>], groups: [usize; 3], threads: [usize; 3], ) -> Result<()>

Encodes pipeline over a grid of groups threadgroups of threads threads each, for kernels that cooperate within a threadgroup (reductions, tiled matrix products).

Safety

As for dispatch: the kernel must access each bound buffer only within its length from the bound offset.

pub unsafe fn dispatch_threads( &mut self, pipeline: &Pipeline, args: &[Arg<'_>], grid: [usize; 3], group: [usize; 3], ) -> Result<()>

Encodes pipeline over exactly grid threads in up to three dimensions, in threadgroups of group threads (the edge threadgroups are partial).

Safety

As for dispatch: the kernel must access each bound buffer only within its length from the bound offset.

pub fn barriers(&self) -> usize

Memory barriers inserted so far.

pub fn signal_event(&mut self, event: &Event, value: u64)

Raises event to value once the GPU has finished the work encoded so far in this command buffer (Event::wait waits for it on the CPU).

pub fn wait_event(&mut self, event: &Event, value: u64)

Makes the work encoded after this call wait on the GPU until event reaches value (the CPU raises it with Event::signal).

pub fn commit(self) -> Submitted

Submits the work to the GPU. Dropping the returned Submitted waits for it and discards its result; Submitted::wait reports GPU errors.

pub fn commit_then( self, on_complete: impl FnOnce(Result<()>) + Send + 'static, ) -> Pending

Submits the work and returns at once. on_complete runs exactly once with the command buffer’s result: on a Metal thread when the GPU finishes, or earlier on the thread that calls Pending::wait.

on_complete must not block, in particular not on other GPU work: Metal runs a queue’s completion handlers one at a time, so waiting there for another command buffer’s completion can deadlock. A panic in on_complete on Metal’s thread is caught and reported on standard error, so it never aborts the process; the result is still published to Pending::wait.

Trait Implementations

impl Drop for CommandBuffer

fn drop(&mut self)

Abandoned work is never submitted; release the buffers’ guards. (Metal objects are released in an autorelease pool: their deallocation may autorelease others.)

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.