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 #include "rocksdb/cleanable.h"
23 #include "rocksdb/slice.h"
24 #include "rocksdb/status.h"
25 
26 namespace ROCKSDB_NAMESPACE {
27 
28 class Iterator : public Cleanable {
29  public:
Iterator()30   Iterator() {}
31   // No copying allowed
32   Iterator(const Iterator&) = delete;
33   void operator=(const Iterator&) = delete;
34 
~Iterator()35   virtual ~Iterator() {}
36 
37   // An iterator is either positioned at a key/value pair, or
38   // not valid.  This method returns true iff the iterator is valid.
39   // Always returns false if !status().ok().
40   virtual bool Valid() const = 0;
41 
42   // Position at the first key in the source.  The iterator is Valid()
43   // after this call iff the source is not empty.
44   virtual void SeekToFirst() = 0;
45 
46   // Position at the last key in the source.  The iterator is
47   // Valid() after this call iff the source is not empty.
48   // Currently incompatible with user timestamp.
49   virtual void SeekToLast() = 0;
50 
51   // Position at the first key in the source that at or past target.
52   // The iterator is Valid() after this call iff the source contains
53   // an entry that comes at or past target.
54   // All Seek*() methods clear any error status() that the iterator had prior to
55   // the call; after the seek, status() indicates only the error (if any) that
56   // happened during the seek, not any past errors.
57   // Target does not contain timestamp.
58   virtual void Seek(const Slice& target) = 0;
59 
60   // Position at the last key in the source that at or before target.
61   // The iterator is Valid() after this call iff the source contains
62   // an entry that comes at or before target.
63   // Currently incompatible with user timestamp.
64   virtual void SeekForPrev(const Slice& target) = 0;
65 
66   // Moves to the next entry in the source.  After this call, Valid() is
67   // true iff the iterator was not positioned at the last entry in the source.
68   // REQUIRES: Valid()
69   virtual void Next() = 0;
70 
71   // Moves to the previous entry in the source.  After this call, Valid() is
72   // true iff the iterator was not positioned at the first entry in source.
73   // Currently incompatible with user timestamp.
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
79   // the iterator.
80   // REQUIRES: Valid()
81   virtual Slice key() const = 0;
82 
83   // Return the value for the current entry.  The underlying storage for
84   // the returned slice is valid only until the next modification of
85   // the iterator.
86   // REQUIRES: Valid()
87   virtual Slice value() const = 0;
88 
89   // If an error has occurred, return it.  Else return an ok status.
90   // If non-blocking IO is requested and this operation cannot be
91   // satisfied without doing some IO, then this returns Status::Incomplete().
92   virtual Status status() const = 0;
93 
94   // If supported, renew the iterator to represent the latest state. The
95   // iterator will be invalidated after the call. Not supported if
96   // ReadOptions.snapshot is given when creating the iterator.
Refresh()97   virtual Status Refresh() {
98     return Status::NotSupported("Refresh() is not supported");
99   }
100 
101   // Property "rocksdb.iterator.is-key-pinned":
102   //   If returning "1", this means that the Slice returned by key() is valid
103   //   as long as the iterator is not deleted.
104   //   It is guaranteed to always return "1" if
105   //      - Iterator created with ReadOptions::pin_data = true
106   //      - DB tables were created with
107   //        BlockBasedTableOptions::use_delta_encoding = false.
108   // Property "rocksdb.iterator.super-version-number":
109   //   LSM version used by the iterator. The same format as DB Property
110   //   kCurrentSuperVersionNumber. See its comment for more information.
111   // Property "rocksdb.iterator.internal-key":
112   //   Get the user-key portion of the internal key at which the iteration
113   //   stopped.
114   virtual Status GetProperty(std::string prop_name, std::string* prop);
115 
timestamp()116   virtual Slice timestamp() const {
117     assert(false);
118     return Slice();
119   }
120 };
121 
122 // Return an empty iterator (yields nothing).
123 extern Iterator* NewEmptyIterator();
124 
125 // Return an empty iterator with the specified status.
126 extern Iterator* NewErrorIterator(const Status& status);
127 
128 }  // namespace ROCKSDB_NAMESPACE
129