Trait DeviceRuntime 

pub trait DeviceRuntime:
    Send
    + Sync
    + 'static {
    type Buffer: Send + Sync + 'static;
    type Stream: Send + 'static;
    type Command: Send + 'static;
    type Fence: Send + 'static;
    type Error: Error + Send + Sync + 'static;

    // Required methods
    fn descriptor(&self) -> &DeviceDescriptor;
    fn attention_execution_policy(&self) -> AttentionExecutionPolicy;
    fn allocate(
        &self,
        permit: DeviceAllocationPermit<'_>,
    ) -> Result<Self::Buffer, Self::Error>;
    fn buffer_descriptor(&self, buffer: &Self::Buffer) -> BufferDescriptor;
    fn create_stream(&self) -> Result<Self::Stream, Self::Error>;
    fn stream_state(&self, stream: &Self::Stream) -> StreamState;
    fn encode_copy(
        &self,
        source: &Self::Buffer,
        destination: &Self::Buffer,
        region: CopyRegion,
    ) -> Result<Self::Command, Self::Error>;
    fn encode_upload(
        &self,
        source: &[u8],
        source_layout: HostTransferLayout,
        destination: &Self::Buffer,
        destination_offset_bytes: u64,
    ) -> Result<Self::Command, Self::Error>;
    fn encode_zero(
        &self,
        destination: &Self::Buffer,
        destination_offset_bytes: u64,
        length_bytes: u64,
    ) -> Result<Self::Command, Self::Error>;
    fn submit(
        &self,
        stream: &mut Self::Stream,
        commands: DeviceCommandBatch<Self::Command>,
    ) -> Result<Self::Fence, DefinitelyNotSubmitted<Self::Error>>;
    fn query_fence(&self, fence: &Self::Fence) -> FenceQuery<Self::Error>;
    fn wait_fence(
        &self,
        fence: &Self::Fence,
    ) -> Result<DeviceTerminalReceipt<Self::Error>, FenceIndeterminate<Self::Error>>;
    fn synchronize(&self, stream: &mut Self::Stream) -> Result<(), Self::Error>;
    fn readback(
        &self,
        stream: &mut Self::Stream,
        source: &Self::Buffer,
        region: CopyRegion,
        output_layout: HostTransferLayout,
    ) -> Result<Vec<u8>, Self::Error>;
    fn describe_error(
        &self,
        error: &Self::Error,
    ) -> Result<DeviceErrorReport, VNextError>;

    // Provided methods
    fn begin_static_weight_import(
        &self,
    ) -> Option<Result<Box<dyn StaticWeightImportSession<Self::Buffer, Self::Error> + '_>, Self::Error>> { ... }
    fn configure_reusable_executables(
        &self,
        _stream: &mut Self::Stream,
        _plan: DeviceReusableExecutionPlan,
    ) -> Result<DeviceReusableExecutionPreparation, Self::Error> { ... }
    fn seal_reusable_executables(
        &self,
        _stream: &mut Self::Stream,
    ) -> Result<DeviceReusableExecutionPreparation, Self::Error> { ... }
    fn reusable_executable_preparation(
        &self,
        _stream: &Self::Stream,
    ) -> Result<DeviceReusableExecutionPreparation, Self::Error> { ... }
    fn reusable_execution_catalog(
        &self,
        _stream: &Self::Stream,
    ) -> Result<Vec<DeviceReusableExecutionProgram>, Self::Error> { ... }
    fn encode_reusable_execution(
        &self,
        _invocation: DeviceReusableExecutionInvocation,
    ) -> Result<Option<Self::Command>, Self::Error> { ... }
    fn trim_reusable_executables(
        &self,
        _stream: &mut Self::Stream,
    ) -> Result<DeviceReusableExecutionTrim, Self::Error> { ... }
    fn coalesce_program_bindings(
        &self,
        commands: Vec<Self::Command>,
    ) -> Result<Vec<Self::Command>, Self::Error> { ... }
    fn submit_with_timing<S>(
        &self,
        stream: &mut Self::Stream,
        commands: DeviceCommandBatch<Self::Command>,
        timing_sink: &S,
    ) -> Result<Self::Fence, DefinitelyNotSubmitted<Self::Error>>
       where Self: Sized,
             S: DeviceSubmissionTimingSink { ... }
    fn submission_attribution(
        &self,
        _fence: &Self::Fence,
    ) -> Option<DeviceSubmissionAttribution> { ... }
}

Stable primitive boundary implemented by a concrete device runtime.

Associated buffer, stream, command, and error types preserve compile-time type safety. Every operation is required; unsupported work cannot inherit a success-returning default implementation.

Required Associated Types

type Buffer: Send + Sync + 'static

type Stream: Send + 'static

type Command: Send + 'static

type Fence: Send + 'static

type Error: Error + Send + Sync + 'static

Required Methods

fn descriptor(&self) -> &DeviceDescriptor

fn attention_execution_policy(&self) -> AttentionExecutionPolicy

Resolved attention provider-family policy installed by this runtime composition. Auto is never valid after composition.

fn allocate( &self, permit: DeviceAllocationPermit<'_>, ) -> Result<Self::Buffer, Self::Error>

Allocates only after the resource transaction has authorized the exact request. DeviceAllocationPermit has no public constructor and borrows the live transaction context, so raw device allocation cannot bypass admission or outlive the transaction action that authorized it.

fn buffer_descriptor(&self, buffer: &Self::Buffer) -> BufferDescriptor

fn create_stream(&self) -> Result<Self::Stream, Self::Error>

fn stream_state(&self, stream: &Self::Stream) -> StreamState

fn encode_copy( &self, source: &Self::Buffer, destination: &Self::Buffer, region: CopyRegion, ) -> Result<Self::Command, Self::Error>

fn encode_upload( &self, source: &[u8], source_layout: HostTransferLayout, destination: &Self::Buffer, destination_offset_bytes: u64, ) -> Result<Self::Command, Self::Error>

fn encode_zero( &self, destination: &Self::Buffer, destination_offset_bytes: u64, length_bytes: u64, ) -> Result<Self::Command, Self::Error>

fn submit( &self, stream: &mut Self::Stream, commands: DeviceCommandBatch<Self::Command>, ) -> Result<Self::Fence, DefinitelyNotSubmitted<Self::Error>>

Submits one non-empty ordered command batch and returns its exact completion fence. A backend must preserve command order and must not manufacture intermediate host-visible completion boundaries.

The error type is intentionally closed over DefinitelyNotSubmitted: an ordinary backend error is not sufficient evidence that invocation resources may be released or retried. Backends that cannot prove that no work was enqueued must panic or retain/return a fence through their implementation boundary; core treats an unwind as possibly submitted.

fn query_fence(&self, fence: &Self::Fence) -> FenceQuery<Self::Error>

Observes a fence without blocking. Indeterminate is not terminal and therefore cannot release command-owned resources.

fn wait_fence( &self, fence: &Self::Fence, ) -> Result<DeviceTerminalReceipt<Self::Error>, FenceIndeterminate<Self::Error>>

Waits for a quiescent terminal. Failure to prove quiescence retains the fence and every resource reachable from the submitted invocation.

fn synchronize(&self, stream: &mut Self::Stream) -> Result<(), Self::Error>

fn readback( &self, stream: &mut Self::Stream, source: &Self::Buffer, region: CopyRegion, output_layout: HostTransferLayout, ) -> Result<Vec<u8>, Self::Error>

fn describe_error( &self, error: &Self::Error, ) -> Result<DeviceErrorReport, VNextError>

Provided Methods

fn begin_static_weight_import( &self, ) -> Option<Result<Box<dyn StaticWeightImportSession<Self::Buffer, Self::Error> + '_>, Self::Error>>

Begins an optional all-or-nothing static-weight import transaction. Returning None selects the portable zero-and-upload path. The default preserves existing CUDA, CPU, and test runtime behavior.

fn configure_reusable_executables( &self, _stream: &mut Self::Stream, _plan: DeviceReusableExecutionPlan, ) -> Result<DeviceReusableExecutionPreparation, Self::Error>

Opens the bounded cold-path preparation window for one stream. Backends without reusable executable support retain the no-op receipt.

fn seal_reusable_executables( &self, _stream: &mut Self::Stream, ) -> Result<DeviceReusableExecutionPreparation, Self::Error>

Permanently closes the preparation window for this stream. A sealed stream may replay or fall back to eager execution but cannot capture on a later product request.

fn reusable_executable_preparation( &self, _stream: &Self::Stream, ) -> Result<DeviceReusableExecutionPreparation, Self::Error>

Returns the current preparation receipt without changing lifecycle state. Product startup uses two snapshots to prove that its validation pass replayed stable executables instead of compiling more work.

fn reusable_execution_catalog( &self, _stream: &Self::Stream, ) -> Result<Vec<DeviceReusableExecutionProgram>, Self::Error>

Returns the immutable direct-submit catalog after preparation is sealed.

Backends without direct reusable execution return an empty catalog.

fn encode_reusable_execution( &self, _invocation: DeviceReusableExecutionInvocation, ) -> Result<Option<Self::Command>, Self::Error>

Encodes one lightweight reference to a resident reusable segment.

Returning None selects the normal provider encoding path. The reference itself owns no request resources; every dynamic target must be retained by explicit per-wave binding commands and the completion fence.

fn trim_reusable_executables( &self, _stream: &mut Self::Stream, ) -> Result<DeviceReusableExecutionTrim, Self::Error>

Releases reusable executable cache entries on a proven-quiescent stream. Backends without such a cache retain the no-op default.

fn coalesce_program_bindings( &self, commands: Vec<Self::Command>, ) -> Result<Vec<Self::Command>, Self::Error>

Coalesces independent provider binding writes into a wave prelude.

The default preserves one command per provider. Backends may return a smaller ordered set, but must retain every command-owned resource and preserve the exact enqueue order and failure semantics.

fn submit_with_timing<S>( &self, stream: &mut Self::Stream, commands: DeviceCommandBatch<Self::Command>, timing_sink: &S, ) -> Result<Self::Fence, DefinitelyNotSubmitted<Self::Error>>

where Self: Sized, S: DeviceSubmissionTimingSink,

Profile-attached submission entrypoint. Backends override this only when they can expose typed internal boundaries without changing submission ownership or error semantics.

fn submission_attribution( &self, _fence: &Self::Fence, ) -> Option<DeviceSubmissionAttribution>

Returns backend-observed native work for an already submitted fence. Attribution may be requested explicitly for correctness evidence or by a diagnostic timing mode. The returned rows never grant completion or resource-release authority.

Dyn Compatibility

This trait is dyn compatible.

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

Implementors