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}