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