perdix 0.1.0

High-performance GPU-accelerated ring buffer for AI terminal multiplexing
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

//! # Runtime Module - Dynamic CUDA Kernel Compilation
//! 
//! This module provides runtime compilation of CUDA kernels using NVRTC (NVIDIA Runtime Compilation).
//! This approach bypasses traditional nvcc/MSVC toolchain conflicts and enables dynamic kernel
//! optimization based on runtime parameters.
//! 
//! ## Key Components
//! 
//! - **NVRTC Compilation**: Compiles CUDA C++ source to PTX at runtime
//! - **Dynamic Loading**: Loads compiled PTX modules into CUDA context
//! - **Parameter Binding**: Safe parameter passing to GPU kernels
//! - **Error Handling**: Comprehensive error reporting with line numbers
//! 
//! ## Architecture
//! 
//! ```text
//! ┌─────────────────┐
//! │  CUDA C++ Source│
//! └────────┬────────┘
//!          │
//!          ▼
//! ┌─────────────────┐
//! │  NVRTC Compiler │  Runtime compilation
//! └────────┬────────┘
//!          │
//!          ▼
//! ┌─────────────────┐
//! │   PTX Assembly  │
//! └────────┬────────┘
//!          │
//!          ▼
//! ┌─────────────────┐
//! │  CUDA Module    │  Loaded into GPU
//! └────────┬────────┘
//!          │
//!          ▼
//! ┌─────────────────┐
//! │ Kernel Function │  Ready for launch
//! └─────────────────┘
//! ```
//! 
//! ## Benefits
//! 
//! 1. **Toolchain Independence**: No dependency on nvcc or Visual Studio
//! 2. **Runtime Optimization**: Kernels optimized for specific GPU architecture
//! 3. **Dynamic Specialization**: Template parameters resolved at runtime
//! 4. **Hot Reload**: Kernels can be recompiled without restarting
//! 
//! ## Example
//! 
//! ```rust,no_run
//! use perdix::runtime::{CudaRuntimeCompiler, get_kernel_source};
//! 
//! // Get kernel source with configuration
//! let kernel_info = get_kernel_source(256, 32, true);
//! 
//! // Compile to PTX
//! let mut compiler = CudaRuntimeCompiler::new();
//! let ptx = compiler.compile(&kernel_info.source, &kernel_info.name)?;
//! 
//! // Load module and get function
//! let module = compiler.load_ptx(&ptx)?;
//! let function = module.get_function("produce_messages")?;
//! 
//! // Launch kernel
//! function.launch(grid_size, block_size, shared_mem, stream)?;
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```

pub mod cuda_params;
pub mod jit;
pub mod kernel_source;
pub mod runtime_compiler;

pub use cuda_params::CudaParams;
pub use jit::JITRuntime;
pub use kernel_source::{get_kernel_source, KernelInfo};
pub use runtime_compiler::{CompilerError, CudaFunction, CudaModule, CudaRuntimeCompiler};

/// High-level runtime system for Perdix GPU operations.
/// 
/// Combines all runtime components into a unified interface for kernel
/// compilation, loading, and execution.
/// 
/// # Components
/// 
/// - `params`: CUDA kernel parameter management
/// - `runtime`: JIT compilation runtime
/// - `compiler`: NVRTC compiler interface
/// - `kernel_info`: Compiled kernel metadata
/// - `error`: Last compilation error (if any)
/// 
/// # Usage
/// 
/// This struct is typically used internally by the GPU producer.
/// Direct usage is for advanced scenarios requiring custom kernel compilation.
pub struct PerdixRuntime {
    pub params: CudaParams,
    pub runtime: JITRuntime,
    pub compiler: CudaRuntimeCompiler,
    pub kernel_info: KernelInfo,
    pub error: CompilerError,
}