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