Trait Driver 

pub trait Driver: Sized {
    type Backend: EventStreamBackend<Stream = Self::Stream>;
    type Stream: DeviceStream;
    type Context;
    type LaunchArgs: ?Sized;

    // Required methods
    unsafe fn pinned_bytes(
        binding: ManagedMemoryBinding,
        resource: HostResource<Self>,
        size: usize,
    ) -> Bytes;
    unsafe fn copy_to_host(
        resource: &DeviceResource<Self>,
        layout: &CopyLayout<'_>,
        bytes: &mut Bytes,
        stream: &Self::Stream,
    ) -> Result<(), IoError>;
    unsafe fn copy_to_device(
        resource: &DeviceResource<Self>,
        layout: &CopyLayout<'_>,
        data: &[u8],
        stream: &Self::Stream,
    ) -> Result<(), IoError>;
    unsafe fn copy_on_device(
        source: &DeviceResource<Self>,
        target: &DeviceResource<Self>,
        queue: <Self::Stream as DeviceStream>::Signal,
    ) -> Result<(), IoError>;
    fn launch(
        ctx: &mut Self::Context,
        stream: &mut Self::Stream,
        kernel: KernelId,
        count: (u32, u32, u32),
        args: &mut Self::LaunchArgs,
    ) -> Result<(), LaunchError>;

    // Provided method
    fn wait_outside_streams(_ctx: &mut Self::Context) -> Result<(), ServerError> { ... }
}

The device calls a Command cannot make itself.

Only these, because everything else a command does — deciding what to stage, when to reclaim, whether a layout needs a 2D copy, when the drop queue may be flushed — is the same whichever driver is underneath.

Required Associated Types

type Backend: EventStreamBackend<Stream = Self::Stream>

The multi-stream backend whose streams this driver drives.

type Stream: DeviceStream

The backend’s stream.

type Context

Whatever the backend needs to launch a compiled kernel — its loaded modules, its profiling clocks.

type LaunchArgs: ?Sized

What this backend hands a kernel at launch.

Not simply the buffers: CUDA passes tensor-map descriptors alongside them and HIP has none, so what a launch is given is the backend’s to say. The command only carries it from the server to launch.

Required Methods

unsafe fn pinned_bytes( binding: ManagedMemoryBinding, resource: HostResource<Self>, size: usize, ) -> Bytes

Hand out size bytes of the pinned host allocation binding names, released back to the pool when the Bytes drop.

Safety

binding names initialized host memory of at least size bytes, and resource resolves it.

unsafe fn copy_to_host( resource: &DeviceResource<Self>, layout: &CopyLayout<'_>, bytes: &mut Bytes, stream: &Self::Stream, ) -> Result<(), IoError>

Enqueue a copy from device memory into bytes on stream.

Safety

resource is a live device allocation of at least bytes.len() readable bytes, bytes has room for the copy, and the caller synchronizes stream before reading it back.

Errors

The driver’s refusal to copy.

unsafe fn copy_to_device( resource: &DeviceResource<Self>, layout: &CopyLayout<'_>, data: &[u8], stream: &Self::Stream, ) -> Result<(), IoError>

Enqueue a copy of data into device memory on stream.

Safety

resource is a live device allocation big enough for data, and data stays alive until stream is synchronized — which is what the caller’s drop queue guarantees.

Errors

The driver’s refusal to copy.

unsafe fn copy_on_device( source: &DeviceResource<Self>, target: &DeviceResource<Self>, queue: <Self::Stream as DeviceStream>::Signal, ) -> Result<(), IoError>

Enqueue a copy of source’s bytes into target on stream, both device memory of the same size — how a live allocation is relocated off an outdated page.

Safety

Both resources are live device allocations of the same size that do not overlap, and nothing reads target or writes source until the caller synchronizes stream.

Errors

The driver’s refusal to copy.

fn launch( ctx: &mut Self::Context, stream: &mut Self::Stream, kernel: KernelId, count: (u32, u32, u32), args: &mut Self::LaunchArgs, ) -> Result<(), LaunchError>

Enqueue an already-compiled kernel on stream.

Always a compiled kernel: the server compiles before entering its write scope, and a skipped launch stops there, before any resource is resolved.

Errors

The driver’s refusal to enqueue the launch.

Provided Methods

fn wait_outside_streams(_ctx: &mut Self::Context) -> Result<(), ServerError>

Wait for device work enqueued outside the command’s streams — CUDA’s collectives, on a stream of their own that the compute streams only wait on at a collective sync — before a relocation moves the allocations that work may still read or write.

Nothing by default: a backend whose every device operation runs on its command streams has nothing else to wait on.

Errors

The driver’s refusal to synchronize.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors