trueno_db/
lib.rs

1//! # Trueno-DB: GPU-First Embedded Analytics Database
2//!
3//! **Version**: 0.1.0 (Phase 1 MVP)
4//!
5//! Trueno-DB is a GPU-aware, compute-intensity-based embedded analytics database
6//! designed for high-performance aggregations with graceful degradation from
7//! GPU → SIMD → Scalar.
8//!
9//! ## Design Principles (Toyota Way Aligned)
10//!
11//! - **Muda elimination**: Kernel fusion minimizes `PCIe` transfers
12//! - **Poka-Yoke safety**: Out-of-core execution prevents VRAM OOM
13//! - **Genchi Genbutsu**: Physics-based cost model (5x rule for GPU dispatch)
14//! - **Jidoka**: Backend equivalence tests (GPU == SIMD == Scalar)
15//!
16//! ## Example Usage (Phase 1 MVP)
17//!
18//! ```rust,no_run
19//! use trueno_db::storage::StorageEngine;
20//!
21//! // Load Parquet file
22//! let storage = StorageEngine::load_parquet("data/events.parquet")?;
23//!
24//! // Iterate over 128MB morsels (out-of-core execution)
25//! for morsel in storage.morsels() {
26//!     println!("Morsel: {} rows", morsel.num_rows());
27//! }
28//! # Ok::<(), Box<dyn std::error::Error>>(())
29//! ```
30
31#![warn(missing_docs)]
32#![warn(clippy::all)]
33#![warn(clippy::pedantic)]
34#![warn(clippy::nursery)]
35
36pub mod backend;
37pub mod error;
38#[cfg(feature = "gpu")]
39pub mod gpu;
40pub mod query;
41pub mod storage;
42pub mod topk;
43
44pub use error::{Error, Result};
45
46/// Database instance
47pub struct Database {
48    _private: (),
49}
50
51/// Backend selection strategy
52#[derive(Debug, Clone, Copy)]
53pub enum Backend {
54    /// Cost-based dispatch (arithmetic intensity)
55    CostBased,
56    /// Force GPU execution
57    Gpu,
58    /// Force SIMD execution
59    Simd,
60}
61
62impl Database {
63    /// Create a new database builder
64    #[must_use]
65    pub fn builder() -> DatabaseBuilder {
66        DatabaseBuilder::default()
67    }
68}
69
70/// Database builder
71#[derive(Default)]
72pub struct DatabaseBuilder {
73    _private: (),
74}
75
76impl DatabaseBuilder {
77    /// Set backend selection strategy
78    #[must_use]
79    pub const fn backend(self, _backend: Backend) -> Self {
80        self
81    }
82
83    /// Set morsel size for out-of-core execution (Poka-Yoke)
84    #[must_use]
85    pub const fn morsel_size_mb(self, _size: usize) -> Self {
86        self
87    }
88
89    /// Build the database
90    ///
91    /// # Errors
92    ///
93    /// Returns error if GPU initialization fails
94    pub const fn build(self) -> Result<Database> {
95        Ok(Database { _private: () })
96    }
97}
trueno_db/lib.rs

trueno_db/
lib.rs
