Struct Command 

pub struct Command<'a, D: Driver> { /* private fields */ }

One unit of work against the device: the context that holds its compiled kernels, and the streams it was resolved against.

Built per operation rather than held, because resolving is what orders the current stream behind whichever streams own the buffers it was given.

Implementations

impl<'a, D: Driver> Command<'a, D>

pub fn new( ctx: &'a mut D::Context, streams: ResolvedStreams<'a, D::Backend>, service: ServiceId, ) -> Self

A command against ctx over the streams streams resolved.

pub fn stream(&mut self) -> &mut D::Stream

The stream this command is issued on.

The one part of the resolution a backend reaches for directly: the driver calls take a stream, and this is the one they take.

pub fn resource( &mut self, binding: BufferBinding, ) -> Result<DeviceResource<D>, IoError>

The device allocation binding names, resolved on the stream that created it rather than the current one.

Errors

IoError::StorageHandleNotFound when the binding names no live allocation.

pub fn memory_usage(&mut self) -> MemoryUsage

The current stream’s device memory usage.

pub fn memory_report(&mut self) -> MemoryReport

Structured per-pool report of the current stream’s device memory.

pub fn memory_cleanup(&mut self)

Release everything the current stream is holding that nothing still needs.

pub fn flush_drops(&mut self)

Flush the current stream’s drop queue, freeing what the device is known to be done with.

Deferred while the stream records a graph — the flush records a fence on the capturing stream, which corrupts the recording — and the window drains the queue itself when it closes. The rule lives here, on the one path a server has to the queue, so no call site can rebuild the flush without the guard.

pub fn allocation_mode(&mut self, mode: MemoryAllocationMode)

Set the MemoryAllocationMode for the current stream.

pub fn install_memory_pools( &mut self, config: MemoryConfiguration, props: &MemoryDeviceProperties, ) -> Result<(), InstallMemoryPoolsError>

Rebuild the current stream’s device pools with a new layout, keeping the old one when something is still live in them.

Errors

InstallMemoryPoolsError::PoolsInUse when the rebuild was refused.

pub fn reserve(&mut self, size: u64) -> Result<ManagedMemoryHandle, IoError>

Allocate size bytes of device memory on the current stream.

Errors

IoError::BufferTooBig when no device could ever fit it, and whatever the allocator reports when a reclaim-and-retry still cannot.

pub fn cursor(&self) -> u64

The current stream’s cursor.

pub fn empty(&mut self, size: u64) -> Result<Handle, IoError>

Allocate size bytes of device memory and a handle naming it.

Errors

Whatever the allocation or the bind reports.

pub fn bind( &mut self, reserved: ManagedMemoryHandle, new: ManagedMemoryHandle, ) -> Result<(), IoError>

Give reserved’s storage to new, so handles issued against new resolve to it.

Errors

IoError when the reservation has no initialized storage to give.

pub fn reserve_cpu(&mut self, size: usize, origin: Option<StreamId>) -> Bytes

size bytes of host memory, pinned when the pool can serve it.

Pinned pages transfer by DMA without a bounce, but they are scarce, so an exhausted pool falls back to the heap rather than failing: this always answers with a buffer of the size asked for.

pub fn read_async( &mut self, descriptors: Vec<CopyDescriptor>, ) -> impl Future<Output = Result<Vec<Bytes>, ServerError>> + Send + use<D>

Copy each descriptor’s device memory back to the host, resolving once the copies have landed.

The copies are enqueued before the future is returned; awaiting it waits on the fence that follows them.

Errors

IoError::UnsupportedStrides for a layout the driver cannot copy, and whatever the fence reports when the stream itself failed.

pub fn write_to_cpu( &mut self, descriptor: CopyDescriptor, bytes: &mut Bytes, stream_id: Option<StreamId>, ) -> Result<(), IoError>

Enqueue a copy of descriptor’s device memory into bytes.

Errors

IoError::UnsupportedStrides for a layout that is not pitched row-major, IoError::StorageHandleNotFound for a binding that names no live allocation, and the driver’s refusal to copy.

pub fn write_to_gpu( &mut self, descriptor: CopyDescriptor, data: Bytes, ) -> Result<(), IoError>

Enqueue a copy of data into the device memory descriptor names.

Errors

IoError::UnsupportedStrides for a layout that is not pitched row-major, IoError::StorageHandleNotFound for a binding that names no live allocation, and the driver’s refusal to copy.

pub fn create_with_data(&mut self, data: &[u8]) -> Result<Handle, IoError>

Allocate device memory for data and enqueue the copy into it.

Errors

Whatever the allocation or the copy reports.

pub fn sync(&mut self) -> DynFut<Result<(), ServerError>>

Wait for everything already enqueued on the current stream to finish.

Errors

The fault the barrier reveals, when the stream itself failed.

pub fn kernel( &mut self, kernel: KernelId, count: (u32, u32, u32), args: &mut D::LaunchArgs, ) -> Result<(), LaunchError>

Enqueue an already-compiled kernel on the current stream.

Errors

The driver’s refusal to enqueue the launch, returned whether or not a profile is open. An open profile is not a reason to hold the failure here: the caller’s write scope is what claims the buffers the launch never wrote, and the caller invalidates every open profile on the same path, so keeping it would lose the claim and duplicate the report.