ceph/src/rocksdb/include/rocksdb/iterator.h

   1 // Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
   2 //  This source code is licensed under both the GPLv2 (found in the
   3 //  COPYING file in the root directory) and Apache 2.0 License
   4 //  (found in the LICENSE.Apache file in the root directory).
   5 // Copyright (c) 2011 The LevelDB Authors. All rights reserved.
   6 // Use of this source code is governed by a BSD-style license that can be
   7 // found in the LICENSE file. See the AUTHORS file for names of contributors.
   8 //
   9 // An iterator yields a sequence of key/value pairs from a source.
  10 // The following class defines the interface.  Multiple implementations
  11 // are provided by this library.  In particular, iterators are provided
  12 // to access the contents of a Table or a DB.
  13 //
  14 // Multiple threads can invoke const methods on an Iterator without
  15 // external synchronization, but if any of the threads may call a
  16 // non-const method, all threads accessing the same Iterator must use
  17 // external synchronization.
  18
  19 #pragma once
  20
  21 #include <string>
  22
  23 #include "rocksdb/cleanable.h"
  24 #include "rocksdb/slice.h"
  25 #include "rocksdb/status.h"
  26 #include "rocksdb/wide_columns.h"
  27
  28 namespace ROCKSDB_NAMESPACE {
  29
  30 class Iterator : public Cleanable {
  31  public:
  32   Iterator() {}
  33   // No copying allowed
  34   Iterator(const Iterator&) = delete;
  35   void operator=(const Iterator&) = delete;
  36
  37   virtual ~Iterator() {}
  38
  39   // An iterator is either positioned at a key/value pair, or
  40   // not valid.  This method returns true iff the iterator is valid.
  41   // Always returns false if !status().ok().
  42   virtual bool Valid() const = 0;
  43
  44   // Position at the first key in the source.  The iterator is Valid()
  45   // after this call iff the source is not empty.
  46   virtual void SeekToFirst() = 0;
  47
  48   // Position at the last key in the source.  The iterator is
  49   // Valid() after this call iff the source is not empty.
  50   virtual void SeekToLast() = 0;
  51
  52   // Position at the first key in the source that at or past target.
  53   // The iterator is Valid() after this call iff the source contains
  54   // an entry that comes at or past target.
  55   // All Seek*() methods clear any error status() that the iterator had prior to
  56   // the call; after the seek, status() indicates only the error (if any) that
  57   // happened during the seek, not any past errors.
  58   // Target does not contain timestamp.
  59   virtual void Seek(const Slice& target) = 0;
  60
  61   // Position at the last key in the source that at or before target.
  62   // The iterator is Valid() after this call iff the source contains
  63   // an entry that comes at or before target.
  64   // Target does not contain timestamp.
  65   virtual void SeekForPrev(const Slice& target) = 0;
  66
  67   // Moves to the next entry in the source.  After this call, Valid() is
  68   // true iff the iterator was not positioned at the last entry in the source.
  69   // REQUIRES: Valid()
  70   virtual void Next() = 0;
  71
  72   // Moves to the previous entry in the source.  After this call, Valid() is
  73   // true iff the iterator was not positioned at the first entry in source.
  74   // REQUIRES: Valid()
  75   virtual void Prev() = 0;
  76
  77   // Return the key for the current entry.  The underlying storage for
  78   // the returned slice is valid only until the next modification of the
  79   // iterator (i.e. the next SeekToFirst/SeekToLast/Seek/SeekForPrev/Next/Prev
  80   // operation).
  81   // REQUIRES: Valid()
  82   virtual Slice key() const = 0;
  83
  84   // Return the value for the current entry.  If the entry is a plain key-value,
  85   // return the value as-is; if it is a wide-column entity, return the value of
  86   // the default anonymous column (see kDefaultWideColumnName) if any, or an
  87   // empty value otherwise.  The underlying storage for the returned slice is
  88   // valid only until the next modification of the iterator (i.e. the next
  89   // SeekToFirst/SeekToLast/Seek/SeekForPrev/Next/Prev operation).
  90   // REQUIRES: Valid()
  91   virtual Slice value() const = 0;
  92
  93   // Return the wide columns for the current entry.  If the entry is a
  94   // wide-column entity, return it as-is; if it is a plain key-value, return it
  95   // as an entity with a single anonymous column (see kDefaultWideColumnName)
  96   // which contains the value.  The underlying storage for the returned
  97   // structure is valid only until the next modification of the iterator (i.e.
  98   // the next SeekToFirst/SeekToLast/Seek/SeekForPrev/Next/Prev operation).
  99   // REQUIRES: Valid()
 100   virtual const WideColumns& columns() const {
 101     assert(false);
 102     return kNoWideColumns;
 103   }
 104
 105   // If an error has occurred, return it.  Else return an ok status.
 106   // If non-blocking IO is requested and this operation cannot be
 107   // satisfied without doing some IO, then this returns Status::Incomplete().
 108   virtual Status status() const = 0;
 109
 110   // If supported, renew the iterator to represent the latest state. The
 111   // iterator will be invalidated after the call. Not supported if
 112   // ReadOptions.snapshot is given when creating the iterator.
 113   virtual Status Refresh() {
 114     return Status::NotSupported("Refresh() is not supported");
 115   }
 116
 117   // Property "rocksdb.iterator.is-key-pinned":
 118   //   If returning "1", this means that the Slice returned by key() is valid
 119   //   as long as the iterator is not deleted.
 120   //   It is guaranteed to always return "1" if
 121   //      - Iterator created with ReadOptions::pin_data = true
 122   //      - DB tables were created with
 123   //        BlockBasedTableOptions::use_delta_encoding = false.
 124   // Property "rocksdb.iterator.super-version-number":
 125   //   LSM version used by the iterator. The same format as DB Property
 126   //   kCurrentSuperVersionNumber. See its comment for more information.
 127   // Property "rocksdb.iterator.internal-key":
 128   //   Get the user-key portion of the internal key at which the iteration
 129   //   stopped.
 130   virtual Status GetProperty(std::string prop_name, std::string* prop);
 131
 132   virtual Slice timestamp() const {
 133     assert(false);
 134     return Slice();
 135   }
 136 };
 137
 138 // Return an empty iterator (yields nothing).
 139 extern Iterator* NewEmptyIterator();
 140
 141 // Return an empty iterator with the specified status.
 142 extern Iterator* NewErrorIterator(const Status& status);
 143
 144 }  // namespace ROCKSDB_NAMESPACE