Skip to main content

natdb/
cursor.rs

1use std::marker::PhantomData;
2use std::{fmt, mem, ptr, result, slice};
3
4use libc::{EINVAL, c_uint, c_void, size_t};
5
6use crate::database::Database;
7use crate::error::{Error, Result, lmdb_result};
8use crate::ffi;
9use crate::flags::WriteFlags;
10use crate::transaction::Transaction;
11
12/// An LMDB cursor.
13pub trait Cursor<'txn> {
14    /// Returns a raw pointer to the underlying LMDB cursor.
15    ///
16    /// The caller **must** ensure that the pointer is not used after the
17    /// lifetime of the cursor.
18    fn cursor(&self) -> *mut ffi::MDB_cursor;
19
20    /// Retrieves a key/data pair from the cursor. Depending on the cursor op,
21    /// the current key may be returned.
22    fn get(&self, key: Option<&[u8]>, data: Option<&[u8]>, op: c_uint) -> Result<(Option<&'txn [u8]>, &'txn [u8])> {
23        let mut key_val = slice_to_val(key);
24        let mut data_val = slice_to_val(data);
25        let key_ptr = key_val.mv_data;
26        // SAFETY: `self.cursor()` is live; `key_val`/`data_val` are null or borrow `key`/`data`,
27        // which outlive the call, and LMDB only writes through them as out-parameters.
28        lmdb_result(unsafe { ffi::mdb_cursor_get(self.cursor(), &mut key_val, &mut data_val, op) })?;
29        let key_out = if key_ptr != key_val.mv_data {
30            // SAFETY: LMDB pointed `key_val` at a key inside the map, valid for 'txn.
31            Some(unsafe { val_to_slice(key_val) })
32        } else {
33            None
34        };
35        // SAFETY: on success `data_val` points at data inside the map, valid for 'txn.
36        let data_out = unsafe { val_to_slice(data_val) };
37        Ok((key_out, data_out))
38    }
39
40    /// Iterate over database items. The iterator will begin with item next
41    /// after the cursor, and continue until the end of the database. For new
42    /// cursors, the iterator will begin with the first item in the database.
43    ///
44    /// For databases with duplicate data items (`DatabaseFlags::DUP_SORT`), the
45    /// duplicate data items of each key will be returned before moving on to
46    /// the next key.
47    fn iter(&mut self) -> Iter<'txn> {
48        Iter::new(self.cursor(), ffi::MDB_NEXT, ffi::MDB_NEXT)
49    }
50
51    /// Iterate over database items starting from the beginning of the database.
52    ///
53    /// For databases with duplicate data items (`DatabaseFlags::DUP_SORT`), the
54    /// duplicate data items of each key will be returned before moving on to
55    /// the next key.
56    fn iter_start(&mut self) -> Iter<'txn> {
57        Iter::new(self.cursor(), ffi::MDB_FIRST, ffi::MDB_NEXT)
58    }
59
60    /// Iterate over database items starting from the given key.
61    ///
62    /// For databases with duplicate data items (`DatabaseFlags::DUP_SORT`), the
63    /// duplicate data items of each key will be returned before moving on to
64    /// the next key.
65    fn iter_from<K>(&mut self, key: K) -> Iter<'txn>
66    where
67        K: AsRef<[u8]>,
68    {
69        match self.get(Some(key.as_ref()), None, ffi::MDB_SET_RANGE) {
70            Ok(_) | Err(Error::NotFound) => (),
71            Err(error) => return Iter::Err(error),
72        };
73        Iter::new(self.cursor(), ffi::MDB_GET_CURRENT, ffi::MDB_NEXT)
74    }
75
76    /// Iterate over duplicate database items. The iterator will begin with the
77    /// item next after the cursor, and continue until the end of the database.
78    /// Each item will be returned as an iterator of its duplicates.
79    fn iter_dup(&mut self) -> IterDup<'txn> {
80        IterDup::new(self.cursor(), ffi::MDB_NEXT)
81    }
82
83    /// Iterate over duplicate database items starting from the beginning of the
84    /// database. Each item will be returned as an iterator of its duplicates.
85    fn iter_dup_start(&mut self) -> IterDup<'txn> {
86        IterDup::new(self.cursor(), ffi::MDB_FIRST)
87    }
88
89    /// Iterate over duplicate items in the database starting from the given
90    /// key. Each item will be returned as an iterator of its duplicates.
91    fn iter_dup_from<K>(&mut self, key: K) -> IterDup<'txn>
92    where
93        K: AsRef<[u8]>,
94    {
95        match self.get(Some(key.as_ref()), None, ffi::MDB_SET_RANGE) {
96            Ok(_) | Err(Error::NotFound) => (),
97            Err(error) => return IterDup::Err(error),
98        };
99        IterDup::new(self.cursor(), ffi::MDB_GET_CURRENT)
100    }
101
102    /// Iterate over the duplicates of the item in the database with the given key.
103    fn iter_dup_of<K>(&mut self, key: K) -> Iter<'txn>
104    where
105        K: AsRef<[u8]>,
106    {
107        match self.get(Some(key.as_ref()), None, ffi::MDB_SET) {
108            Ok(_) => (),
109            Err(Error::NotFound) => {
110                self.get(None, None, ffi::MDB_LAST).ok();
111                return Iter::new(self.cursor(), ffi::MDB_NEXT, ffi::MDB_NEXT);
112            },
113            Err(error) => return Iter::Err(error),
114        };
115        Iter::new(self.cursor(), ffi::MDB_GET_CURRENT, ffi::MDB_NEXT_DUP)
116    }
117}
118
119/// A read-only cursor for navigating the items within a database.
120pub struct RoCursor<'txn> {
121    cursor: *mut ffi::MDB_cursor,
122    _marker: PhantomData<fn() -> &'txn ()>,
123}
124
125impl<'txn> Cursor<'txn> for RoCursor<'txn> {
126    fn cursor(&self) -> *mut ffi::MDB_cursor {
127        self.cursor
128    }
129}
130
131impl<'txn> fmt::Debug for RoCursor<'txn> {
132    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> result::Result<(), fmt::Error> {
133        f.debug_struct("RoCursor").finish()
134    }
135}
136
137impl Drop for RoCursor<'_> {
138    fn drop(&mut self) {
139        // SAFETY: `self.cursor` was opened in `RoCursor::new` and is closed only here.
140        unsafe { ffi::mdb_cursor_close(self.cursor) }
141    }
142}
143
144impl<'txn> RoCursor<'txn> {
145    /// Creates a new read-only cursor in the given database and transaction.
146    /// Prefer using `Transaction::open_cursor`.
147    pub(crate) fn new<T>(txn: &'txn T, db: Database) -> Result<RoCursor<'txn>>
148    where
149        T: Transaction,
150    {
151        let mut cursor: *mut ffi::MDB_cursor = ptr::null_mut();
152        // SAFETY: `txn` is live for 'txn and `cursor` is a valid out-pointer.
153        lmdb_result(unsafe { ffi::mdb_cursor_open(txn.txn(), db.dbi(), &mut cursor) })?;
154        Ok(RoCursor {
155            cursor,
156            _marker: PhantomData,
157        })
158    }
159}
160
161/// A read-write cursor for navigating items within a database.
162pub struct RwCursor<'txn> {
163    cursor: *mut ffi::MDB_cursor,
164    _marker: PhantomData<fn() -> &'txn ()>,
165}
166
167/// Read access to the position of a [`RwCursor`], obtained with [`RwCursor::reader`].
168///
169/// Data read through a write transaction points into pages that later writes of
170/// the same transaction may modify. Every slice read through this type
171/// therefore borrows the [`RwCursor`] mutably: the cursor cannot write while
172/// any of those slices is alive.
173///
174/// ```compile_fail
175/// # use natdb::{Cursor, Environment, WriteFlags};
176/// # let dir = std::env::temp_dir().join("natdb_rw_cursor_reader_doc");
177/// # std::fs::create_dir_all(&dir).unwrap();
178/// # let env = Environment::new().open(&dir).unwrap();
179/// # let db = env.open_db(None).unwrap();
180/// let mut txn = env.begin_rw_txn().unwrap();
181/// let mut cursor = txn.open_rw_cursor(db).unwrap();
182/// cursor.put(b"key", b"value", WriteFlags::empty()).unwrap();
183/// let (_, value) = cursor.reader().get(None, None, natdb_sys::MDB_GET_CURRENT).unwrap();
184/// cursor.put(b"key", b"other", WriteFlags::empty()).unwrap(); // error: `cursor` is still borrowed
185/// assert_eq!(value, b"value");
186/// ```
187pub struct RwCursorReader<'cursor> {
188    cursor: *mut ffi::MDB_cursor,
189    _marker: PhantomData<&'cursor mut ()>,
190}
191
192impl<'cursor> Cursor<'cursor> for RwCursorReader<'cursor> {
193    fn cursor(&self) -> *mut ffi::MDB_cursor {
194        self.cursor
195    }
196}
197
198impl fmt::Debug for RwCursorReader<'_> {
199    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> result::Result<(), fmt::Error> {
200        f.debug_struct("RwCursorReader").finish()
201    }
202}
203
204impl<'txn> fmt::Debug for RwCursor<'txn> {
205    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> result::Result<(), fmt::Error> {
206        f.debug_struct("RwCursor").finish()
207    }
208}
209
210impl Drop for RwCursor<'_> {
211    fn drop(&mut self) {
212        // SAFETY: `self.cursor` was opened in `RwCursor::new` and is closed only here.
213        unsafe { ffi::mdb_cursor_close(self.cursor) }
214    }
215}
216
217impl<'txn> RwCursor<'txn> {
218    /// Creates a new read-only cursor in the given database and transaction.
219    /// Prefer using `RwTransaction::open_rw_cursor`.
220    pub(crate) fn new<T>(txn: &'txn T, db: Database) -> Result<RwCursor<'txn>>
221    where
222        T: Transaction,
223    {
224        let mut cursor: *mut ffi::MDB_cursor = ptr::null_mut();
225        // SAFETY: `txn` is live for 'txn and `cursor` is a valid out-pointer.
226        lmdb_result(unsafe { ffi::mdb_cursor_open(txn.txn(), db.dbi(), &mut cursor) })?;
227        Ok(RwCursor {
228            cursor,
229            _marker: PhantomData,
230        })
231    }
232
233    /// Returns read access to this cursor. The slices it yields keep this
234    /// cursor mutably borrowed, so no write can modify them while they are
235    /// alive (see [`RwCursorReader`]).
236    pub fn reader(&mut self) -> RwCursorReader<'_> {
237        RwCursorReader {
238            cursor: self.cursor,
239            _marker: PhantomData,
240        }
241    }
242
243    /// Puts a key/data pair into the database. The cursor will be positioned at
244    /// the new data item, or on failure usually near it.
245    pub fn put<K, D>(&mut self, key: &K, data: &D, flags: WriteFlags) -> Result<()>
246    where
247        K: AsRef<[u8]>,
248        D: AsRef<[u8]>,
249    {
250        let key = key.as_ref();
251        let data = data.as_ref();
252        let mut key_val: ffi::MDB_val = ffi::MDB_val {
253            mv_size: key.len() as size_t,
254            mv_data: key.as_ptr() as *mut c_void,
255        };
256        let mut data_val: ffi::MDB_val = ffi::MDB_val {
257            mv_size: data.len() as size_t,
258            mv_data: data.as_ptr() as *mut c_void,
259        };
260        // SAFETY: `key_val` and `data_val` borrow `key` and `data`, which outlive the call.
261        lmdb_result(unsafe { ffi::mdb_cursor_put(self.cursor, &mut key_val, &mut data_val, flags.bits()) })
262    }
263
264    /// Deletes the current key/data pair.
265    ///
266    /// ### Flags
267    ///
268    /// `WriteFlags::NO_DUP_DATA` may be used to delete all data items for the
269    /// current key, if the database was opened with `DatabaseFlags::DUP_SORT`.
270    pub fn del(&mut self, flags: WriteFlags) -> Result<()> {
271        // SAFETY: `self.cursor()` is a live cursor of a write transaction.
272        lmdb_result(unsafe { ffi::mdb_cursor_del(self.cursor, flags.bits()) })
273    }
274}
275
276fn slice_to_val(slice: Option<&[u8]>) -> ffi::MDB_val {
277    match slice {
278        Some(slice) => ffi::MDB_val {
279            mv_size: slice.len() as size_t,
280            mv_data: slice.as_ptr() as *mut c_void,
281        },
282        None => ffi::MDB_val {
283            mv_size: 0,
284            mv_data: ptr::null_mut(),
285        },
286    }
287}
288
289/// # Safety
290///
291/// `val` must describe `mv_size` initialized bytes at `mv_data` that stay valid and
292/// unmodified for `'a`.
293unsafe fn val_to_slice<'a>(val: ffi::MDB_val) -> &'a [u8] {
294    // SAFETY: guaranteed by the caller.
295    unsafe { slice::from_raw_parts(val.mv_data as *const u8, val.mv_size) }
296}
297
298/// An iterator over the key/value pairs in an LMDB database.
299pub enum Iter<'txn> {
300    /// An iterator that returns an error on every call to Iter.next().
301    /// Cursor.iter*() creates an Iter of this type when LMDB returns an error
302    /// on retrieval of a cursor.  Using this variant instead of returning
303    /// an error makes Cursor.iter()* methods infallible, so consumers only
304    /// need to check the result of Iter.next().
305    Err(Error),
306
307    /// An iterator that returns an Item on calls to Iter.next().
308    /// The Item is a Result<(&'txn [u8], &'txn [u8])>, so this variant
309    /// might still return an error, if retrieval of the key/value pair
310    /// fails for some reason.
311    Ok {
312        /// The LMDB cursor with which to iterate.
313        cursor: *mut ffi::MDB_cursor,
314
315        /// The first operation to perform when the consumer calls Iter.next().
316        op: c_uint,
317
318        /// The next and subsequent operations to perform.
319        next_op: c_uint,
320
321        /// A marker to ensure the iterator doesn't outlive the transaction.
322        _marker: PhantomData<fn(&'txn ())>,
323    },
324}
325
326impl<'txn> Iter<'txn> {
327    /// Creates a new iterator backed by the given cursor.
328    fn new<'t>(cursor: *mut ffi::MDB_cursor, op: c_uint, next_op: c_uint) -> Iter<'t> {
329        Iter::Ok {
330            cursor,
331            op,
332            next_op,
333            _marker: PhantomData,
334        }
335    }
336}
337
338impl<'txn> fmt::Debug for Iter<'txn> {
339    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> result::Result<(), fmt::Error> {
340        f.debug_struct("Iter").finish()
341    }
342}
343
344impl<'txn> Iterator for Iter<'txn> {
345    type Item = Result<(&'txn [u8], &'txn [u8])>;
346
347    fn next(&mut self) -> Option<Result<(&'txn [u8], &'txn [u8])>> {
348        match self {
349            Iter::Ok {
350                cursor,
351                op,
352                next_op,
353                ..
354            } => {
355                let mut key = ffi::MDB_val {
356                    mv_size: 0,
357                    mv_data: ptr::null_mut(),
358                };
359                let mut data = ffi::MDB_val {
360                    mv_size: 0,
361                    mv_data: ptr::null_mut(),
362                };
363                let op = mem::replace(op, *next_op);
364                // SAFETY: `cursor` stays open while the iterator borrows the transaction
365                // ('txn); `key` and `data` are valid out-parameters.
366                match unsafe { ffi::mdb_cursor_get(*cursor, &mut key, &mut data, op) } {
367                    // SAFETY: on success both values point inside the map, valid for 'txn.
368                    ffi::MDB_SUCCESS => Some(Ok(unsafe { (val_to_slice(key), val_to_slice(data)) })),
369                    // EINVAL can occur when the cursor was previously seeked to a non-existent value,
370                    // e.g. iter_from with a key greater than all values in the database.
371                    ffi::MDB_NOTFOUND | EINVAL => None,
372                    error => Some(Err(Error::from_err_code(error))),
373                }
374            },
375            Iter::Err(err) => Some(Err(*err)),
376        }
377    }
378}
379
380/// An iterator over the keys and duplicate values in an LMDB database.
381///
382/// The yielded items of the iterator are themselves iterators over the duplicate values for a
383/// specific key.
384pub enum IterDup<'txn> {
385    /// An iterator that returns an error on every call to Iter.next().
386    /// Cursor.iter*() creates an Iter of this type when LMDB returns an error
387    /// on retrieval of a cursor.  Using this variant instead of returning
388    /// an error makes Cursor.iter()* methods infallible, so consumers only
389    /// need to check the result of Iter.next().
390    Err(Error),
391
392    /// An iterator that returns an Item on calls to Iter.next().
393    /// The Item is a Result<(&'txn [u8], &'txn [u8])>, so this variant
394    /// might still return an error, if retrieval of the key/value pair
395    /// fails for some reason.
396    Ok {
397        /// The LMDB cursor with which to iterate.
398        cursor: *mut ffi::MDB_cursor,
399
400        /// The first operation to perform when the consumer calls Iter.next().
401        op: c_uint,
402
403        /// A marker to ensure the iterator doesn't outlive the transaction.
404        _marker: PhantomData<fn(&'txn ())>,
405    },
406}
407
408impl<'txn> IterDup<'txn> {
409    /// Creates a new iterator backed by the given cursor.
410    fn new<'t>(cursor: *mut ffi::MDB_cursor, op: c_uint) -> IterDup<'t> {
411        IterDup::Ok {
412            cursor,
413            op,
414            _marker: PhantomData,
415        }
416    }
417}
418
419impl<'txn> fmt::Debug for IterDup<'txn> {
420    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> result::Result<(), fmt::Error> {
421        f.debug_struct("IterDup").finish()
422    }
423}
424
425impl<'txn> Iterator for IterDup<'txn> {
426    type Item = Iter<'txn>;
427
428    fn next(&mut self) -> Option<Iter<'txn>> {
429        match self {
430            IterDup::Ok {
431                cursor,
432                op,
433                ..
434            } => {
435                let mut key = ffi::MDB_val {
436                    mv_size: 0,
437                    mv_data: ptr::null_mut(),
438                };
439                let mut data = ffi::MDB_val {
440                    mv_size: 0,
441                    mv_data: ptr::null_mut(),
442                };
443                let op = mem::replace(op, ffi::MDB_NEXT_NODUP);
444                // SAFETY: `cursor` stays open while the iterator borrows the transaction
445                // ('txn); `key` and `data` are valid out-parameters.
446                let err_code = unsafe { ffi::mdb_cursor_get(*cursor, &mut key, &mut data, op) };
447
448                if err_code == ffi::MDB_SUCCESS {
449                    Some(Iter::new(*cursor, ffi::MDB_GET_CURRENT, ffi::MDB_NEXT_DUP))
450                } else {
451                    None
452                }
453            },
454            IterDup::Err(err) => Some(Iter::Err(*err)),
455        }
456    }
457}