noxu_db/
extinction_filter.rs

1//! Filter interface for identifying extinct records.
2//!
3//!
4//! # Record Extinction
5//!
6//! Record extinction is an optimized deletion mechanism for large sets of
7//! records that are known to be permanently unused. Instead of logging a
8//! delete entry per record, a single `Environment::discard_extinct_records`
9//! call logs one entry covering the entire key range, and the cleaner
10//! asynchronously removes the records and reclaims disk space.
11//!
12//! **Semantics**: Once records are marked extinct via
13//! `discard_extinct_records`, the application must not read or write them
14//! again. does not guarantee transactional semantics for extinct records.
15//!
16//! ExtinctionFilter.ExtinctionStatus` (extended fork 18.1+).
17
18/// Classification returned by [`ExtinctionFilter::get_extinction_status`].
19///
20///
21#[derive(Debug, Clone, Copy, PartialEq, Eq)]
22pub enum ExtinctionStatus {
23    /// The record is extinct: it was specified in a previous
24    /// `discard_extinct_records` call and will never be accessed again.
25    ///
26    ///
27    Extinct,
28
29    /// The record is not extinct: it has not been specified for extinction.
30    ///
31    ///
32    NotExtinct,
33
34    /// The record may or may not be extinct. The application temporarily
35    /// cannot determine extinction status (e.g. during startup before
36    /// metadata is loaded). The cleaner will fall back to a BTree lookup.
37    ///
38    ///
39    MaybeExtinct,
40}
41
42/// Callback for classifying records as extinct.
43///
44///
45///
46/// Implement this trait and register it with `EnvironmentConfig` before
47/// calling `crate::Environment::discard_extinct_records`.
48///
49/// # Requirements
50///
51/// For every key previously specified in `discard_extinct_records`, this
52/// method **must** return [`ExtinctionStatus::Extinct`] or
53/// [`ExtinctionStatus::MaybeExtinct`]. Returning
54/// [`ExtinctionStatus::NotExtinct`] for an extinct key is a contract
55/// violation and may trigger an `EnvironmentFailureException`.
56pub trait ExtinctionFilter: Send + Sync {
57    /// Determine the extinction status of a record.
58    ///
59    /// # Arguments
60    ///
61    /// * `db_name` — name of the database containing the record.
62    /// * `dups` — whether the database uses duplicate keys (secondary DB).
63    /// * `key` — the primary key of the record. When `dups` is true this is
64    ///   the record's data field, treated as a primary key.
65    ///
66    ///
67    fn get_extinction_status(
68        &self,
69        db_name: &str,
70        dups: bool,
71        key: &[u8],
72    ) -> ExtinctionStatus;
73}
74
75#[cfg(test)]
76mod tests {
77    use super::*;
78
79    struct AlwaysExtinct;
80
81    impl ExtinctionFilter for AlwaysExtinct {
82        fn get_extinction_status(
83            &self,
84            _db_name: &str,
85            _dups: bool,
86            _key: &[u8],
87        ) -> ExtinctionStatus {
88            ExtinctionStatus::Extinct
89        }
90    }
91
92    #[test]
93    fn test_always_extinct() {
94        let f = AlwaysExtinct;
95        assert_eq!(
96            f.get_extinction_status("mydb", false, b"key1"),
97            ExtinctionStatus::Extinct
98        );
99    }
100
101    #[test]
102    fn test_status_eq() {
103        assert_eq!(ExtinctionStatus::Extinct, ExtinctionStatus::Extinct);
104        assert_ne!(ExtinctionStatus::Extinct, ExtinctionStatus::NotExtinct);
105    }
106}
noxu_db/extinction_filter.rs

noxu_db/
extinction_filter.rs
