]>
Commit | Line | Data |
---|---|---|
7c673cae | 1 | // Copyright (c) 2011-present, Facebook, Inc. All rights reserved. |
11fdf7f2 TL |
2 | // This source code is licensed under both the GPLv2 (found in the |
3 | // COPYING file in the root directory) and Apache 2.0 License | |
4 | // (found in the LICENSE.Apache file in the root directory). | |
7c673cae FG |
5 | // Copyright (c) 2011 The LevelDB Authors. All rights reserved. |
6 | // Use of this source code is governed by a BSD-style license that can be | |
7 | // found in the LICENSE file. See the AUTHORS file for names of contributors. | |
8 | // | |
9 | // An iterator yields a sequence of key/value pairs from a source. | |
10 | // The following class defines the interface. Multiple implementations | |
11 | // are provided by this library. In particular, iterators are provided | |
12 | // to access the contents of a Table or a DB. | |
13 | // | |
14 | // Multiple threads can invoke const methods on an Iterator without | |
15 | // external synchronization, but if any of the threads may call a | |
16 | // non-const method, all threads accessing the same Iterator must use | |
17 | // external synchronization. | |
18 | ||
11fdf7f2 | 19 | #pragma once |
7c673cae FG |
20 | |
21 | #include <string> | |
22 | #include "rocksdb/cleanable.h" | |
23 | #include "rocksdb/slice.h" | |
24 | #include "rocksdb/status.h" | |
25 | ||
26 | namespace rocksdb { | |
27 | ||
28 | class Iterator : public Cleanable { | |
29 | public: | |
30 | Iterator() {} | |
31 | virtual ~Iterator() {} | |
32 | ||
33 | // An iterator is either positioned at a key/value pair, or | |
34 | // not valid. This method returns true iff the iterator is valid. | |
11fdf7f2 | 35 | // Always returns false if !status().ok(). |
7c673cae FG |
36 | virtual bool Valid() const = 0; |
37 | ||
38 | // Position at the first key in the source. The iterator is Valid() | |
39 | // after this call iff the source is not empty. | |
40 | virtual void SeekToFirst() = 0; | |
41 | ||
42 | // Position at the last key in the source. The iterator is | |
43 | // Valid() after this call iff the source is not empty. | |
44 | virtual void SeekToLast() = 0; | |
45 | ||
11fdf7f2 | 46 | // Position at the first key in the source that at or past target. |
7c673cae FG |
47 | // The iterator is Valid() after this call iff the source contains |
48 | // an entry that comes at or past target. | |
11fdf7f2 TL |
49 | // All Seek*() methods clear any error status() that the iterator had prior to |
50 | // the call; after the seek, status() indicates only the error (if any) that | |
51 | // happened during the seek, not any past errors. | |
7c673cae FG |
52 | virtual void Seek(const Slice& target) = 0; |
53 | ||
11fdf7f2 | 54 | // Position at the last key in the source that at or before target. |
7c673cae FG |
55 | // The iterator is Valid() after this call iff the source contains |
56 | // an entry that comes at or before target. | |
11fdf7f2 | 57 | virtual void SeekForPrev(const Slice& target) = 0; |
7c673cae FG |
58 | |
59 | // Moves to the next entry in the source. After this call, Valid() is | |
60 | // true iff the iterator was not positioned at the last entry in the source. | |
61 | // REQUIRES: Valid() | |
62 | virtual void Next() = 0; | |
63 | ||
64 | // Moves to the previous entry in the source. After this call, Valid() is | |
65 | // true iff the iterator was not positioned at the first entry in source. | |
66 | // REQUIRES: Valid() | |
67 | virtual void Prev() = 0; | |
68 | ||
69 | // Return the key for the current entry. The underlying storage for | |
70 | // the returned slice is valid only until the next modification of | |
71 | // the iterator. | |
72 | // REQUIRES: Valid() | |
73 | virtual Slice key() const = 0; | |
74 | ||
75 | // Return the value for the current entry. The underlying storage for | |
76 | // the returned slice is valid only until the next modification of | |
77 | // the iterator. | |
11fdf7f2 | 78 | // REQUIRES: Valid() |
7c673cae FG |
79 | virtual Slice value() const = 0; |
80 | ||
81 | // If an error has occurred, return it. Else return an ok status. | |
82 | // If non-blocking IO is requested and this operation cannot be | |
83 | // satisfied without doing some IO, then this returns Status::Incomplete(). | |
84 | virtual Status status() const = 0; | |
85 | ||
11fdf7f2 TL |
86 | // If supported, renew the iterator to represent the latest state. The |
87 | // iterator will be invalidated after the call. Not supported if | |
88 | // ReadOptions.snapshot is given when creating the iterator. | |
89 | virtual Status Refresh() { | |
90 | return Status::NotSupported("Refresh() is not supported"); | |
91 | } | |
92 | ||
7c673cae FG |
93 | // Property "rocksdb.iterator.is-key-pinned": |
94 | // If returning "1", this means that the Slice returned by key() is valid | |
95 | // as long as the iterator is not deleted. | |
96 | // It is guaranteed to always return "1" if | |
97 | // - Iterator created with ReadOptions::pin_data = true | |
98 | // - DB tables were created with | |
99 | // BlockBasedTableOptions::use_delta_encoding = false. | |
100 | // Property "rocksdb.iterator.super-version-number": | |
101 | // LSM version used by the iterator. The same format as DB Property | |
102 | // kCurrentSuperVersionNumber. See its comment for more information. | |
11fdf7f2 TL |
103 | // Property "rocksdb.iterator.internal-key": |
104 | // Get the user-key portion of the internal key at which the iteration | |
105 | // stopped. | |
7c673cae FG |
106 | virtual Status GetProperty(std::string prop_name, std::string* prop); |
107 | ||
108 | private: | |
109 | // No copying allowed | |
110 | Iterator(const Iterator&); | |
111 | void operator=(const Iterator&); | |
112 | }; | |
113 | ||
114 | // Return an empty iterator (yields nothing). | |
115 | extern Iterator* NewEmptyIterator(); | |
116 | ||
117 | // Return an empty iterator with the specified status. | |
118 | extern Iterator* NewErrorIterator(const Status& status); | |
119 | ||
120 | } // namespace rocksdb |