pub mod accel_op;
pub mod cpu;
pub mod detect;
pub mod registry;
#[cfg(feature = "cuda-reference")]
pub mod cuda;
#[cfg(feature = "tpu-jax-reference")]
pub mod tpu_jax;
#[cfg(feature = "wasm-reference")]
pub mod wasm;
#[cfg(feature = "shared-memory-worker-reference")]
pub mod shared_mem;
use std::sync::Arc;
pub use cpu::CpuBackend;
pub use registry::{
backend_by_id, backends, cpu_backend, ensure_default_registered, register_backend,
};
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub enum Backend {
Cpu,
Cuda {
device_id: u32,
},
Rocm {
device_id: u32,
},
Metal {
device_id: u32,
},
Tpu {
device_id: u32,
},
Ane,
Wasm {
device_id: u32,
},
SharedMemoryWorker {
backend_id: u32,
},
Custom(u32),
}
impl Backend {
pub fn name(&self) -> &'static str {
match self {
Backend::Cpu => "cpu",
Backend::Cuda { .. } => "cuda",
Backend::Rocm { .. } => "rocm",
Backend::Metal { .. } => "metal",
Backend::Tpu { .. } => "tpu",
Backend::Ane => "ane",
Backend::Wasm { .. } => "wasm",
Backend::SharedMemoryWorker { .. } => "shared-mem",
Backend::Custom(_) => "custom",
}
}
pub fn is_simt(&self) -> bool {
matches!(
self,
Backend::Cuda { .. }
| Backend::Rocm { .. }
| Backend::Metal { .. }
| Backend::Tpu { .. }
)
}
}
#[derive(Copy, Clone, Debug)]
pub struct BackendCapabilities {
pub simt_width: u32,
pub max_threads_in_flight: u32,
pub launch_latency_ns: u32,
pub h2d_bw_bytes_per_sec: u64,
}
impl BackendCapabilities {
pub fn cpu_defaults() -> Self {
let threads = std::thread::available_parallelism()
.map(std::num::NonZeroUsize::get)
.unwrap_or(1) as u32;
Self {
simt_width: 1,
max_threads_in_flight: threads,
launch_latency_ns: 100,
h2d_bw_bytes_per_sec: 0,
}
}
}
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub struct KernelHandle(pub u64);
#[derive(Copy, Clone, Debug)]
pub enum KernelArg<'a> {
I32(i32),
I64(i64),
U32(u32),
U64(u64),
F32(f32),
F64(f64),
DevicePtr(usize),
HostSlice(&'a [u8]),
Buffer(&'a dyn DeviceArg),
}
pub trait DeviceArg: Send + Sync + std::fmt::Debug {
fn as_any(&self) -> &dyn std::any::Any;
}
#[derive(Debug, Clone)]
pub enum BackendError {
NotSupported,
DeviceUnavailable(Backend),
KernelCompile(String),
Launch(String),
Memory(String),
}
impl std::fmt::Display for BackendError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
BackendError::NotSupported => f.write_str("backend operation not supported"),
BackendError::DeviceUnavailable(b) => {
write!(f, "backend device unavailable: {}", b.name())
}
BackendError::KernelCompile(msg) => write!(f, "kernel compile failed: {msg}"),
BackendError::Launch(msg) => write!(f, "kernel launch failed: {msg}"),
BackendError::Memory(msg) => write!(f, "backend memory error: {msg}"),
}
}
}
impl std::error::Error for BackendError {}
pub trait DispatchBackend: Send + Sync + 'static {
fn id(&self) -> Backend;
fn capabilities(&self) -> BackendCapabilities;
fn dispatch_parallel_for(&self, count: u32, work: &(dyn Fn(u32) + Send + Sync));
fn dispatch_one(&self, work: Box<dyn FnOnce() + Send>);
fn register_kernel(
&self,
_name: &str,
_source: &[u8],
) -> Result<KernelHandle, BackendError> {
Err(BackendError::NotSupported)
}
fn dispatch_kernel(
&self,
_handle: KernelHandle,
_count: u32,
_args: &[KernelArg<'_>],
) -> Result<(), BackendError> {
Err(BackendError::NotSupported)
}
fn dispatch_kernel_sync(
&self,
handle: KernelHandle,
count: u32,
args: &[KernelArg<'_>],
) -> Result<(), BackendError> {
self.dispatch_kernel(handle, count, args)
}
}
pub type BackendRef = Arc<dyn DispatchBackend>;
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn backend_names_are_stable() {
assert_eq!(Backend::Cpu.name(), "cpu");
assert_eq!(Backend::Cuda { device_id: 0 }.name(), "cuda");
assert_eq!(Backend::Rocm { device_id: 0 }.name(), "rocm");
assert_eq!(Backend::Metal { device_id: 0 }.name(), "metal");
assert_eq!(Backend::Tpu { device_id: 0 }.name(), "tpu");
assert_eq!(Backend::Ane.name(), "ane");
assert_eq!(Backend::Wasm { device_id: 0 }.name(), "wasm");
assert_eq!(
Backend::SharedMemoryWorker { backend_id: 0 }.name(),
"shared-mem"
);
assert_eq!(Backend::Custom(42).name(), "custom");
}
#[test]
fn simt_classification_matches_taxonomy() {
assert!(!Backend::Cpu.is_simt());
assert!(!Backend::Ane.is_simt());
assert!(Backend::Cuda { device_id: 0 }.is_simt());
assert!(Backend::Rocm { device_id: 0 }.is_simt());
assert!(Backend::Metal { device_id: 0 }.is_simt());
assert!(Backend::Tpu { device_id: 0 }.is_simt());
assert!(!Backend::Wasm { device_id: 0 }.is_simt());
assert!(!Backend::SharedMemoryWorker { backend_id: 0 }.is_simt());
assert!(!Backend::Custom(0).is_simt());
}
#[test]
fn cpu_capabilities_report_host_thread_count() {
let caps = BackendCapabilities::cpu_defaults();
assert_eq!(caps.simt_width, 1);
assert!(caps.max_threads_in_flight >= 1);
assert_eq!(caps.h2d_bw_bytes_per_sec, 0);
assert!(caps.launch_latency_ns > 0);
}
#[test]
fn backend_error_display_is_non_empty() {
let errors = [
BackendError::NotSupported,
BackendError::DeviceUnavailable(Backend::Cuda { device_id: 0 }),
BackendError::KernelCompile("syntax".into()),
BackendError::Launch("oom".into()),
BackendError::Memory("invalid ptr".into()),
];
for e in errors {
assert!(!format!("{e}").is_empty());
}
}
}