llkv_transaction/
lib.rs

1//! Transaction management and MVCC (Multi-Version Concurrency Control) for LLKV.
2//!
3//! This crate provides transaction isolation using MVCC semantics. Each transaction
4//! operates with a consistent snapshot of the database, determined by its transaction
5//! ID and snapshot timestamp.
6//!
7//! # Module Organization
8//!
9//! - `core`: Core MVCC primitives (TxnIdManager, TransactionSnapshot, RowVersion) - *currently `mvcc` module*
10//! - `table`: Table-level MVCC integration (row filtering, builders) - *currently `helpers` module*
11//! - [`context`]: Transaction context types (SessionTransaction, TransactionSession, TransactionManager)
12//! - [`types`]: Data type definitions (TransactionResult, TransactionKind, TransactionCatalogSnapshot)
13//!
14//! # Key Concepts
15//!
16//! - **Transaction ID ([`TxnId`])**: Unique 64-bit identifier for each transaction
17//! - **Snapshot Isolation**: Transactions see a consistent view of data as of their start time
18//! - **Row Versioning**: Each row tracks when it was created and deleted via `created_by` and `deleted_by` columns
19//! - **[`TransactionSnapshot`]**: Captures transaction ID and snapshot timestamp
20//!
21//! # Reserved Transaction IDs
22//!
23//! - **[`TXN_ID_NONE`] (u64::MAX)**: Indicates no transaction (uninitialized state)
24//! - **[`TXN_ID_AUTO_COMMIT`] (1)**: Used for auto-commit (single-statement) transactions
25//! - **IDs 2+**: Multi-statement transactions (allocated by [`TxnIdManager`])
26//!
27//! # Visibility Rules
28//!
29//! A row is visible to a transaction if:
30//! 1. It was created before the transaction's snapshot (`created_by <= snapshot_id`)
31//! 2. It was not deleted, or deleted after the snapshot (`deleted_by == TXN_ID_NONE || deleted_by > snapshot_id`)
32//!
33//! # Architecture
34//!
35//! - **[`TxnIdManager`]**: Allocates transaction IDs and tracks commit status
36//! - **[`TransactionSnapshot`]**: Immutable view of transaction state for visibility checks
37//! - **[`context::TransactionContext`]**: Main interface for executing operations within a transaction
38//! - **[`context::SessionTransaction`]**: Per-transaction state machine
39//! - **[`context::TransactionSession`]**: Session-level transaction management
40//! - **[`context::TransactionManager`]**: Cross-session transaction coordinator
41//! - **[`RowVersion`]**: Metadata tracking which transaction created/deleted a row
42//! - **[`types::TransactionCatalogSnapshot`]**: Catalog snapshot interface for table lookups
43
44// ============================================================================
45// Module Declarations
46// ============================================================================
47
48pub mod context;
49pub mod helpers;
50pub mod mvcc;
51pub mod types;
52
53pub use context::{
54    SessionTransaction, TransactionContext, TransactionManager, TransactionSession,
55    TransactionSessionId,
56};
57pub use helpers::{
58    MvccRowIdFilter, TransactionMvccBuilder, filter_row_ids_for_fk_check,
59    filter_row_ids_for_snapshot,
60};
61pub use mvcc::{
62    RowVersion, TXN_ID_AUTO_COMMIT, TXN_ID_NONE, TransactionSnapshot, TxnId, TxnIdManager,
63};
64pub use types::{TransactionCatalogSnapshot, TransactionKind, TransactionResult};
llkv_transaction/lib.rs

llkv_transaction/
lib.rs
