1 | // Copyright (c) 2011 The LevelDB Authors. All rights reserved. |
2 | // Use of this source code is governed by a BSD-style license that can be |
3 | // found in the LICENSE file. See the AUTHORS file for names of contributors. |
4 | // |
5 | // An iterator yields a sequence of key/value pairs from a source. |
6 | // The following class defines the interface. Multiple implementations |
7 | // are provided by this library. In particular, iterators are provided |
8 | // to access the contents of a Table or a DB. |
9 | // |
10 | // Multiple threads can invoke const methods on an Iterator without |
11 | // external synchronization, but if any of the threads may call a |
12 | // non-const method, all threads accessing the same Iterator must use |
13 | // external synchronization. |
14 | |
15 | #ifndef STORAGE_LEVELDB_INCLUDE_ITERATOR_H_ |
16 | #define STORAGE_LEVELDB_INCLUDE_ITERATOR_H_ |
17 | |
18 | #include "leveldb/export.h" |
19 | #include "leveldb/slice.h" |
20 | #include "leveldb/status.h" |
21 | |
22 | namespace leveldb { |
23 | |
24 | class LEVELDB_EXPORT Iterator { |
25 | public: |
26 | Iterator(); |
27 | |
28 | Iterator(const Iterator&) = delete; |
29 | Iterator& operator=(const Iterator&) = delete; |
30 | |
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. |
35 | virtual bool Valid() const = 0; |
36 | |
37 | // Position at the first key in the source. The iterator is Valid() |
38 | // after this call iff the source is not empty. |
39 | virtual void SeekToFirst() = 0; |
40 | |
41 | // Position at the last key in the source. The iterator is |
42 | // Valid() after this call iff the source is not empty. |
43 | virtual void SeekToLast() = 0; |
44 | |
45 | // Position at the first key in the source that is at or past target. |
46 | // The iterator is Valid() after this call iff the source contains |
47 | // an entry that comes at or past target. |
48 | virtual void Seek(const Slice& target) = 0; |
49 | |
50 | // Moves to the next entry in the source. After this call, Valid() is |
51 | // true iff the iterator was not positioned at the last entry in the source. |
52 | // REQUIRES: Valid() |
53 | virtual void Next() = 0; |
54 | |
55 | // Moves to the previous entry in the source. After this call, Valid() is |
56 | // true iff the iterator was not positioned at the first entry in source. |
57 | // REQUIRES: Valid() |
58 | virtual void Prev() = 0; |
59 | |
60 | // Return the key for the current entry. The underlying storage for |
61 | // the returned slice is valid only until the next modification of |
62 | // the iterator. |
63 | // REQUIRES: Valid() |
64 | virtual Slice key() const = 0; |
65 | |
66 | // Return the value for the current entry. The underlying storage for |
67 | // the returned slice is valid only until the next modification of |
68 | // the iterator. |
69 | // REQUIRES: Valid() |
70 | virtual Slice value() const = 0; |
71 | |
72 | // If an error has occurred, return it. Else return an ok status. |
73 | virtual Status status() const = 0; |
74 | |
75 | // Clients are allowed to register function/arg1/arg2 triples that |
76 | // will be invoked when this iterator is destroyed. |
77 | // |
78 | // Note that unlike all of the preceding methods, this method is |
79 | // not abstract and therefore clients should not override it. |
80 | using CleanupFunction = void (*)(void* arg1, void* arg2); |
81 | void RegisterCleanup(CleanupFunction function, void* arg1, void* arg2); |
82 | |
83 | private: |
84 | // Cleanup functions are stored in a single-linked list. |
85 | // The list's head node is inlined in the iterator. |
86 | struct CleanupNode { |
87 | // True if the node is not used. Only head nodes might be unused. |
88 | bool IsEmpty() const { return function == nullptr; } |
89 | // Invokes the cleanup function. |
90 | void Run() { |
91 | assert(function != nullptr); |
92 | (*function)(arg1, arg2); |
93 | } |
94 | |
95 | // The head node is used if the function pointer is not null. |
96 | CleanupFunction function; |
97 | void* arg1; |
98 | void* arg2; |
99 | CleanupNode* next; |
100 | }; |
101 | CleanupNode cleanup_head_; |
102 | }; |
103 | |
104 | // Return an empty iterator (yields nothing). |
105 | LEVELDB_EXPORT Iterator* NewEmptyIterator(); |
106 | |
107 | // Return an empty iterator with the specified status. |
108 | LEVELDB_EXPORT Iterator* NewErrorIterator(const Status& status); |
109 | |
110 | } // namespace leveldb |
111 | |
112 | #endif // STORAGE_LEVELDB_INCLUDE_ITERATOR_H_ |
113 | |