use crate::hook::{NoHook, TypedWriteHook};
use super::freeze::Admission;
use super::index_target::{self, IndexState, IndexStateCell};
use std::hash::Hash;
use std::marker::PhantomData;
use std::ops::{Bound, ControlFlow};
use std::path::Path;
use std::sync::{Arc, OnceLock, Weak};
use std::time::Duration;
use super::config::SegConfig;
use super::core::{OpenOptions, SegCore, SegMeta};
use super::ordered::RawOrderedIter;
use super::query::SegRange;
use super::verify::{SegmentInfo, VerifyReport, VerifyScope};
use super::worker::SealStatus;
use crate::codec::Codec;
use crate::error::{DbError, DbResult};
use crate::key::Key;
use crate::{CollectionMeta, KeyPage, Page};
pub trait SegTreeMeta: CollectionMeta {
const PREFIX_FILTERS: &'static [usize] = &[];
const INDEX_TARGET: bool = false;
}
pub struct SegTree<K: Key + Hash + Eq + Send + Sync + 'static, T, C, H = NoHook> {
core: Arc<SegCore<K>>,
pub(crate) codec: C,
pub(crate) hook: H,
pub(crate) tx_self: OnceLock<Weak<Self>>,
index_target: bool,
index_state: OnceLock<Arc<IndexStateCell>>,
_value: PhantomData<fn() -> T>,
}
impl<K, T, C> SegTree<K, T, C>
where
K: Key + Hash + Eq + Send + Sync + 'static,
C: Codec<T>,
{
pub fn open(
path: &Path,
meta: SegMeta,
prefix_filters: &'static [usize],
config: SegConfig,
codec: C,
) -> DbResult<Self> {
Self::open_with(
path,
meta,
prefix_filters,
config,
codec,
OpenOptions::production(),
)
}
pub(crate) fn open_with(
path: &Path,
meta: SegMeta,
prefix_filters: &'static [usize],
config: SegConfig,
codec: C,
options: OpenOptions,
) -> DbResult<Self> {
Ok(Self {
core: SegCore::open_tree(path, meta, prefix_filters, config, options)?,
codec,
hook: NoHook,
tx_self: OnceLock::new(),
index_target: false,
index_state: OnceLock::new(),
_value: PhantomData,
})
}
}
impl<K, T, C, H> SegTree<K, T, C, H>
where
K: Key + Hash + Eq + Send + Sync + 'static,
C: Codec<T>,
H: TypedWriteHook<K, T>,
{
pub(crate) fn open_deferred(
path: &Path,
meta: SegMeta,
prefix_filters: &'static [usize],
index_target: bool,
config: SegConfig,
codec: C,
hook: H,
) -> DbResult<Self> {
Ok(Self {
core: SegCore::open_tree_deferred(
path,
meta,
prefix_filters,
config,
OpenOptions::production(),
)?,
codec,
hook,
tx_self: OnceLock::new(),
index_target,
index_state: OnceLock::new(),
_value: PhantomData,
})
}
pub(crate) fn core(&self) -> &Arc<SegCore<K>> {
&self.core
}
pub fn name(&self) -> &'static str {
self.core.meta.name
}
pub fn index_state(&self) -> Option<IndexState> {
self.index_state.get().map(|cell| cell.get())
}
pub(crate) fn is_index_target(&self) -> bool {
self.index_target
}
pub(crate) fn is_index_target_participant(&self) -> bool {
self.is_index_target()
}
pub(crate) fn bind_index_state(&self, cell: Arc<IndexStateCell>) {
let _ = self.index_state.set(cell);
}
pub(crate) fn maintenance_write(&self, key: &[u8], value: Option<&[u8]>) -> DbResult<()> {
if !crate::index_maintenance::IndexMaintenance::consume(self.name()) {
return Err(DbError::Config(index_target::DIRECT_WRITE));
}
if key.len() != size_of::<K>() {
return Err(DbError::CorruptedEntry { offset: 0 });
}
let k = K::from_bytes(key);
let admission = Admission::until_seal_fails(&self.core.config)?;
match value {
Some(v) => self.core.put_with(&k, v, admission),
None => self.core.delete_with(&k, admission),
}
}
pub fn stats(&self) -> super::verify::SegStats {
self.core.stats()
}
pub fn config(&self) -> &SegConfig {
&self.core.config
}
pub fn put(&self, key: &K, value: &T) -> DbResult<()> {
if self.is_index_target() {
return Err(DbError::Config(index_target::DIRECT_WRITE));
}
self.facade_guard()?;
self.core.put(key, &self.codec.encode(value)?)
}
pub fn insert(&self, key: &K, value: &T) -> DbResult<()> {
if self.is_index_target() {
return Err(DbError::Config(index_target::DIRECT_WRITE));
}
self.facade_guard()?;
self.core.insert(key, &self.codec.encode(value)?)
}
pub fn insert_hinted(&self, key: &K, value: &T, written_since_ms: u64) -> DbResult<()> {
if self.is_index_target() {
return Err(DbError::Config(index_target::DIRECT_WRITE));
}
self.facade_guard()?;
self.core
.insert_since(key, &self.codec.encode(value)?, Some(written_since_ms))
}
pub fn delete(&self, key: &K) -> DbResult<()> {
if self.is_index_target() {
return Err(DbError::Config(index_target::DIRECT_WRITE));
}
self.facade_guard()?;
self.core.delete(key)
}
fn decode(&self, bytes: Option<Vec<u8>>) -> DbResult<Option<T>> {
bytes.map(|b| self.codec.decode_from(&b)).transpose()
}
pub fn try_get(&self, key: &K) -> DbResult<Option<T>> {
self.decode(self.core.get(key)?)
}
pub fn get(&self, key: &K) -> Option<T> {
metrics::counter!("armdb.ops", "op" => "get", "tree" => "seg_tree").increment(1);
match self.try_get(key) {
Ok(value) => value,
Err(e) => {
tracing::error!(collection = self.name(), error = %e, "SegTree get error");
None
}
}
}
pub fn get_or_err(&self, key: &K) -> DbResult<T> {
self.try_get(key)?.ok_or(DbError::KeyNotFound)
}
pub fn try_contains(&self, key: &K) -> DbResult<bool> {
self.core.contains(key)
}
pub fn contains(&self, key: &K) -> bool {
match self.try_contains(key) {
Ok(found) => found,
Err(e) => {
tracing::error!(collection = self.name(), error = %e, "SegTree contains error");
false
}
}
}
pub fn try_get_hinted(&self, key: &K, written_since_ms: u64) -> DbResult<Option<T>> {
self.decode(self.core.get_hinted(key, written_since_ms)?)
}
pub fn len(&self) -> usize {
self.core.len()
}
pub fn is_empty(&self) -> bool {
self.len() == 0
}
pub fn seal(&self) -> DbResult<()> {
self.core.seal()
}
pub fn wait_sealed(&self, timeout: Duration) -> DbResult<bool> {
self.core.wait_sealed(timeout)
}
pub fn seal_status(&self) -> SealStatus {
self.core.seal_status()
}
pub fn segments(&self) -> Vec<SegmentInfo> {
self.core.segments()
}
pub fn drop_segments_before(&self, ts_ms: u64) -> DbResult<usize> {
if self.is_index_target() {
return Err(DbError::Config(index_target::NO_DROP));
}
if self.hook.projection_targets().is_some() || self.hook.counter_targets().is_some() {
return Err(DbError::Config(
"segmented projection sources cannot drop segments",
));
}
self.core.drop_segments_before(ts_ms)
}
pub fn verify(&self, scope: VerifyScope) -> DbResult<VerifyReport> {
self.core.verify(scope)
}
pub fn flush(&self) -> DbResult<()> {
self.core.flush()
}
pub fn durable_flush(&self) -> DbResult<()> {
self.core.durable_flush()
}
pub fn dirty_shards(&self) -> usize {
self.core.dirty_shards()
}
pub fn clean_shutdown(&self) -> DbResult<()> {
self.core.clean_shutdown()
}
pub fn iter(&self) -> SegIter<'_, K, T, C> {
self.scan(SegRange::all())
}
pub fn range(&self, start: &K, end: &K) -> SegIter<'_, K, T, C> {
self.range_bounds(Bound::Included(start), Bound::Excluded(end))
}
pub fn range_bounds(&self, start: Bound<&K>, end: Bound<&K>) -> SegIter<'_, K, T, C> {
self.scan(SegRange::range(start, end))
}
pub fn prefix_iter(&self, prefix: &[u8]) -> SegIter<'_, K, T, C> {
self.scan(SegRange::prefix(prefix))
}
pub fn scan(&self, query: SegRange<K>) -> SegIter<'_, K, T, C> {
SegIter {
raw: self.core.ordered_iter(query, true, true),
codec: &self.codec,
ended: false,
_value: PhantomData,
}
}
pub fn scan_keys(&self, query: SegRange<K>) -> SegKeyIter<'_, K> {
SegKeyIter {
raw: self.core.ordered_iter(query, false, true),
}
}
pub fn first(&self) -> DbResult<Option<(K, T)>> {
let mut iter = self.iter();
iter.raw.limit_rows(1);
iter.next().transpose()
}
pub fn last(&self) -> DbResult<Option<(K, T)>> {
let mut iter = self.scan(SegRange::all().rev());
iter.raw.limit_rows(1);
iter.next().transpose()
}
pub fn page(
&self,
query: SegRange<K>,
after: Option<&K>,
limit: usize,
) -> DbResult<Page<K, T>> {
let mut iter = self.scan(query.after(after));
iter.raw.limit_rows(limit);
let items: Vec<_> = iter.take(limit).collect::<DbResult<_>>()?;
let next = if limit != 0 && items.len() == limit {
items.last().map(|r| r.0)
} else {
None
};
Ok(Page { items, next })
}
pub fn keys_page(
&self,
query: SegRange<K>,
after: Option<&K>,
limit: usize,
) -> DbResult<KeyPage<K>> {
let mut iter = self.scan_keys(query.after(after));
iter.raw.limit_rows(limit);
let keys: Vec<_> = iter.take(limit).collect::<DbResult<_>>()?;
let next = if limit != 0 && keys.len() == limit {
keys.last().copied()
} else {
None
};
Ok(KeyPage { keys, next })
}
pub(super) fn check_own_migration_action(&self) -> DbResult<()> {
if self.is_index_target() {
Err(DbError::Config(index_target::KEEP_ONLY))
} else {
Ok(())
}
}
pub(crate) fn walk_rows(
&self,
decode: bool,
visit: &mut dyn FnMut(DbResult<(K, T)>) -> ControlFlow<()>,
) {
self.core.scan(&mut |row| match row {
Err(e) => {
let _ = visit(Err(e));
ControlFlow::Break(())
}
Ok((key, bytes)) => match self.codec.decode_from(&bytes) {
Ok(value) if decode => visit(Ok((key, value))),
Ok(_) => ControlFlow::Continue(()),
Err(e) => {
tracing::warn!(collection = self.name(), error = %e, "a segmented row does not decode");
visit(Err(e))
}
},
});
}
}
impl<K, T, C> crate::projection::sealed::Sealed for SegTree<K, T, C, NoHook>
where
K: Key + Hash + Eq + Send + Sync + 'static,
T: SegTreeMeta + Send + Sync + 'static,
C: Codec<T> + Send + Sync + 'static,
{
}
impl<K, T, C> crate::projection::ProjectableIndex for SegTree<K, T, C, NoHook>
where
K: Key + Hash + Eq + Send + Sync + 'static,
T: SegTreeMeta + PartialEq + Send + Sync + 'static,
C: Codec<T> + Send + Sync + 'static,
{
fn collection_name(&self) -> &'static str {
self.name()
}
fn put_bytes(&self, key: &[u8], value: &[u8]) -> DbResult<()> {
self.maintenance_write(key, Some(value))
}
fn delete_bytes(&self, key: &[u8]) -> DbResult<()> {
self.maintenance_write(key, None)
}
fn values_equal(&self, a: &[u8], b: &[u8]) -> DbResult<bool> {
if a == b {
return Ok(true);
}
Ok(self.codec.decode_from(a)? == self.codec.decode_from(b)?)
}
fn for_each_bytes(&self, f: &mut dyn FnMut(&[u8], &[u8]) -> DbResult<()>) -> DbResult<()> {
let mut failure = None;
self.core.scan(
&mut |row| match row.and_then(|(k, v)| f(k.as_bytes(), &v)) {
Ok(()) => ControlFlow::Continue(()),
Err(e) => {
failure = Some(e);
ControlFlow::Break(())
}
},
);
failure.map_or(Ok(()), Err)
}
fn durable_flush(&self) -> DbResult<()> {
self.core.durable_flush()
}
fn target_kind(&self) -> crate::projection::TargetKind {
crate::projection::TargetKind::Segmented {
declared: self.is_index_target(),
}
}
fn physical_entries(&self) -> Option<u64> {
Some(self.core.physical_entries())
}
}
impl<K, T, C> crate::projection::ProjectableIndexTx for SegTree<K, T, C, NoHook>
where
K: Key + Hash + Eq + Send + Sync + 'static,
T: SegTreeMeta + PartialEq + Send + Sync + 'static,
C: Codec<T> + Send + Sync + 'static,
{
fn as_tx_participant(self: Arc<Self>) -> Arc<dyn crate::txn::participant::TxParticipant> {
self
}
}
impl<K, T, C> crate::projection::IndexKeyed for SegTree<K, T, C, NoHook>
where
K: Key + Hash + Eq + Send + Sync + 'static,
T: SegTreeMeta + Clone + PartialEq + Send + Sync + 'static,
C: Codec<T> + Send + Sync + 'static,
{
type K = K;
type V = T;
fn encode_value(&self, v: &T) -> DbResult<Vec<u8>> {
self.codec.encode(v)
}
}
impl<K: Key + Hash + Eq + Send + Sync + 'static, T, C, H> Drop for SegTree<K, T, C, H> {
fn drop(&mut self) {
self.core.stop_worker();
}
}
pub struct SegIter<'a, K: Key + Hash + Eq + Send + Sync + 'static, T, C> {
raw: RawOrderedIter<'a, K>,
codec: &'a C,
ended: bool,
_value: PhantomData<fn() -> T>,
}
impl<K: Key + Hash + Eq + Send + Sync + 'static, T, C: Codec<T>> Iterator for SegIter<'_, K, T, C> {
type Item = DbResult<(K, T)>;
fn next(&mut self) -> Option<Self::Item> {
if self.ended {
return None;
}
let row = self
.raw
.next()?
.and_then(|(key, bytes)| self.codec.decode_from(&bytes).map(|value| (key, value)));
if row.is_err() {
self.ended = true;
}
Some(row)
}
}
pub struct SegKeyIter<'a, K: Key + Hash + Eq + Send + Sync + 'static> {
raw: RawOrderedIter<'a, K>,
}
impl<K: Key + Hash + Eq + Send + Sync + 'static> Iterator for SegKeyIter<'_, K> {
type Item = DbResult<K>;
fn next(&mut self) -> Option<Self::Item> {
self.raw.next().map(|row| row.map(|(key, _)| key))
}
}
impl<K, T, C, H> crate::armour::collection::Collection for SegTree<K, T, C, H>
where
K: Key + Hash + Eq + Send + Sync + 'static,
T: Send + Sync,
C: Codec<T>,
H: TypedWriteHook<K, T>,
{
fn reconcile_counters(&self) -> DbResult<u64> {
SegTree::reconcile_counters(self)
}
fn counter_target_names(&self) -> Vec<&'static str> {
SegTree::counter_target_names(self)
}
fn name(&self) -> &str {
self.core.meta.name
}
fn len(&self) -> usize {
self.core.len()
}
fn compact(&self) -> DbResult<usize> {
Ok(0)
}
fn flush(&self) -> DbResult<()> {
self.core.flush()
}
fn periodic_flush(&self) -> DbResult<()> {
self.core.durable_flush()
}
fn durable_flush(&self) -> DbResult<()> {
self.core.durable_flush()
}
fn clean_shutdown(&self) -> DbResult<()> {
self.core.clean_shutdown()
}
fn dirty_shards(&self) -> Option<usize> {
Some(self.core.dirty_shards())
}
}
#[cfg(test)]
#[cfg(feature = "segmented")]
mod managed_tests {
use super::*;
use crate::seg::testkit::{TestKey, TextCodec, meta, ordered_key};
#[test]
fn maintenance_write_needs_the_capability_for_its_collection() {
use crate::index_maintenance::IndexMaintenance;
let dir = tempfile::tempdir().unwrap();
let tree = SegTree::<TestKey, String, TextCodec>::open_with(
dir.path(),
meta(),
&[],
SegConfig::test(),
TextCodec,
OpenOptions {
worker: false,
..OpenOptions::production()
},
)
.unwrap();
let key = ordered_key(1);
assert!(matches!(
tree.maintenance_write(key.as_slice(), Some(b"v")),
Err(DbError::Config(_))
));
{
let _other = IndexMaintenance::enter("another_collection");
assert!(matches!(
tree.maintenance_write(key.as_slice(), Some(b"v")),
Err(DbError::Config(_))
));
}
assert_eq!(
tree.try_get(&key).unwrap(),
None,
"refused writes apply nothing"
);
let _cap = IndexMaintenance::enter(tree.name());
assert!(matches!(
tree.maintenance_write(&key[1..], Some(b"v")),
Err(DbError::CorruptedEntry { .. })
));
assert!(
matches!(
tree.maintenance_write(key.as_slice(), Some(b"v")),
Err(DbError::Config(_))
),
"even a failed mutation spends its grant"
);
let _put = IndexMaintenance::enter(tree.name());
tree.maintenance_write(key.as_slice(), Some(b"v")).unwrap();
assert_eq!(tree.try_get(&key).unwrap().as_deref(), Some("v"));
let _delete = IndexMaintenance::enter(tree.name());
tree.maintenance_write(key.as_slice(), None).unwrap();
assert_eq!(tree.try_get(&key).unwrap(), None);
}
#[test]
fn migration_walk_does_not_pin_or_revisit_frozen_generations() {
let dir = tempfile::tempdir().unwrap();
let tree = SegTree::<TestKey, String, TextCodec>::open_with(
dir.path(),
meta(),
&[],
SegConfig {
seal_max_keys: 10_000,
max_frozen_generations: 8,
..SegConfig::test()
},
TextCodec,
OpenOptions {
worker: false,
..OpenOptions::production()
},
)
.unwrap();
for n in 0..1000 {
tree.put(&ordered_key(n), &format!("old{n}")).unwrap();
}
let retired = Arc::downgrade(&tree.core.view().active);
let mut seen = std::collections::BTreeSet::new();
tree.walk_rows(true, &mut |row| {
let (key, value) = row.unwrap();
assert!(value.starts_with("old"));
assert!(seen.insert(key));
tree.core.put(&key, b"rewritten").unwrap();
if seen.len() % 200 == 0 {
tree.seal().unwrap();
tree.core.seal_oldest().unwrap();
assert!(
retired.upgrade().is_none(),
"callback must not pin the retired index"
);
}
ControlFlow::Continue(())
});
assert_eq!(seen.len(), 1000);
let mut visited = 0;
tree.walk_rows(true, &mut |_| {
visited += 1;
ControlFlow::Break(())
});
assert_eq!(visited, 1, "full scans preserve early-stop callbacks");
}
}