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;
38pub mod experiment;
39#[cfg(feature = "gpu")]
40pub mod gpu;
41pub mod kv;
42pub mod query;
43pub mod storage;
44pub mod topk;
45#[cfg(all(target_arch = "wasm32", feature = "wasm"))]
46pub mod wasm;
47
48pub use error::{Error, Result};
49
50/// Database instance
51pub struct Database {
52    _private: (),
53}
54
55/// Backend selection strategy
56#[derive(Debug, Clone, Copy)]
57pub enum Backend {
58    /// Cost-based dispatch (arithmetic intensity)
59    CostBased,
60    /// Force GPU execution
61    Gpu,
62    /// Force SIMD execution
63    Simd,
64}
65
66impl Database {
67    /// Create a new database builder
68    #[must_use]
69    pub fn builder() -> DatabaseBuilder {
70        DatabaseBuilder::default()
71    }
72}
73
74/// Database builder
75#[derive(Default)]
76pub struct DatabaseBuilder {
77    _private: (),
78}
79
80impl DatabaseBuilder {
81    /// Set backend selection strategy
82    #[must_use]
83    pub const fn backend(self, _backend: Backend) -> Self {
84        self
85    }
86
87    /// Set morsel size for out-of-core execution (Poka-Yoke)
88    #[must_use]
89    pub const fn morsel_size_mb(self, _size: usize) -> Self {
90        self
91    }
92
93    /// Build the database
94    ///
95    /// # Errors
96    ///
97    /// Returns error if GPU initialization fails
98    pub const fn build(self) -> Result<Database> {
99        Ok(Database { _private: () })
100    }
101}
trueno_db/lib.rs

trueno_db/
lib.rs
