src/leveldb/include/leveldb/iterator.h

   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: Valid()
  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_