tuwunel_database/
map.rs

1mod clear;
2pub mod compact;
3mod contains;
4mod count;
5mod del;
6mod del_prefix;
7mod get;
8mod get_batch;
9mod insert;
10mod keys;
11mod keys_from;
12mod keys_prefix;
13mod open;
14mod options;
15mod put;
16mod qry;
17mod qry_batch;
18mod remove;
19mod rev_keys;
20mod rev_keys_from;
21mod rev_keys_prefix;
22mod rev_stream;
23mod rev_stream_from;
24mod rev_stream_prefix;
25mod seek;
26mod stream;
27mod stream_from;
28mod stream_prefix;
29mod watch;
30
31use std::{
32	ffi::CStr,
33	fmt,
34	fmt::{Debug, Display},
35	sync::Arc,
36};
37
38use rocksdb::{AsColumnFamilyRef, ColumnFamily, DBCommon, ReadOptions, WriteOptions};
39use tuwunel_core::Result;
40
41pub(crate) use self::options::{
42	cache_iter_options_default, cache_read_options_default, iter_options_default,
43	read_options_default, write_options_default,
44};
45use self::watch::Watch;
46/// Stream extensions for batched map reads.
47///
48/// `Get` accepts raw keys, while `Qry` serializes structured keys before
49/// lookup. Both yield pinned value handles through an asynchronous stream.
50pub use self::{get_batch::Get, qry_batch::Qry};
51use crate::{Engine, util::map_err};
52
53/// Provides typed and raw access to one RocksDB column family.
54///
55/// A map retains its column-family handle and the engine that owns it. Point
56/// operations reuse read and write options prepared when the map opens.
57pub struct Map {
58	name: &'static str,
59	watch: Watch,
60	cf: Arc<ColumnFamily>,
61	engine: Arc<Engine>,
62	read_options: ReadOptions,
63	cache_read_options: ReadOptions,
64	write_options: WriteOptions,
65}
66
67impl Map {
68	/// Opens a map for a named column family.
69	///
70	/// The returned map keeps the engine alive for at least as long as its
71	/// column-family handle. Its read and write options are initialized from
72	/// the engine configuration.
73	pub(crate) fn open(engine: &Arc<Engine>, name: &'static str) -> Result<Arc<Self>> {
74		Ok(Arc::new(Self {
75			name,
76			watch: Watch::default(),
77			cf: open::open(engine, name),
78			engine: engine.clone(),
79			read_options: read_options_default(engine),
80			cache_read_options: cache_read_options_default(engine),
81			write_options: write_options_default(engine),
82		}))
83	}
84
85	/// Flush this map's memtable to SST files (a RocksDB LSM-tree flush).
86	///
87	/// Forces the column family's buffered writes out of memory into the
88	/// on-disk LSM tree. An LSM flush, not a libc `fflush(3)` or `fsync(2)`,
89	/// and distinct from the engine's `flush` and `sync`, which act on the
90	/// write-ahead log.
91	#[tracing::instrument(
92		level = "info",
93		skip_all,
94		fields(
95			map = self.name(),
96			sequence = ?self.engine.current_sequence(),
97		),
98	)]
99	pub fn sort(&self) -> Result {
100		let cf = self.cf();
101		let flushoptions = rocksdb::FlushOptions::default();
102		DBCommon::flush_cf_opt(&self.engine.db, &cf, &flushoptions).map_err(map_err)
103	}
104
105	/// Reads an integer RocksDB property for this map.
106	///
107	/// The property query is scoped to this map's column family. Engine errors
108	/// are returned to the caller.
109	#[inline]
110	pub fn property_integer(&self, name: &CStr) -> Result<u64> {
111		self.engine.property_integer(&self.cf(), name)
112	}
113
114	/// Reads a string RocksDB property for this map.
115	///
116	/// The property query is scoped to this map's column family. Engine errors
117	/// are returned to the caller.
118	#[inline]
119	pub fn property(&self, name: &str) -> Result<String> {
120		self.engine.property(&self.cf(), name)
121	}
122
123	/// Returns the column-family name of this map.
124	///
125	/// The name is fixed when the map opens and lives for the duration of the
126	/// process.
127	#[inline]
128	pub fn name(&self) -> &str { self.name }
129
130	/// Returns the engine that owns this map.
131	///
132	/// The borrowed `Arc` keeps the same identity used to open the
133	/// column-family handle.
134	#[inline]
135	pub(crate) fn engine(&self) -> &Arc<Engine> { &self.engine }
136
137	/// Returns this map's RocksDB column-family handle.
138	///
139	/// The handle remains valid because the map retains its owning engine.
140	#[inline]
141	pub(crate) fn cf(&self) -> impl AsColumnFamilyRef + '_ { &*self.cf }
142
143	/// Returns the numeric RocksDB identifier for this column family.
144	///
145	/// The identifier belongs to this map's engine and must not be compared
146	/// across engines.
147	#[inline]
148	pub(crate) fn cf_id(&self) -> u32 { self.cf().id() }
149}
150
151impl Debug for Map {
152	fn fmt(&self, out: &mut fmt::Formatter<'_>) -> fmt::Result {
153		write!(out, "Map {{name: {0}}}", self.name)
154	}
155}
156
157impl Display for Map {
158	fn fmt(&self, out: &mut fmt::Formatter<'_>) -> fmt::Result { write!(out, "{0}", self.name) }
159}
tuwunel_database/map.rs

tuwunel_database/
map.rs
