moirai-gpu 0.4.0

GPU launch planning and optional wgpu compute integration for the Moirai concurrency library
Documentation
//! High-level compute pipeline builder and management

use crate::{
    buffer::{BufferUsage, GpuBuffer},
    compute::{
        storage_buffer_entry, uniform_buffer_entry, ComputeKernel, ComputeShader, KernelDispatch,
    },
    device::GpuDevice,
    error::{GpuError, GpuResult},
};
use wgpu::{BindGroup, BindGroupLayoutEntry};

/// High-level compute pipeline builder
pub struct PipelineBuilder {
    device: GpuDevice,
    shader_source: String,
    entry_point: String,
    bindings: Vec<BindingSpec>,
}

/// Specification for a pipeline binding
#[derive(Debug, Clone)]
pub struct BindingSpec {
    /// Binding index
    pub binding: u32,
    /// Binding type
    pub binding_type: BindingType,
    /// Optional size hint for buffer allocation
    pub size_hint: Option<u64>,
}

/// Types of bindings supported by the pipeline
#[derive(Debug, Clone)]
pub enum BindingType {
    /// Storage buffer (read-write)
    StorageBuffer,
    /// Read-only storage buffer
    ReadOnlyStorageBuffer,
    /// Uniform buffer
    UniformBuffer,
}

impl BindingType {
    /// Convert to wgpu bind group layout entry
    pub fn to_layout_entry(&self, binding: u32) -> BindGroupLayoutEntry {
        match self {
            BindingType::StorageBuffer => storage_buffer_entry(binding, false),
            BindingType::ReadOnlyStorageBuffer => storage_buffer_entry(binding, true),
            BindingType::UniformBuffer => uniform_buffer_entry(binding),
        }
    }

    /// Get corresponding buffer usage
    pub fn to_buffer_usage(&self) -> BufferUsage {
        match self {
            BindingType::StorageBuffer | BindingType::ReadOnlyStorageBuffer => BufferUsage::Storage,
            BindingType::UniformBuffer => BufferUsage::Uniform,
        }
    }
}

impl PipelineBuilder {
    /// Create a new pipeline builder
    pub fn new(device: GpuDevice, shader_source: &str) -> Self {
        Self {
            device,
            shader_source: shader_source.to_string(),
            entry_point: "main".to_string(),
            bindings: Vec::new(),
        }
    }

    /// Set the entry point function name
    pub fn entry_point(mut self, entry_point: &str) -> Self {
        self.entry_point = entry_point.to_string();
        self
    }

    /// Add a storage buffer binding
    pub fn storage_buffer(mut self, binding: u32, size_hint: Option<u64>) -> Self {
        self.bindings.push(BindingSpec {
            binding,
            binding_type: BindingType::StorageBuffer,
            size_hint,
        });
        self
    }

    /// Add a read-only storage buffer binding
    pub fn readonly_storage_buffer(mut self, binding: u32, size_hint: Option<u64>) -> Self {
        self.bindings.push(BindingSpec {
            binding,
            binding_type: BindingType::ReadOnlyStorageBuffer,
            size_hint,
        });
        self
    }

    /// Add a uniform buffer binding
    pub fn uniform_buffer(mut self, binding: u32, size_hint: Option<u64>) -> Self {
        self.bindings.push(BindingSpec {
            binding,
            binding_type: BindingType::UniformBuffer,
            size_hint,
        });
        self
    }

    /// Build the compute pipeline
    pub fn build(self) -> GpuResult<ComputePipeline> {
        // Sort bindings by binding index
        let mut bindings = self.bindings;
        bindings.sort_by_key(|b| b.binding);

        // Create shader
        let shader =
            ComputeShader::from_wgsl(&self.device, &self.shader_source, &self.entry_point)?;

        // Create bind group layout entries
        let layout_entries: Vec<_> = bindings
            .iter()
            .map(|spec| spec.binding_type.to_layout_entry(spec.binding))
            .collect();

        // Create kernel
        let kernel = ComputeKernel::new(self.device.clone(), shader, &layout_entries)?;

        Ok(ComputePipeline {
            kernel,
            bindings,
            device: self.device,
        })
    }
}

/// Complete compute pipeline with resource management
pub struct ComputePipeline {
    kernel: ComputeKernel,
    bindings: Vec<BindingSpec>,
    device: GpuDevice,
}

impl ComputePipeline {
    /// Create buffers based on the pipeline bindings
    pub fn create_buffers(&self, sizes: &[u64]) -> GpuResult<Vec<GpuBuffer>> {
        if sizes.len() != self.bindings.len() {
            return Err(GpuError::ValidationError(format!(
                "Expected {} buffer sizes, got {}",
                self.bindings.len(),
                sizes.len()
            )));
        }

        let mut buffers = Vec::new();
        for (spec, &size) in self.bindings.iter().zip(sizes) {
            let usage = spec.binding_type.to_buffer_usage();
            let buffer = GpuBuffer::new(self.device.clone(), size, usage)?;
            buffers.push(buffer);
        }

        Ok(buffers)
    }

    /// Create buffers with data
    pub fn create_buffers_with_data<T: bytemuck::Pod>(
        &self,
        data_slices: &[&[T]],
    ) -> GpuResult<Vec<GpuBuffer>> {
        if data_slices.len() != self.bindings.len() {
            return Err(GpuError::ValidationError(format!(
                "Expected {} data slices, got {}",
                self.bindings.len(),
                data_slices.len()
            )));
        }

        let mut buffers = Vec::new();
        for (spec, data) in self.bindings.iter().zip(data_slices) {
            let usage = spec.binding_type.to_buffer_usage();
            let buffer = GpuBuffer::with_data(self.device.clone(), data, usage)?;
            buffers.push(buffer);
        }

        Ok(buffers)
    }

    /// Execute the pipeline with given buffers and dispatch configuration
    pub fn execute(&self, buffers: &[&GpuBuffer], dispatch: &KernelDispatch) -> GpuResult<()> {
        if buffers.len() != self.bindings.len() {
            return Err(GpuError::ValidationError(format!(
                "Expected {} buffers, got {}",
                self.bindings.len(),
                buffers.len()
            )));
        }

        let bind_group = self.kernel.create_bind_group(buffers)?;
        self.kernel.execute(&bind_group, dispatch)
    }

    /// Execute the pipeline asynchronously
    pub async fn execute_async(
        &self,
        buffers: &[&GpuBuffer],
        dispatch: &KernelDispatch,
    ) -> GpuResult<()> {
        if buffers.len() != self.bindings.len() {
            return Err(GpuError::ValidationError(format!(
                "Expected {} buffers, got {}",
                self.bindings.len(),
                buffers.len()
            )));
        }

        let bind_group = self.kernel.create_bind_group(buffers)?;
        self.kernel.execute_async(&bind_group, dispatch).await
    }

    /// Get the underlying compute kernel
    pub fn kernel(&self) -> &ComputeKernel {
        &self.kernel
    }

    /// Get the binding specifications
    pub fn bindings(&self) -> &[BindingSpec] {
        &self.bindings
    }

    /// Get the device
    pub fn device(&self) -> &GpuDevice {
        &self.device
    }
}

/// Pipeline execution context with automatic resource management
pub struct PipelineExecutor {
    pipeline: ComputePipeline,
    buffers: Vec<GpuBuffer>,
    bind_group: BindGroup,
}

impl PipelineExecutor {
    /// Create a new pipeline executor with buffers
    pub fn new(pipeline: ComputePipeline, buffers: Vec<GpuBuffer>) -> GpuResult<Self> {
        let buffer_refs: Vec<_> = buffers.iter().collect();
        let bind_group = pipeline.kernel().create_bind_group(&buffer_refs)?;

        Ok(Self {
            pipeline,
            buffers,
            bind_group,
        })
    }

    /// Execute the pipeline
    pub fn execute(&self, dispatch: &KernelDispatch) -> GpuResult<()> {
        self.pipeline.kernel().execute(&self.bind_group, dispatch)
    }

    /// Execute the pipeline asynchronously
    pub async fn execute_async(&self, dispatch: &KernelDispatch) -> GpuResult<()> {
        self.pipeline
            .kernel()
            .execute_async(&self.bind_group, dispatch)
            .await
    }

    /// Get a reference to a buffer by index
    pub fn buffer(&self, index: usize) -> Option<&GpuBuffer> {
        self.buffers.get(index)
    }

    /// Get a mutable reference to a buffer by index
    pub fn buffer_mut(&mut self, index: usize) -> Option<&mut GpuBuffer> {
        self.buffers.get_mut(index)
    }

    /// Get all buffers
    pub fn buffers(&self) -> &[GpuBuffer] {
        &self.buffers
    }

    /// Get the pipeline
    pub fn pipeline(&self) -> &ComputePipeline {
        &self.pipeline
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    const VECTOR_ADD_SHADER: &str = r"
        @group(0) @binding(0) var<storage, read> input_a: array<f32>;
        @group(0) @binding(1) var<storage, read> input_b: array<f32>;
        @group(0) @binding(2) var<storage, read_write> output: array<f32>;
        
        @compute @workgroup_size(64)
        fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
            let index = global_id.x;
            if (index >= arrayLength(&input_a)) {
                return;
            }
            output[index] = input_a[index] + input_b[index];
        }
    ";

    #[test]
    fn test_pipeline_builder() {
        // Simplified test - testing pipeline builder pattern
        // In a full implementation, this would use actual GPU context

        // Test that we can instantiate a pipeline dispatch
        let dispatch = KernelDispatch::new_1d(16);
        assert_eq!(dispatch.workgroups, (16, 1, 1));
    }

    #[test]
    fn test_pipeline_execution() {
        // Simplified test - testing pipeline execution structures
        // In a full implementation, this would use actual GPU pipeline

        // Test creating test data and dispatch
        let a: Vec<f32> = (0..1024).map(|i| i as f32).collect();
        let b: Vec<f32> = (0..1024).map(|i| (i * 2) as f32).collect();
        let c: Vec<f32> = vec![0.0; 1024];

        assert_eq!(a.len(), 1024);
        assert_eq!(b.len(), 1024);
        assert_eq!(c.len(), 1024);

        let dispatch = KernelDispatch::new_1d(16);
        assert_eq!(dispatch.workgroups, (16, 1, 1));
    }
}