alopex_core/kv/
mod.rs

1//! Traits for the Key-Value storage layer.
2
3use crate::error::Result;
4use crate::txn::TxnManager;
5use crate::types::{Key, TxnId, TxnMode, Value};
6
7/// Runtime statistics exposed by SQL system functions.
8#[derive(Debug, Clone, PartialEq)]
9pub enum RuntimeStats {
10    /// Statistics for the in-memory store.
11    Memory(crate::kv::memory::MemoryStats),
12    /// Statistics for the LSM store.
13    Lsm(crate::lsm::metrics::LsmMetricsSnapshot),
14}
15
16#[cfg(feature = "test-hooks")]
17pub mod hooks;
18
19/// MemoryKV / LsmKV を 1 つの型として扱うためのラッパー。
20pub mod any;
21/// Async adapter for sync KV stores (requires `tokio` feature).
22#[cfg(feature = "tokio")]
23pub mod async_adapter;
24/// Async KV traits (requires `async` feature).
25#[cfg(feature = "async")]
26pub mod async_kv;
27pub mod memory;
28/// Storage mode selection helpers (disk vs memory).
29pub mod storage;
30
31/// S3-backed storage (requires `s3` feature).
32#[cfg(feature = "s3")]
33pub mod s3;
34
35pub use any::AnyKV;
36#[cfg(feature = "tokio")]
37pub use async_adapter::{AsyncKVStoreAdapter, AsyncKVTransactionAdapter};
38#[cfg(feature = "async")]
39pub use async_kv::{AsyncKVStore, AsyncKVTransaction};
40
41#[cfg(feature = "s3")]
42pub use s3::{S3Config, S3KV};
43
44/// A transaction for interacting with the key-value store.
45///
46/// Transactions provide snapshot isolation.
47pub trait KVTransaction<'a> {
48    /// Returns the transaction's unique ID.
49    fn id(&self) -> TxnId;
50
51    /// Returns the transaction's mode (ReadOnly or ReadWrite).
52    fn mode(&self) -> TxnMode;
53
54    /// Retrieves the value for a given key.
55    fn get(&mut self, key: &Key) -> Result<Option<Value>>;
56
57    /// Sets a value for a given key.
58    /// This operation is buffered and will be applied on commit.
59    ///
60    /// # Errors
61    ///
62    /// Returns an error if the transaction is read-only.
63    fn put(&mut self, key: Key, value: Value) -> Result<()>;
64
65    /// Deletes a key-value pair.
66    /// This operation is buffered and will be applied on commit.
67    ///
68    /// # Errors
69    ///
70    /// Returns an error if the transaction is read-only.
71    fn delete(&mut self, key: Key) -> Result<()>;
72
73    /// Scans all key-value pairs whose keys start with the given prefix.
74    ///
75    /// Implementations must respect snapshot isolation: results should reflect
76    /// the transaction's start version plus its in-flight writes.
77    fn scan_prefix(&mut self, prefix: &[u8])
78        -> Result<Box<dyn Iterator<Item = (Key, Value)> + '_>>;
79
80    /// Scans key-value pairs in the half-open range [start, end).
81    ///
82    /// Implementations must respect snapshot isolation: results should reflect
83    /// the transaction's start version plus its in-flight writes.
84    fn scan_range(
85        &mut self,
86        start: &[u8],
87        end: &[u8],
88    ) -> Result<Box<dyn Iterator<Item = (Key, Value)> + '_>>;
89
90    /// Commits the transaction, applying all buffered writes.
91    ///
92    /// This method consumes the transaction. On success, all writes become
93    /// visible to subsequent transactions. On failure, no changes are applied.
94    fn commit_self(self) -> Result<()>;
95
96    /// Rolls back the transaction, discarding all buffered writes.
97    ///
98    /// This method consumes the transaction. All pending writes are discarded.
99    fn rollback_self(self) -> Result<()>;
100}
101
102/// The main trait for a key-value storage engine.
103///
104/// This trait provides the primary entry point for interacting with the database.
105pub trait KVStore: Send + Sync {
106    /// The transaction type for this store.
107    type Transaction<'a>: KVTransaction<'a>
108    where
109        Self: 'a;
110
111    /// The transaction manager for this store.
112    type Manager<'a>: TxnManager<'a, Self::Transaction<'a>>
113    where
114        Self: 'a;
115
116    /// Returns the transaction manager for this store.
117    fn txn_manager(&self) -> Self::Manager<'_>;
118
119    /// A convenience method to begin a new transaction.
120    fn begin(&self, mode: TxnMode) -> Result<Self::Transaction<'_>>;
121
122    /// Returns a point-in-time runtime statistics snapshot, when supported.
123    fn runtime_stats(&self) -> Option<RuntimeStats> {
124        None
125    }
126
127    /// Sets the memory limit in bytes, when supported.
128    fn set_memory_limit_bytes(&self, _limit: Option<usize>) -> Result<()> {
129        Ok(())
130    }
131
132    /// Sets the cache capacity in bytes, when supported.
133    fn set_cache_capacity_bytes(&self, _capacity: usize) -> Result<()> {
134        Ok(())
135    }
136
137    /// Clears the cache and returns the number of bytes removed.
138    fn clear_cache(&self) -> Result<usize> {
139        Ok(0)
140    }
141}
alopex_core/kv/mod.rs

alopex_core/kv/
mod.rs
