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

trueno_db/
lib.rs
