Skip to main content

tuwunel_database/
map.rs

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