noxu-db 4.0.0

Noxu DB - An embedded transactional database engine
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

//! Filter interface for identifying extinct records.
//!
//!
//! # Record Extinction
//!
//! Record extinction is an optimized deletion mechanism for large sets of
//! records that are known to be permanently unused. Instead of logging a
//! delete entry per record, a single `Environment::discard_extinct_records`
//! call logs one entry covering the entire key range, and the cleaner
//! asynchronously removes the records and reclaims disk space.
//!
//! **Semantics**: Once records are marked extinct via
//! `discard_extinct_records`, the application must not read or write them
//! again. does not guarantee transactional semantics for extinct records.
//!
//! ExtinctionFilter.ExtinctionStatus` (extended fork 18.1+).

/// Classification returned by [`ExtinctionFilter::get_extinction_status`].
///
///
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ExtinctionStatus {
    /// The record is extinct: it was specified in a previous
    /// `discard_extinct_records` call and will never be accessed again.
    ///
    ///
    Extinct,

    /// The record is not extinct: it has not been specified for extinction.
    ///
    ///
    NotExtinct,

    /// The record may or may not be extinct. The application temporarily
    /// cannot determine extinction status (e.g. during startup before
    /// metadata is loaded). The cleaner will fall back to a BTree lookup.
    ///
    ///
    MaybeExtinct,
}

/// Callback for classifying records as extinct.
///
///
///
/// Implement this trait and register it with `EnvironmentConfig` before
/// calling `crate::Environment::discard_extinct_records`.
///
/// # Requirements
///
/// For every key previously specified in `discard_extinct_records`, this
/// method **must** return [`ExtinctionStatus::Extinct`] or
/// [`ExtinctionStatus::MaybeExtinct`]. Returning
/// [`ExtinctionStatus::NotExtinct`] for an extinct key is a contract
/// violation and may trigger an `EnvironmentFailureException`.
pub trait ExtinctionFilter: Send + Sync {
    /// Determine the extinction status of a record.
    ///
    /// # Arguments
    ///
    /// * `db_name` — name of the database containing the record.
    /// * `dups` — whether the database uses duplicate keys (secondary DB).
    /// * `key` — the primary key of the record. When `dups` is true this is
    ///   the record's data field, treated as a primary key.
    ///
    ///
    fn get_extinction_status(
        &self,
        db_name: &str,
        dups: bool,
        key: &[u8],
    ) -> ExtinctionStatus;
}

#[cfg(test)]
mod tests {
    use super::*;

    struct AlwaysExtinct;

    impl ExtinctionFilter for AlwaysExtinct {
        fn get_extinction_status(
            &self,
            _db_name: &str,
            _dups: bool,
            _key: &[u8],
        ) -> ExtinctionStatus {
            ExtinctionStatus::Extinct
        }
    }

    #[test]
    fn test_always_extinct() {
        let f = AlwaysExtinct;
        assert_eq!(
            f.get_extinction_status("mydb", false, b"key1"),
            ExtinctionStatus::Extinct
        );
    }

    #[test]
    fn test_status_eq() {
        assert_eq!(ExtinctionStatus::Extinct, ExtinctionStatus::Extinct);
        assert_ne!(ExtinctionStatus::Extinct, ExtinctionStatus::NotExtinct);
    }
}