docs

Author: niklabh

src/lib.rs

@@ -1,5 +1,40 @@
-// VelociDB library interface
-// Modern embedded database with MVCC, async I/O, and vectorized execution
+//! # VelociDB
+//!
+//! VelociDB is a high-performance, embedded database engine written in Rust.
+//! It features a modern architecture designed for NVMe storage and multi-core systems.
+//!
+//! ## Key Features
+//!
+//! - **MVCC**: Multi-Version Concurrency Control for non-blocking reads.
+//! - **Async I/O**: Built on `tokio` and `io_uring` (on Linux) for high throughput.
+//! - **SIMD Acceleration**: Vectorized execution for query processing.
+//! - **Persistent Memory**: Direct Access (DAX) support for PMEM.
+//!
+//! ## Quick Start
+//!
+//! ```rust,no_run
+//! use velocidb::Database;
+//!
+//! # fn main() -> anyhow::Result<()> {
+//! // Open a database (creates it if it doesn't exist)
+//! let db = Database::open("my_database.db")?;
+//!
+//! // Create a table
+//! db.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, age INTEGER)")?;
+//!
+//! // Insert data
+//! db.execute("INSERT INTO users VALUES (1, 'Alice', 30)")?;
+//! db.execute("INSERT INTO users VALUES (2, 'Bob', 25)")?;
+//!
+//! // Query data
+//! let results = db.query("SELECT * FROM users WHERE age > 25")?;
+//!
+//! for row in results.rows {
+//!     println!("Found user: {:?}", row.values);
+//! }
+//! # Ok(())
+//! # }
+//! ```
 
 pub mod storage;
 pub mod btree;

src/lockfree.rs

@@ -17,7 +17,7 @@ pub struct LockFreePageCache {
     /// Current size
     size: AtomicUsize,
     /// Cache entries: page_id -> cached page
-    /// Using Arc<RwLock> for the HashMap as a pragmatic hybrid approach
+    /// Using `Arc<RwLock>` for the HashMap as a pragmatic hybrid approach
     /// The HashMap itself is behind a lock, but individual operations are fast
     entries: Arc<RwLock<HashMap<PageId, Arc<CachedPage>>>>,
     /// LRU tracking queue (lock-free)

src/storage.rs

@@ -150,6 +150,15 @@ impl Drop for Pager {
     }
 }
 
+/// The main database structure.
+///
+/// `Database` provides the primary interface for interacting with a VelociDB database.
+/// It handles storage management, transaction coordination, and query execution.
+///
+/// # Thread Safety
+///
+/// `Database` is thread-safe and can be shared across threads using `Arc`.
+/// Internally, it uses fine-grained locking to allow concurrent reads and writes.
 pub struct Database {
     pager: Arc<RwLock<Pager>>,
     btrees: Arc<RwLock<HashMap<String, Arc<RwLock<BTree>>>>>,
@@ -158,6 +167,25 @@ pub struct Database {
 }
 
 impl Database {
+    /// Opens a database at the specified path.
+    ///
+    /// If the database file does not exist, it will be created.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The path to the database file.
+    ///
+    /// # Returns
+    ///
+    /// Returns a `Result` containing an `Arc<Database>` on success.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    /// use velocidb::Database;
+    ///
+    /// let db = Database::open("my_database.db").unwrap();
+    /// ```
     pub fn open<P: AsRef<Path>>(path: P) -> Result<Arc<Self>> {
         let pager = Arc::new(RwLock::new(Pager::new(path.as_ref())?));
         let btrees = Arc::new(RwLock::new(HashMap::new()));
@@ -421,6 +449,20 @@ impl Database {
         Ok(())
     }
 
+    /// Executes a SQL statement that does not return rows (e.g., CREATE, INSERT, UPDATE, DELETE).
+    ///
+    /// # Arguments
+    ///
+    /// * `sql` - The SQL statement to execute.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    /// # use velocidb::Database;
+    /// # let db = Database::open("test.db").unwrap();
+    /// db.execute("CREATE TABLE items (id INTEGER, name TEXT)").unwrap();
+    /// db.execute("INSERT INTO items VALUES (1, 'Item 1')").unwrap();
+    /// ```
     pub fn execute(&self, sql: &str) -> Result<()> {
         let parser = Parser::new();
         let statement = parser.parse(sql)?;
@@ -446,6 +488,26 @@ impl Database {
         Ok(())
     }
 
+    /// Executes a SQL query that returns rows (e.g., SELECT).
+    ///
+    /// # Arguments
+    ///
+    /// * `sql` - The SQL query to execute.
+    ///
+    /// # Returns
+    ///
+    /// Returns a `Result` containing a `QueryResult` with the fetched rows and columns.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    /// # use velocidb::Database;
+    /// # let db = Database::open("test.db").unwrap();
+    /// let results = db.query("SELECT * FROM items").unwrap();
+    /// for row in results.rows {
+    ///     println!("{:?}", row.values);
+    /// }
+    /// ```
     pub fn query(&self, sql: &str) -> Result<QueryResult> {
         let parser = Parser::new();
         let statement = parser.parse(sql)?;
@@ -460,11 +522,16 @@ impl Database {
         executor.query(statement)
     }
 
+    /// Closes the database and flushes all changes to disk.
+    ///
+    /// While `Database` implements `Drop` to automatically flush on cleanup,
+    /// calling `close` explicitly allows handling any flush errors.
     pub fn close(&self) -> Result<()> {
         self.pager.write().flush()?;
         Ok(())
     }
 
+    /// Lists all tables in the database.
     pub fn list_tables(&self) -> Vec<String> {
         self.schema.read().list_tables()
     }

src/transaction.rs

@@ -13,11 +13,15 @@ use std::sync::atomic::{AtomicU64, AtomicU8, Ordering};
 use std::sync::Arc;
 use std::time::Duration;
 
+/// Represents the state of a transaction.
 #[derive(Debug, Clone, Copy, PartialEq)]
 #[repr(u8)]
 pub enum TransactionState {
+    /// Transaction is active and can perform operations.
     Active = 0,
+    /// Transaction has been committed successfully.
     Committed = 1,
+    /// Transaction has been aborted/rolled back.
     Aborted = 2,
 }
 
@@ -32,6 +36,10 @@ impl From<u8> for TransactionState {
     }
 }
 
+/// A database transaction.
+///
+/// Transactions provide ACID guarantees for database operations.
+/// They are created by the `TransactionManager`.
 pub struct Transaction {
     id: TransactionId,
     // Use atomic instead of RwLock to eliminate lock contention
@@ -46,14 +54,19 @@ impl Transaction {
         }
     }
 
+    /// Returns the unique identifier of the transaction.
     pub fn id(&self) -> TransactionId {
         self.id
     }
 
+    /// Returns the current state of the transaction.
     pub fn state(&self) -> TransactionState {
         self.state.load(Ordering::Acquire).into()
     }
 
+    /// Commits the transaction.
+    ///
+    /// This makes all changes made by the transaction permanent.
     pub fn commit(&self) -> Result<()> {
         // Use compare-exchange to ensure atomic state transition
         match self.state.compare_exchange(
@@ -72,6 +85,9 @@ impl Transaction {
         }
     }
 
+    /// Aborts the transaction.
+    ///
+    /// This rolls back all changes made by the transaction.
     pub fn abort(&self) -> Result<()> {
         // Use compare-exchange to ensure atomic state transition
         match self.state.compare_exchange(
@@ -91,6 +107,7 @@ impl Transaction {
     }
 }
 
+/// Manages the lifecycle of transactions.
 pub struct TransactionManager {
     next_txn_id: AtomicU64,
     active_transactions: RwLock<HashMap<TransactionId, Arc<Transaction>>>,
@@ -104,6 +121,7 @@ impl TransactionManager {
         }
     }
 
+    /// Begins a new transaction.
     pub fn begin(&self) -> Arc<Transaction> {
         let txn_id = self.next_txn_id.fetch_add(1, Ordering::SeqCst);
         let txn = Arc::new(Transaction::new(txn_id));
@@ -117,6 +135,7 @@ impl TransactionManager {
         txn
     }
 
+    /// Commits a transaction.
     pub fn commit(&self, txn: &Transaction) -> Result<()> {
         // LOCK ORDERING: 
         // 1. Commit transaction state (atomic operation - no lock)
@@ -129,6 +148,7 @@ impl TransactionManager {
         Ok(())
     }
 
+    /// Aborts a transaction.
     pub fn abort(&self, txn: &Transaction) -> Result<()> {
         // LOCK ORDERING: Same as commit - state first (atomic), then active_transactions
         txn.abort()?;
@@ -138,10 +158,12 @@ impl TransactionManager {
         Ok(())
     }
 
+    /// Retrieves an active transaction by ID.
     pub fn get_transaction(&self, txn_id: TransactionId) -> Option<Arc<Transaction>> {
         self.active_transactions.read().get(&txn_id).cloned()
     }
 
+    /// Returns the number of currently active transactions.
     pub fn active_count(&self) -> usize {
         self.active_transactions.read().len()
     }
@@ -166,6 +188,7 @@ impl TransactionManager {
 
 use dashmap::DashMap;
 
+/// Manages locks on database resources (e.g., tables).
 pub struct LockManager {
     // Per-table lock entries using lock-free DashMap
     // This eliminates the single global lock bottleneck
@@ -178,9 +201,12 @@ struct LockEntry {
     lock_type: LockType,
 }
 
+/// Types of locks available.
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub enum LockType {
+    /// Shared lock (allows concurrent readers).
     Shared,
+    /// Exclusive lock (single writer, no readers).
     Exclusive,
 }