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_