leveldb/database/
iterator.rs

1//! leveldb iterators
2//!
3//! Iteration is one of the most important parts of leveldb. This module provides
4//! Iterators to iterate over key, values and pairs of both.
5use leveldb_sys::*;
6use libc::{size_t, c_char};
7use std::iter;
8use super::Database;
9use super::options::{ReadOptions, c_readoptions};
10use std::slice::from_raw_parts;
11use std::marker::PhantomData;
12use crate::database::snapshots::Snapshot;
13
14#[allow(missing_docs)]
15struct RawIterator {
16    ptr: *mut leveldb_iterator_t,
17}
18
19#[allow(missing_docs)]
20impl Drop for RawIterator {
21    fn drop(&mut self) {
22        unsafe { leveldb_iter_destroy(self.ptr) }
23    }
24}
25
26/// An iterator over the leveldb keyspace.
27///
28/// Returns key and value as a tuple.
29pub struct Iterator<'a> {
30    iter: RawIterator,
31    // Iterator accesses the Database through a leveldb_iter_t pointer
32    // but needs to hold the reference for lifetime tracking
33    #[allow(dead_code)]
34    database: PhantomData<&'a Database>,
35
36}
37
38/// An iterator over the leveldb keyspace  that browses the keys backwards.
39///
40/// Returns key and value as a tuple.
41pub struct RevIterator<'a> {
42    iter: RawIterator,
43    // Iterator accesses the Database through a leveldb_iter_t pointer
44    // but needs to hold the reference for lifetime tracking
45    #[allow(dead_code)]
46    database: PhantomData<&'a Database>,
47}
48
49/// An iterator over the leveldb keyspace.
50///
51/// Returns just the keys.
52pub struct KeyIterator<'a> {
53    inner: Iterator<'a>,
54}
55
56/// An iterator over the leveldb keyspace that browses the keys backwards.
57///
58/// Returns just the keys.
59pub struct RevKeyIterator<'a> {
60    inner: RevIterator<'a>,
61}
62
63/// An iterator over the leveldb keyspace.
64///
65/// Returns just the value.
66pub struct ValueIterator<'a> {
67    inner: Iterator<'a>,
68}
69
70/// An iterator over the leveldb keyspace that browses the keys backwards.
71///
72/// Returns just the value.
73pub struct RevValueIterator<'a> {
74    inner: RevIterator<'a>,
75}
76
77/// A trait to allow access to the three main iteration styles of leveldb.
78pub trait Iterable<'a> {
79    /// Return an Iterator iterating over (Key,Value) pairs
80    fn iter(&'a self, options: &ReadOptions) -> Iterator<'a>;
81    /// Returns an Iterator iterating over Keys only.
82    fn keys_iter(&'a self, options: &ReadOptions) -> KeyIterator<'a>;
83    /// Returns an Iterator iterating over Values only.
84    fn value_iter(&'a self, options: &ReadOptions) -> ValueIterator<'a>;
85}
86
87impl<'a> Iterable<'a> for Database {
88    fn iter(&'a self, options: &ReadOptions) -> Iterator<'a> {
89        Iterator::new(self, options, None)
90    }
91
92    fn keys_iter(&'a self, options: &ReadOptions) -> KeyIterator<'a> {
93        KeyIterator::new(self, options, None)
94    }
95
96    fn value_iter(&'a self, options: &ReadOptions) -> ValueIterator<'a> {
97        ValueIterator::new(self, options, None)
98    }
99}
100
101pub trait LevelDBIterator<'a> {
102    type RevIter: LevelDBIterator<'a>;
103
104    fn raw_iterator(&self) -> *mut leveldb_iterator_t;
105
106    fn reverse(self) -> Self::RevIter;
107
108    fn valid(&self) -> bool {
109        unsafe { leveldb_iter_valid(self.raw_iterator()) != 0 }
110    }
111
112    #[inline]
113    unsafe fn advance_raw(&mut self) {
114        leveldb_iter_next(self.raw_iterator());
115    }
116
117    fn advance(&mut self) {
118        unsafe { self.advance_raw(); }
119    }
120
121    fn key(&self) -> Vec<u8> {
122        unsafe {
123            let length: size_t = 0;
124            let value = leveldb_iter_key(self.raw_iterator(), &length) as *const u8;
125            from_raw_parts(value, length as usize).to_vec()
126        }
127    }
128
129    fn value(&self) -> Vec<u8> {
130        unsafe {
131            let length: size_t = 0;
132            let value = leveldb_iter_value(self.raw_iterator(), &length) as *const u8;
133            from_raw_parts(value, length as usize).to_vec()
134        }
135    }
136
137    fn entry(&self) -> (Vec<u8>, Vec<u8>) {
138        (self.key(), self.value())
139    }
140
141    fn seek_to_first(&self) {
142        unsafe { leveldb_iter_seek_to_first(self.raw_iterator()); }
143    }
144
145    fn seek_to_last(&self) {
146        unsafe {
147                leveldb_iter_seek_to_last(self.raw_iterator());
148        }
149    }
150
151    fn seek(&self, key: &[u8]) {
152        unsafe {
153            leveldb_iter_seek(self.raw_iterator(), key.as_ptr() as *mut c_char, key.len() as size_t);
154        }
155    }
156}
157
158impl<'a> Iterator<'a> {
159    pub fn new(database: &'a Database, options: &ReadOptions, snapshot: Option<&'a Snapshot>) -> Iterator<'a> {
160        unsafe {
161            let c_read_options = c_readoptions(options);
162
163            if let Some(snapshot) = snapshot {
164                leveldb_readoptions_set_snapshot(c_read_options, snapshot.raw_ptr());
165            }
166
167            let ptr = leveldb_create_iterator(database.database.ptr, c_read_options);
168
169            leveldb_readoptions_destroy(c_read_options);
170            leveldb_iter_seek_to_first(ptr);
171
172            Iterator {
173                iter: RawIterator { ptr },
174                database: PhantomData,
175            }
176        }
177    }
178
179    /// return the last element of the iterator
180    pub fn last(&self) -> Option<(Vec<u8>, Vec<u8>)> {
181        self.seek_to_last();
182        Some((self.key(), self.value()))
183    }
184}
185
186impl<'a> LevelDBIterator<'a> for Iterator<'a> {
187    type RevIter = RevIterator<'a>;
188
189    #[inline]
190    fn raw_iterator(&self) -> *mut leveldb_iterator_t {
191        self.iter.ptr
192    }
193
194    fn reverse(self) -> Self::RevIter {
195        self.seek_to_last();
196
197        RevIterator {
198            database: self.database,
199            iter: self.iter,
200        }
201    }
202}
203
204impl<'a> LevelDBIterator<'a> for RevIterator<'a> {
205    type RevIter = Iterator<'a>;
206
207    #[inline]
208    fn raw_iterator(&self) -> *mut leveldb_iterator_t {
209        self.iter.ptr
210    }
211
212    fn reverse(self) -> Self::RevIter {
213        self.seek_to_last();
214
215        Iterator {
216            database: self.database,
217            iter: self.iter,
218        }
219    }
220
221    #[inline]
222    unsafe fn advance_raw(&mut self) {
223        leveldb_iter_prev(self.raw_iterator());
224    }
225}
226
227impl<'a> KeyIterator<'a> {
228    pub fn new(database: &'a Database, options: &ReadOptions, snapshot: Option<&'a Snapshot>) -> KeyIterator<'a> {
229        KeyIterator { inner: Iterator::new(database, options, snapshot) }
230    }
231
232    /// return the last element of the iterator
233    pub fn last(self) -> Option<Vec<u8>> {
234        self.seek_to_last();
235        Some(self.key())
236    }
237}
238
239impl<'a> ValueIterator<'a> {
240    pub fn new(database: &'a Database, options: &ReadOptions, snapshot: Option<&'a Snapshot>) -> ValueIterator<'a> {
241        ValueIterator { inner: Iterator::new(database, options, snapshot) }
242    }
243
244    /// return the last element of the iterator
245    pub fn last(self) -> Option<Vec<u8>> {
246        self.seek_to_last();
247        Some(self.value())
248    }
249}
250
251macro_rules! impl_leveldb_iterator {
252    ($T:ty, $RevT:ty) => {
253        impl<'a> LevelDBIterator<'a> for $T {
254            type RevIter = $RevT;
255
256            #[inline]
257            fn raw_iterator(&self) -> *mut leveldb_iterator_t {
258                self.inner.iter.ptr
259            }
260
261            #[inline]
262            unsafe fn advance_raw(&mut self) {
263                self.inner.advance_raw();
264            }
265
266            #[inline]
267            fn reverse(self) -> Self::RevIter {
268                Self::RevIter { inner: self.inner.reverse() }
269            }
270        }
271    };
272}
273
274impl_leveldb_iterator!(KeyIterator<'a>, RevKeyIterator<'a>);
275impl_leveldb_iterator!(RevKeyIterator<'a>, KeyIterator<'a>);
276impl_leveldb_iterator!(ValueIterator<'a>, RevValueIterator<'a>);
277impl_leveldb_iterator!(RevValueIterator<'a>, ValueIterator<'a>);
278
279macro_rules! impl_iterator {
280    ($T:ty, $Item:ty, $ItemMethod:ident) => {
281        impl<'a> iter::Iterator for $T {
282            type Item = $Item;
283
284            fn next(&mut self) -> Option<Self::Item> {
285                if (self.valid()) {
286                    let ret = Some(self.$ItemMethod());
287                    self.advance();
288
289                    ret
290                } else {
291                    None
292                }
293            }
294        }
295    };
296}
297
298impl_iterator!(Iterator<'a>, (Vec<u8>,Vec<u8>), entry);
299impl_iterator!(RevIterator<'a>, (Vec<u8>,Vec<u8>), entry);
300impl_iterator!(KeyIterator<'a>, Vec<u8>, key);
301impl_iterator!(RevKeyIterator<'a>, Vec<u8>, key);
302impl_iterator!(ValueIterator<'a>, Vec<u8>, value);
303impl_iterator!(RevValueIterator<'a>, Vec<u8>, key);
leveldb/database/iterator.rs

leveldb/database/
iterator.rs
