masstree 0.9.5

A high-performance concurrent ordered map (trie of B+trees)
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
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

//! Reference-based range scan methods for [`crate::MassTreeGeneric`].
//!
//! These methods require [`RefLeafPolicy`] and return `&V` references.
//! Not available for `MassTree15Inline` (inline storage has no stable address).
//!
//! ```compile_fail
//! use masstree::{MassTree15Inline, RangeBound};
//!
//! let tree: MassTree15Inline<u64> = MassTree15Inline::new();
//! let guard = tree.guard();
//!
//! // Not available for true-inline storage.
//! tree.scan_ref(
//!     RangeBound::Unbounded,
//!     RangeBound::Unbounded,
//!     |_k, _v| true,
//!     &guard,
//! );
//! ```

use seize::LocalGuard;

use crate::alloc_trait::TreeAllocator;
use crate::policy::LeafPolicy;
use crate::policy::RefPolicy as RefLeafPolicy;
use crate::tree::MassTreeGeneric;

use super::iterator::RangeBound;

// ============================================================================
//  Reference-Based Scan API (requires RefLeafPolicy)
// ============================================================================

impl<P, A> MassTreeGeneric<P, A>
where
    P: LeafPolicy + RefLeafPolicy,
    A: TreeAllocator<P>,
{
    /// Scan a range with zero-copy `&V` references.
    ///
    /// Eliminates 2 atomic ops per entry vs [`Self::scan`] (no Arc increment).
    /// Value references are only valid for the callback duration.
    ///
    /// ```ignore
    /// let guard = tree.guard();
    /// let mut sum = 0u64;
    /// tree.scan_ref(
    ///     RangeBound::Unbounded, RangeBound::Unbounded,
    ///     |_key, value| { sum += *value; true },
    ///     &guard
    /// );
    /// ```
    pub fn scan_ref<F>(
        &self,
        start: RangeBound<'_>,
        end: RangeBound<'_>,
        visitor: F,
        guard: &LocalGuard<'_>,
    ) -> usize
    where
        F: FnMut(&[u8], &P::Value) -> bool,
    {
        self.range_forward(start, end, guard).for_each_ref(visitor)
    }

    /// Batch scan with zero-copy references and reduced dispatch overhead.
    ///
    /// Eliminates `match state {}` dispatch per entry vs [`scan_ref`](Self::scan_ref),
    /// inlining the common `FindNext` -> `Emit` path. Same OCC and correctness
    /// guarantees.
    ///
    /// ```ignore
    /// let guard = tree.guard();
    /// let mut sum = 0u64;
    /// tree.scan_batch_ref(
    ///     RangeBound::Unbounded, RangeBound::Unbounded,
    ///     |_key, value| { sum += *value; true },
    ///     &guard
    /// );
    /// ```
    pub fn scan_batch_ref<F>(
        &self,
        start: RangeBound<'_>,
        end: RangeBound<'_>,
        visitor: F,
        guard: &LocalGuard<'_>,
    ) -> usize
    where
        F: FnMut(&[u8], &P::Value) -> bool,
    {
        self.range_forward(start, end, guard)
            .for_each_batch_ref(visitor)
    }

    /// Intra-leaf batch scan with zero-copy references — highest performance.
    ///
    /// Processes entire leaves in tight loops with single OCC validation per
    /// leaf. Falls back to state machine for sublayer transitions.
    ///
    /// ```ignore
    /// let guard = tree.guard();
    /// let mut sum = 0u64;
    /// tree.scan_intra_leaf_batch_ref(
    ///     RangeBound::Unbounded, RangeBound::Unbounded,
    ///     |_key, value| { sum += *value; true },
    ///     &guard
    /// );
    /// ```
    pub fn scan_intra_leaf_batch_ref<F>(
        &self,
        start: RangeBound<'_>,
        end: RangeBound<'_>,
        visitor: F,
        guard: &LocalGuard<'_>,
    ) -> usize
    where
        F: FnMut(&[u8], &P::Value) -> bool,
    {
        self.range_forward(start, end, guard)
            .for_each_intra_leaf_batch_ref(visitor)
    }

    /// Reverse intra-leaf batch scan with zero-copy references.
    ///
    /// Same perf characteristics as [`scan_intra_leaf_batch_ref`](Self::scan_intra_leaf_batch_ref)
    /// but in descending key order.
    ///
    /// ```ignore
    /// let guard = tree.guard();
    /// let mut sum = 0u64;
    /// tree.scan_rev_batch_ref(
    ///     RangeBound::Unbounded, RangeBound::Unbounded,
    ///     |_key, value| { sum += *value; true },
    ///     &guard
    /// );
    /// ```
    pub fn scan_rev_batch_ref<F>(
        &self,
        start: RangeBound<'_>,
        end: RangeBound<'_>,
        visitor: F,
        guard: &LocalGuard<'_>,
    ) -> usize
    where
        F: FnMut(&[u8], &P::Value) -> bool,
    {
        self.range(start, end, guard).rev_for_each_ref(visitor)
    }
}