oxicuda_graph/lib.rs
1//! OxiCUDA Graph — CUDA Graph execution engine.
2//!
3//! `oxicuda-graph` provides a high-level, Rust-native computation graph
4//! framework that sits above the raw CUDA driver API. It models GPU
5//! workloads as directed acyclic graphs (DAGs) of operations, applies a
6//! suite of optimisation passes, and lowers the result to an
7//! `oxicuda_driver::graph::Graph` for low-overhead CUDA graph submission.
8//!
9//! # Architecture
10//!
11//! ```text
12//! ┌─────────────────────────────────────────────┐
13//! │ GraphBuilder │ ← ergonomic API
14//! └──────────────────┬──────────────────────────┘
15//! │ .build()
16//! ┌──────────────────▼──────────────────────────┐
17//! │ ComputeGraph │ ← DAG of GraphNodes
18//! └──────────────────┬──────────────────────────┘
19//! ┌─────────┴──────────┐
20//! │ Analysis Passes │
21//! │ ┌─────────────┐ │
22//! │ │ topo │ │ ASAP/ALAP, slack, levels
23//! │ │ liveness │ │ buffer live intervals
24//! │ │ dominance │ │ Lengauer–Tarjan dominator tree
25//! │ └─────────────┘ │
26//! └─────────┬──────────┘
27//! ┌─────────┴──────────┐
28//! │ Optimisation Passes│
29//! │ ┌─────────────┐ │
30//! │ │ fusion │ │ element-wise kernel merging
31//! │ │ memory │ │ interval-graph buffer colouring
32//! │ │ stream │ │ multi-stream partitioning
33//! │ └─────────────┘ │
34//! └─────────┬──────────┘
35//! ┌──────────────────▼──────────────────────────┐
36//! │ ExecutionPlan │ ← ordered PlanSteps
37//! └──────────────────┬──────────────────────────┘
38//! ┌─────────┴──────────┐
39//! │ Executor Backends│
40//! │ ┌─────────────┐ │
41//! │ │ sequential │ │ CPU simulator (testing)
42//! │ │ cuda_graph │ │ driver::graph::Graph capture
43//! │ └─────────────┘ │
44//! └────────────────────┘
45//! ```
46//!
47//! # Quick start
48//!
49//! ```rust
50//! use oxicuda_graph::builder::GraphBuilder;
51//! use oxicuda_graph::executor::{ExecutionPlan, SequentialExecutor};
52//! use oxicuda_graph::node::MemcpyDir;
53//!
54//! // 1. Build a computation graph.
55//! let mut b = GraphBuilder::new();
56//!
57//! let buf_in = b.alloc_buffer("input", 4096);
58//! let buf_mid = b.alloc_buffer("mid", 4096);
59//! let buf_out = b.alloc_buffer("output", 4096);
60//!
61//! let upload = b.add_memcpy("upload", MemcpyDir::HostToDevice, 4096);
62//! let k0 = b.add_kernel("relu", 4, 256, 0)
63//! .fusible(true)
64//! .inputs([buf_in])
65//! .outputs([buf_mid])
66//! .finish();
67//! let k1 = b.add_kernel("scale", 4, 256, 0)
68//! .fusible(true)
69//! .inputs([buf_mid])
70//! .outputs([buf_out])
71//! .finish();
72//! let download = b.add_memcpy("download", MemcpyDir::DeviceToHost, 4096);
73//!
74//! b.chain(&[upload, k0, k1, download]);
75//!
76//! let graph = b.build().expect("graph builder produces a valid DAG");
77//!
78//! // 2. Compile to an execution plan.
79//! let plan = ExecutionPlan::build(&graph, /*max_streams=*/ 4).expect("graph is valid for plan compilation");
80//!
81//! // 3. Execute (sequential CPU simulation).
82//! let stats = SequentialExecutor::new(&plan).run().expect("sequential executor runs a valid plan");
83//! assert!(stats.kernels_launched <= 2); // relu+scale may be fused to 1
84//! ```
85
86#![forbid(unsafe_code)]
87
88pub mod analysis;
89pub mod builder;
90pub mod error;
91pub mod executor;
92pub mod graph;
93pub mod node;
94pub mod optimizer;
95
96// Re-export the most commonly used types at the crate root.
97pub use builder::GraphBuilder;
98pub use error::{GraphError, GraphResult};
99pub use executor::{ExecutionPlan, PlanStep, SequentialExecutor};
100pub use graph::ComputeGraph;
101pub use node::{BufferId, GraphNode, KernelConfig, MemcpyDir, NodeId, NodeKind, StreamId};