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