foundationdb/
mapped_key_values.rs

1// Copyright 2022 foundationdb-rs developers, https://github.com/Clikengo/foundationdb-rs/graphs/contributors
2// Copyright 2013-2018 Apple, Inc and the FoundationDB project authors.
3//
4// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
5// http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
6// http://opensource.org/licenses/MIT>, at your option. This file may not be
7// copied, modified, or distributed except according to those terms.
8
9//! Definitions of MappedKeyValues, used in api version 710 and more.
10//!
11//! GetMappedRange is an experimental feature introduced in FDB 7.1. It is intended to improve the
12//! client throughput and reduce latency for a commonly used traffic pattern.
13//! An experiment with Record Layer shows that this optimization can get 4x client throughput on a certain workload.
14//!
15//! More info can be found in the [relevant documentation](https://github.com/apple/foundationdb/wiki/Everything-about-GetMappedRange).
16
17use crate::from_raw_fdb_slice;
18use crate::future::{FdbFutureHandle, FdbKeyValue};
19use crate::{error, KeySelector};
20use crate::{FdbError, FdbResult};
21use foundationdb_sys as fdb_sys;
22use std::fmt;
23
24use std::ops::Deref;
25use std::sync::Arc;
26
27/// An slice of mapped keyvalues owned by a foundationDB future produced by the `get_mapped` method.
28pub struct MappedKeyValues {
29    _f: FdbFutureHandle,
30    mapped_keyvalues: *const FdbMappedKeyValue,
31    len: i32,
32    more: bool,
33}
34unsafe impl Sync for MappedKeyValues {}
35unsafe impl Send for MappedKeyValues {}
36
37impl MappedKeyValues {
38    /// `true` if there is another range after this one
39    pub fn more(&self) -> bool {
40        self.more
41    }
42}
43
44impl TryFrom<FdbFutureHandle> for MappedKeyValues {
45    type Error = FdbError;
46    fn try_from(f: FdbFutureHandle) -> FdbResult<Self> {
47        let mut mapped_keyvalues = std::ptr::null();
48        let mut len = 0;
49        let mut more = 0;
50
51        unsafe {
52            error::eval(fdb_sys::fdb_future_get_mappedkeyvalue_array(
53                f.as_ptr(),
54                &mut mapped_keyvalues,
55                &mut len,
56                &mut more,
57            ))?
58        }
59
60        Ok(MappedKeyValues {
61            _f: f,
62            mapped_keyvalues: mapped_keyvalues as *const FdbMappedKeyValue,
63            len,
64            more: more != 0,
65        })
66    }
67}
68
69#[repr(C, packed)]
70/// A KeyValue produced by a mapped operation, ownder by a Foundation Future.
71pub struct FdbMappedKeyValue(fdb_sys::FDBMappedKeyValue);
72
73impl PartialEq for FdbMappedKeyValue {
74    fn eq(&self, other: &Self) -> bool {
75        (self.parent_key(), self.parent_value()) == (other.parent_key(), other.parent_value())
76    }
77}
78impl Eq for FdbMappedKeyValue {}
79impl fmt::Debug for FdbMappedKeyValue {
80    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
81        write!(
82            f,
83            "({:?}, {:?})",
84            crate::tuple::Bytes::from(self.parent_key()),
85            crate::tuple::Bytes::from(self.parent_value())
86        )
87    }
88}
89
90impl FdbMappedKeyValue {
91    /// Retrieves the "parent" key that generated the secondary scan.
92    pub fn parent_key(&self) -> &[u8] {
93        from_raw_fdb_slice(self.0.key.key, self.0.key.key_length as usize)
94    }
95
96    /// Retrieves the "parent" value that generated the secondary scan.
97    pub fn parent_value(&self) -> &[u8] {
98        from_raw_fdb_slice(self.0.value.key, self.0.value.key_length as usize)
99    }
100
101    /// Retrieves the beginning of the range
102    pub fn begin_range(&self) -> &[u8] {
103        from_raw_fdb_slice(
104            self.0.getRange.begin.key.key,
105            self.0.getRange.begin.key.key_length as usize,
106        )
107    }
108
109    /// Retrieves the end of the range
110    pub fn end_range(&self) -> &[u8] {
111        from_raw_fdb_slice(
112            self.0.getRange.end.key.key,
113            self.0.getRange.end.key.key_length as usize,
114        )
115    }
116
117    /// Retrieves the beginning of the range as a [`KeySelector`]
118    pub fn begin_selector(&self) -> KeySelector<'_> {
119        KeySelector::first_greater_or_equal(self.begin_range())
120    }
121
122    /// Retrieves the end of the range as a [`KeySelector`]
123    pub fn end_selector(&self) -> KeySelector<'_> {
124        KeySelector::first_greater_or_equal(self.end_range())
125    }
126
127    /// retrieves the associated slice of [`FdbKeyValue`]
128    pub fn key_values(&self) -> &[FdbKeyValue] {
129        from_raw_fdb_slice(
130            self.0.getRange.data as *const FdbKeyValue,
131            self.0.getRange.m_size as usize,
132        )
133    }
134}
135
136impl Deref for MappedKeyValues {
137    type Target = [FdbMappedKeyValue];
138
139    fn deref(&self) -> &Self::Target {
140        assert_eq_size!(FdbMappedKeyValue, fdb_sys::FDBMappedKeyValue);
141        assert_eq_align!(FdbMappedKeyValue, u8);
142        from_raw_fdb_slice(self.mapped_keyvalues, self.len as usize)
143    }
144}
145
146impl AsRef<[FdbMappedKeyValue]> for MappedKeyValues {
147    fn as_ref(&self) -> &[FdbMappedKeyValue] {
148        self.deref()
149    }
150}
151
152impl<'a> IntoIterator for &'a MappedKeyValues {
153    type Item = &'a FdbMappedKeyValue;
154    type IntoIter = std::slice::Iter<'a, FdbMappedKeyValue>;
155
156    fn into_iter(self) -> Self::IntoIter {
157        self.deref().iter()
158    }
159}
160
161/// An FdbMappedValue that you can own.
162pub struct FdbMappedValue {
163    _f: Arc<FdbFutureHandle>,
164    mapped_keyvalue: *const FdbMappedKeyValue,
165}
166
167impl IntoIterator for MappedKeyValues {
168    type Item = FdbMappedValue;
169    type IntoIter = FdbMappedValuesIter;
170
171    fn into_iter(self) -> Self::IntoIter {
172        FdbMappedValuesIter {
173            f: Arc::new(self._f),
174            mapped_keyvalues: self.mapped_keyvalues,
175            len: self.len,
176            pos: 0,
177        }
178    }
179}
180
181unsafe impl Send for FdbMappedValue {}
182
183impl Deref for FdbMappedValue {
184    type Target = FdbMappedKeyValue;
185    fn deref(&self) -> &Self::Target {
186        assert_eq_size!(FdbMappedKeyValue, fdb_sys::FDBMappedKeyValue);
187        assert_eq_align!(FdbMappedKeyValue, u8);
188        unsafe { &*self.mapped_keyvalue }
189    }
190}
191impl AsRef<FdbMappedKeyValue> for FdbMappedValue {
192    fn as_ref(&self) -> &FdbMappedKeyValue {
193        self.deref()
194    }
195}
196impl PartialEq for FdbMappedValue {
197    fn eq(&self, other: &Self) -> bool {
198        self.deref() == other.deref()
199    }
200}
201impl Eq for FdbMappedValue {}
202
203/// An iterator of mapped keyvalues owned by a foundationDB future
204pub struct FdbMappedValuesIter {
205    f: Arc<FdbFutureHandle>,
206    mapped_keyvalues: *const FdbMappedKeyValue,
207    len: i32,
208    pos: i32,
209}
210
211unsafe impl Send for FdbMappedValuesIter {}
212
213impl Iterator for FdbMappedValuesIter {
214    type Item = FdbMappedValue;
215    fn next(&mut self) -> Option<Self::Item> {
216        #[allow(clippy::iter_nth_zero)]
217        self.nth(0)
218    }
219
220    fn nth(&mut self, n: usize) -> Option<Self::Item> {
221        let pos = (self.pos as usize).checked_add(n);
222        match pos {
223            Some(pos) if pos < self.len as usize => {
224                // safe because pos < self.len
225                let mapped_keyvalue = unsafe { self.mapped_keyvalues.add(pos) };
226                self.pos = pos as i32 + 1;
227
228                Some(FdbMappedValue {
229                    _f: self.f.clone(),
230                    mapped_keyvalue,
231                })
232            }
233            _ => {
234                self.pos = self.len;
235                None
236            }
237        }
238    }
239
240    fn size_hint(&self) -> (usize, Option<usize>) {
241        let rem = (self.len - self.pos) as usize;
242        (rem, Some(rem))
243    }
244}
245impl ExactSizeIterator for FdbMappedValuesIter {
246    #[inline]
247    fn len(&self) -> usize {
248        (self.len - self.pos) as usize
249    }
250}
251impl DoubleEndedIterator for FdbMappedValuesIter {
252    fn next_back(&mut self) -> Option<Self::Item> {
253        self.nth_back(0)
254    }
255
256    fn nth_back(&mut self, n: usize) -> Option<Self::Item> {
257        if n < self.len() {
258            self.len -= 1 + n as i32;
259            // safe because len < original len
260            let keyvalue = unsafe { self.mapped_keyvalues.add(self.len as usize) };
261            Some(FdbMappedValue {
262                _f: self.f.clone(),
263                mapped_keyvalue: keyvalue,
264            })
265        } else {
266            self.pos = self.len;
267            None
268        }
269    }
270}