1179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org// Copyright (c) 2011 The LevelDB Authors. All rights reserved. 2179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org// Use of this source code is governed by a BSD-style license that can be 3179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org// found in the LICENSE file. See the AUTHORS file for names of contributors. 4179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org// 5179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org// An iterator yields a sequence of key/value pairs from a source. 6179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org// The following class defines the interface. Multiple implementations 7179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org// are provided by this library. In particular, iterators are provided 8179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org// to access the contents of a Table or a DB. 9a5b4129c0a8c01158cde2244a5811f15b9d45ec0dgrogan@chromium.org// 10a5b4129c0a8c01158cde2244a5811f15b9d45ec0dgrogan@chromium.org// Multiple threads can invoke const methods on an Iterator without 11a5b4129c0a8c01158cde2244a5811f15b9d45ec0dgrogan@chromium.org// external synchronization, but if any of the threads may call a 12a5b4129c0a8c01158cde2244a5811f15b9d45ec0dgrogan@chromium.org// non-const method, all threads accessing the same Iterator must use 13a5b4129c0a8c01158cde2244a5811f15b9d45ec0dgrogan@chromium.org// external synchronization. 14179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 15179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org#ifndef STORAGE_LEVELDB_INCLUDE_ITERATOR_H_ 16179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org#define STORAGE_LEVELDB_INCLUDE_ITERATOR_H_ 17179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 181ca60b12c68a71aac695b15e329b2a76a63cbb0ajorlow@chromium.org#include "leveldb/slice.h" 191ca60b12c68a71aac695b15e329b2a76a63cbb0ajorlow@chromium.org#include "leveldb/status.h" 20179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 21179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.orgnamespace leveldb { 22179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 23179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.orgclass Iterator { 24179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org public: 25179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org Iterator(); 26179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org virtual ~Iterator(); 27179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 28179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // An iterator is either positioned at a key/value pair, or 29179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // not valid. This method returns true iff the iterator is valid. 30179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org virtual bool Valid() const = 0; 31179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 32179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // Position at the first key in the source. The iterator is Valid() 33179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // after this call iff the source is not empty. 34179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org virtual void SeekToFirst() = 0; 35179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 36179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // Position at the last key in the source. The iterator is 37179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // Valid() after this call iff the source is not empty. 38179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org virtual void SeekToLast() = 0; 39179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 40179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // Position at the first key in the source that at or past target 41179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // The iterator is Valid() after this call iff the source contains 42179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // an entry that comes at or past target. 43179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org virtual void Seek(const Slice& target) = 0; 44179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 45179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // Moves to the next entry in the source. After this call, Valid() is 46179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // true iff the iterator was not positioned at the last entry in the source. 47179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // REQUIRES: Valid() 48179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org virtual void Next() = 0; 49179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 50179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // Moves to the previous entry in the source. After this call, Valid() is 51179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // true iff the iterator was not positioned at the first entry in source. 52179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // REQUIRES: Valid() 53179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org virtual void Prev() = 0; 54179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 55179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // Return the key for the current entry. The underlying storage for 56179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // the returned slice is valid only until the next modification of 57179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // the iterator. 58179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // REQUIRES: Valid() 59179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org virtual Slice key() const = 0; 60179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 61179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // Return the value for the current entry. The underlying storage for 62179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // the returned slice is valid only until the next modification of 63179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // the iterator. 64179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // REQUIRES: !AtEnd() && !AtStart() 65179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org virtual Slice value() const = 0; 66179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 67179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // If an error has occurred, return it. Else return an ok status. 68179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org virtual Status status() const = 0; 69179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 70179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // Clients are allowed to register function/arg1/arg2 triples that 71179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // will be invoked when this iterator is destroyed. 72179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // 73179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // Note that unlike all of the preceding methods, this method is 74179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // not abstract and therefore clients should not override it. 75179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org typedef void (*CleanupFunction)(void* arg1, void* arg2); 76179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org void RegisterCleanup(CleanupFunction function, void* arg1, void* arg2); 77179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 78179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org private: 79179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org struct Cleanup { 80179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org CleanupFunction function; 81179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org void* arg1; 82179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org void* arg2; 83179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org Cleanup* next; 84179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org }; 85179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org Cleanup cleanup_; 86179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 87179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org // No copying allowed 88179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org Iterator(const Iterator&); 89179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org void operator=(const Iterator&); 90179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org}; 91179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 92179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org// Return an empty iterator (yields nothing). 93179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.orgextern Iterator* NewEmptyIterator(); 94179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 95179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org// Return an empty iterator with the specified status. 96179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.orgextern Iterator* NewErrorIterator(const Status& status); 97179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 9845b9940be332834440bd5299419f396e38085ebehans@chromium.org} // namespace leveldb 99179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org 100179be588c25dccaa963df9c9c104fc6229435483jorlow@chromium.org#endif // STORAGE_LEVELDB_INCLUDE_ITERATOR_H_ 101