]>
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 | ||
f67539c2 | 26 | namespace ROCKSDB_NAMESPACE { |
7c673cae FG |
27 | |
28 | class Iterator : public Cleanable { | |
29 | public: | |
30 | Iterator() {} | |
f67539c2 TL |
31 | // No copying allowed |
32 | Iterator(const Iterator&) = delete; | |
33 | void operator=(const Iterator&) = delete; | |
34 | ||
7c673cae FG |
35 | virtual ~Iterator() {} |
36 | ||
37 | // An iterator is either positioned at a key/value pair, or | |
38 | // not valid. This method returns true iff the iterator is valid. | |
11fdf7f2 | 39 | // Always returns false if !status().ok(). |
7c673cae FG |
40 | virtual bool Valid() const = 0; |
41 | ||
42 | // Position at the first key in the source. The iterator is Valid() | |
43 | // after this call iff the source is not empty. | |
44 | virtual void SeekToFirst() = 0; | |
45 | ||
46 | // Position at the last key in the source. The iterator is | |
47 | // Valid() after this call iff the source is not empty. | |
20effc67 | 48 | // Currently incompatible with user timestamp. |
7c673cae FG |
49 | virtual void SeekToLast() = 0; |
50 | ||
11fdf7f2 | 51 | // Position at the first key in the source that at or past target. |
7c673cae FG |
52 | // The iterator is Valid() after this call iff the source contains |
53 | // an entry that comes at or past target. | |
11fdf7f2 TL |
54 | // All Seek*() methods clear any error status() that the iterator had prior to |
55 | // the call; after the seek, status() indicates only the error (if any) that | |
56 | // happened during the seek, not any past errors. | |
20effc67 | 57 | // Target does not contain timestamp. |
7c673cae FG |
58 | virtual void Seek(const Slice& target) = 0; |
59 | ||
11fdf7f2 | 60 | // Position at the last key in the source that at or before target. |
7c673cae FG |
61 | // The iterator is Valid() after this call iff the source contains |
62 | // an entry that comes at or before target. | |
20effc67 | 63 | // Currently incompatible with user timestamp. |
11fdf7f2 | 64 | virtual void SeekForPrev(const Slice& target) = 0; |
7c673cae FG |
65 | |
66 | // Moves to the next entry in the source. After this call, Valid() is | |
67 | // true iff the iterator was not positioned at the last entry in the source. | |
68 | // REQUIRES: Valid() | |
69 | virtual void Next() = 0; | |
70 | ||
71 | // Moves to the previous entry in the source. After this call, Valid() is | |
72 | // true iff the iterator was not positioned at the first entry in source. | |
20effc67 | 73 | // Currently incompatible with user timestamp. |
7c673cae FG |
74 | // REQUIRES: Valid() |
75 | virtual void Prev() = 0; | |
76 | ||
77 | // Return the key for the current entry. The underlying storage for | |
78 | // the returned slice is valid only until the next modification of | |
79 | // the iterator. | |
80 | // REQUIRES: Valid() | |
81 | virtual Slice key() const = 0; | |
82 | ||
83 | // Return the value for the current entry. The underlying storage for | |
84 | // the returned slice is valid only until the next modification of | |
85 | // the iterator. | |
11fdf7f2 | 86 | // REQUIRES: Valid() |
7c673cae FG |
87 | virtual Slice value() const = 0; |
88 | ||
89 | // If an error has occurred, return it. Else return an ok status. | |
90 | // If non-blocking IO is requested and this operation cannot be | |
91 | // satisfied without doing some IO, then this returns Status::Incomplete(). | |
92 | virtual Status status() const = 0; | |
93 | ||
11fdf7f2 TL |
94 | // If supported, renew the iterator to represent the latest state. The |
95 | // iterator will be invalidated after the call. Not supported if | |
96 | // ReadOptions.snapshot is given when creating the iterator. | |
97 | virtual Status Refresh() { | |
98 | return Status::NotSupported("Refresh() is not supported"); | |
99 | } | |
100 | ||
7c673cae FG |
101 | // Property "rocksdb.iterator.is-key-pinned": |
102 | // If returning "1", this means that the Slice returned by key() is valid | |
103 | // as long as the iterator is not deleted. | |
104 | // It is guaranteed to always return "1" if | |
105 | // - Iterator created with ReadOptions::pin_data = true | |
106 | // - DB tables were created with | |
107 | // BlockBasedTableOptions::use_delta_encoding = false. | |
108 | // Property "rocksdb.iterator.super-version-number": | |
109 | // LSM version used by the iterator. The same format as DB Property | |
110 | // kCurrentSuperVersionNumber. See its comment for more information. | |
11fdf7f2 TL |
111 | // Property "rocksdb.iterator.internal-key": |
112 | // Get the user-key portion of the internal key at which the iteration | |
113 | // stopped. | |
7c673cae | 114 | virtual Status GetProperty(std::string prop_name, std::string* prop); |
20effc67 TL |
115 | |
116 | virtual Slice timestamp() const { | |
117 | assert(false); | |
118 | return Slice(); | |
119 | } | |
7c673cae FG |
120 | }; |
121 | ||
122 | // Return an empty iterator (yields nothing). | |
123 | extern Iterator* NewEmptyIterator(); | |
124 | ||
125 | // Return an empty iterator with the specified status. | |
126 | extern Iterator* NewErrorIterator(const Status& status); | |
127 | ||
f67539c2 | 128 | } // namespace ROCKSDB_NAMESPACE |