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/slice.h" 19 #include "leveldb/status.h" 20 21 namespace leveldb { 22 23 class Iterator { 24 public: 25 Iterator(); 26 virtual ~Iterator(); 27 28 // An iterator is either positioned at a key/value pair, or 29 // not valid. This method returns true iff the iterator is valid. 30 virtual bool Valid() const = 0; 31 32 // Position at the first key in the source. The iterator is Valid() 33 // after this call iff the source is not empty. 34 virtual void SeekToFirst() = 0; 35 36 // Position at the last key in the source. The iterator is 37 // Valid() after this call iff the source is not empty. 38 virtual void SeekToLast() = 0; 39 40 // Position at the first key in the source that at or past target 41 // The iterator is Valid() after this call iff the source contains 42 // an entry that comes at or past target. 43 virtual void Seek(const Slice& target) = 0; 44 45 // Moves to the next entry in the source. After this call, Valid() is 46 // true iff the iterator was not positioned at the last entry in the source. 47 // REQUIRES: Valid() 48 virtual void Next() = 0; 49 50 // Moves to the previous entry in the source. After this call, Valid() is 51 // true iff the iterator was not positioned at the first entry in source. 52 // REQUIRES: Valid() 53 virtual void Prev() = 0; 54 55 // Return the key for the current entry. The underlying storage for 56 // the returned slice is valid only until the next modification of 57 // the iterator. 58 // REQUIRES: Valid() 59 virtual Slice key() const = 0; 60 61 // Return the value for the current entry. The underlying storage for 62 // the returned slice is valid only until the next modification of 63 // the iterator. 64 // REQUIRES: !AtEnd() && !AtStart() 65 virtual Slice value() const = 0; 66 67 // If an error has occurred, return it. Else return an ok status. 68 virtual Status status() const = 0; 69 70 // Clients are allowed to register function/arg1/arg2 triples that 71 // will be invoked when this iterator is destroyed. 72 // 73 // Note that unlike all of the preceding methods, this method is 74 // not abstract and therefore clients should not override it. 75 typedef void (*CleanupFunction)(void* arg1, void* arg2); 76 void RegisterCleanup(CleanupFunction function, void* arg1, void* arg2); 77 78 private: 79 struct Cleanup { 80 CleanupFunction function; 81 void* arg1; 82 void* arg2; 83 Cleanup* next; 84 }; 85 Cleanup cleanup_; 86 87 // No copying allowed 88 Iterator(const Iterator&); 89 void operator=(const Iterator&); 90 }; 91 92 // Return an empty iterator (yields nothing). 93 extern Iterator* NewEmptyIterator(); 94 95 // Return an empty iterator with the specified status. 96 extern Iterator* NewErrorIterator(const Status& status); 97 98 } // namespace leveldb 99 100 #endif // STORAGE_LEVELDB_INCLUDE_ITERATOR_H_ 101
