Struct GpuCommandBatch 

pub struct GpuCommandBatch { /* private fields */ }

Command batch for async GPU execution

Accumulates GPU operations and executes them together to minimize CPU↔GPU data transfers.

Implementations

impl GpuCommandBatch

pub async fn execute(&mut self) -> Result<(), String>

Execute all queued operations on GPU

Uses a single command encoder for all operations (one GPU submission) and caches pipelines per shader source to avoid redundant compilation. The pipeline cache is local to this call — see execute_with_cache() for persistent caching across multiple batch executions.

Contract (C-BATCH-EXEC-001)

• Precondition: Operations queued via matmul(), relu(), etc.
• Postcondition: All operations executed, results in GPU buffers
• Invariant: Pipeline compiled at most once per unique shader source
• Invariant: Single queue.submit() per execute() call

pub async fn execute_with_cache( &mut self, cache: &mut PipelineCache, ) -> Result<(), String>

Execute with a persistent pipeline cache (KAIZEN-023).

Same as execute() but uses a caller-provided pipeline cache that persists across multiple batch executions. Shaders compiled in a previous batch are reused without recompilation.

For Qwen3-4B FFN (36 layers × 3 unique shaders per batch):

• execute(): 3 compilations per layer × 36 = 108 total
• execute_with_cache(): 3 compilations (layer 1) + 0 (layers 2-36) = 3 total

pub async fn read(&self, buffer_id: BufferId) -> Result<Vec<f32>, String>

Read buffer data back from GPU

Must call execute() first.

impl GpuCommandBatch

pub fn new(device: GpuDevice) -> Self

Create a new command batch

pub fn upload(&mut self, data: &[f32]) -> BufferId

Upload data to GPU (queued for batch execution)

Returns a buffer ID that can be used in subsequent operations.

pub fn relu(&mut self, input: BufferId) -> BufferId

Queue ReLU operation: max(0, x)

Returns buffer ID for the output.

pub fn scale(&mut self, input: BufferId, scalar: f32) -> BufferId

Queue scalar multiplication: x * scalar

Returns buffer ID for the output.

pub fn add(&mut self, a: BufferId, b: BufferId) -> BufferId

Queue element-wise addition: a + b

Returns buffer ID for the output.

Panics

Panics if buffers have different sizes.

pub fn mul(&mut self, a: BufferId, b: BufferId) -> BufferId

Queue element-wise multiplication: a * b

Returns buffer ID for the output.

Panics

Panics if buffers have different sizes.

pub fn dot(&mut self, a: BufferId, b: BufferId) -> BufferId

Queue dot product: sum(a[i] * b[i])

Returns buffer ID for a single-element output buffer.

Panics

Panics if buffers have different sizes.

pub fn sigmoid(&mut self, input: BufferId) -> BufferId

Queue sigmoid activation: 1 / (1 + exp(-x))

Returns buffer ID for the output.

pub fn tanh(&mut self, input: BufferId) -> BufferId

Queue hyperbolic tangent: tanh(x)

Returns buffer ID for the output.

pub fn swish(&mut self, input: BufferId) -> BufferId

Queue Swish activation: x * sigmoid(x)

Returns buffer ID for the output.

pub fn gelu(&mut self, input: BufferId) -> BufferId

Queue GELU activation: x * Φ(x)

Returns buffer ID for the output.

pub fn sub(&mut self, a: BufferId, b: BufferId) -> BufferId

Queue element-wise subtraction: a - b

Returns buffer ID for the output.

Panics

Panics if buffers have different sizes.

pub fn matmul( &mut self, a: BufferId, b: BufferId, m: u32, k: u32, n: u32, ) -> BufferId

Queue matrix multiplication: C = A × B

A is M×K elements, B is K×N elements, output is M×N elements. All matrices are row-major flat arrays.

Returns buffer ID for the M×N output.

Panics

Panics if buffer sizes don’t match the declared dimensions.

pub fn import_buffer(&mut self, buffer: Arc<Buffer>, size: usize) -> BufferId

Import a pre-existing GPU buffer for use in batch operations.

Unlike upload() which copies host data to GPU during execute(), imported buffers are already GPU-resident and skip the upload step. The Arc wrapper allows the same buffer to be shared across multiple batch executions without re-uploading (KAIZEN-015: GPU-resident weights).

Contract (C-BATCH-IMPORT-001)

• Precondition: buffer is a valid wgpu::Buffer with STORAGE | COPY_SRC usage
• Postcondition: Returned BufferId can be used in all batch operations (matmul, etc.)
• Invariant: Imported buffer is NOT destroyed when the batch is dropped — the Arc keeps it alive as long as the caller retains a clone

pub fn wgpu_device(&self) -> &Device

Get the underlying wgpu device for creating persistent buffers.

Used to create wgpu::Buffer instances that outlive individual batch executions. Created buffers can be registered via import_buffer().

pub fn wgpu_queue(&self) -> &Queue

Get the underlying wgpu queue for writing to persistent buffers.

pub fn num_operations(&self) -> usize

Get number of queued operations

pub fn num_buffers(&self) -> usize

Get number of buffers