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

trueno_db/
lib.rs
