text: // Copyright (c) 2011 The LevelDB Authors. All rights reserved.
  // Use of this source code is governed by a BSD-style license that can be
  // found in the LICENSE file. See the AUTHORS file for names of contributors.
  //
  // An iterator yields a sequence of key/value pairs from a source.
  // The following class defines the interface.  Multiple implementations
  // are provided by this library.  In particular, iterators are provided
  // to access the contents of a Table or a DB.
  //
  // Multiple threads can invoke const methods on an Iterator without
  // external synchronization, but if any of the threads may call a
  // non-const method, all threads accessing the same Iterator must use
  // external synchronization.
  
  #ifndef STORAGE_LEVELDB_INCLUDE_ITERATOR_H_
  #define STORAGE_LEVELDB_INCLUDE_ITERATOR_H_
  
  #include "leveldb/export.h"
  #include "leveldb/slice.h"
  #include "leveldb/status.h"
  
  namespace leveldb {
  
  class LEVELDB_EXPORT Iterator {
   public:
    Iterator();
  
    Iterator(const Iterator&) = delete;
    Iterator& operator=(const Iterator&) = delete;
  
    virtual ~Iterator();
  
    // An iterator is either positioned at a key/value pair, or
    // not valid.  This method returns true iff the iterator is valid.
    virtual bool Valid() const = 0;
  
    // Position at the first key in the source.  The iterator is Valid()
    // after this call iff the source is not empty.
    virtual void SeekToFirst() = 0;
  
    // Position at the last key in the source.  The iterator is
    // Valid() after this call iff the source is not empty.
    virtual void SeekToLast() = 0;
  
    // Position at the first key in the source that is at or past target.
    // The iterator is Valid() after this call iff the source contains
    // an entry that comes at or past target.
    virtual void Seek(const Slice& target) = 0;
  
    // Moves to the next entry in the source.  After this call, Valid() is
    // true iff the iterator was not positioned at the last entry in the source.
    // REQUIRES: Valid()
    virtual void Next() = 0;
  
    // Moves to the previous entry in the source.  After this call, Valid() is
    // true iff the iterator was not positioned at the first entry in source.
    // REQUIRES: Valid()
    virtual void Prev() = 0;
  
    // Return the key for the current entry.  The underlying storage for
    // the returned slice is valid only until the next modification of
    // the iterator.
    // REQUIRES: Valid()
    virtual Slice key() const = 0;
  
    // Return the value for the current entry.  The underlying storage for
    // the returned slice is valid only until the next modification of
    // the iterator.
    // REQUIRES: Valid()
    virtual Slice value() const = 0;
  
    // If an error has occurred, return it.  Else return an ok status.
    virtual Status status() const = 0;
  
    // Clients are allowed to register function/arg1/arg2 triples that
    // will be invoked when this iterator is destroyed.
    //
    // Note that unlike all of the preceding methods, this method is
    // not abstract and therefore clients should not override it.
    using CleanupFunction = void (*)(void* arg1, void* arg2);
    void RegisterCleanup(CleanupFunction function, void* arg1, void* arg2);
  
   private:
    // Cleanup functions are stored in a single-linked list.
    // The list's head node is inlined in the iterator.
    struct CleanupNode 
    {
      // True if the node is not used. Only head nodes might be unused.
      bool IsEmpty() const { return function == nullptr; }
      // Invokes the cleanup function.
      void Run() 
      {
        assert(function != nullptr);
        (*function)(arg1, arg2);
      }
  
      // The head node is used if the function pointer is not null.
      CleanupFunction function;
      void* arg1;
      void* arg2;
      CleanupNode* next;
    };
    CleanupNode cleanup_head_;
  };
  
  // Return an empty iterator (yields nothing).
  LEVELDB_EXPORT Iterator* NewEmptyIterator();
  
  // Return an empty iterator with the specified status.
  LEVELDB_EXPORT Iterator* NewErrorIterator(const Status& status);
  
  }  // namespace leveldb
  
  #endif  // STORAGE_LEVELDB_INCLUDE_ITERATOR_H_
  