xref: /aosp_15_r20/external/leveldb/include/leveldb/iterator.h (revision 9507f98c5f32dee4b5f9e4a38cd499f3ff5c4490)
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.
IsEmptyCleanupNode88     bool IsEmpty() const { return function == nullptr; }
89     // Invokes the cleanup function.
RunCleanupNode90     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