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