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.

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

commit_then, but the GPU gets the work only once Deferred::commit is called (or the Deferred is dropped). The command buffer takes its place in the queue now: command buffers committed later run after it. Work that waits on the GPU for an event the CPU may raise late is committed this way once the event is raised, so the GPU never waits for it (Metal fails a command buffer that waits for seconds).

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.