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