1// Copyright (c) 2011 The LevelDB Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file. See the AUTHORS file for names of contributors.
4//
5// An iterator yields a sequence of key/value pairs from a source.
6// The following class defines the interface.  Multiple implementations
7// are provided by this library.  In particular, iterators are provided
8// to access the contents of a Table or a DB.
9//
10// Multiple threads can invoke const methods on an Iterator without
11// external synchronization, but if any of the threads may call a
12// non-const method, all threads accessing the same Iterator must use
13// external synchronization.
14
15#ifndef STORAGE_LEVELDB_INCLUDE_ITERATOR_H_
16#define STORAGE_LEVELDB_INCLUDE_ITERATOR_H_
17
18#include "leveldb/slice.h"
19#include "leveldb/status.h"
20
21namespace leveldb {
22
23class Iterator {
24 public:
25  Iterator();
26  virtual ~Iterator();
27
28  // An iterator is either positioned at a key/value pair, or
29  // not valid.  This method returns true iff the iterator is valid.
30  virtual bool Valid() const = 0;
31
32  // Position at the first key in the source.  The iterator is Valid()
33  // after this call iff the source is not empty.
34  virtual void SeekToFirst() = 0;
35
36  // Position at the last key in the source.  The iterator is
37  // Valid() after this call iff the source is not empty.
38  virtual void SeekToLast() = 0;
39
40  // Position at the first key in the source that at or past target
41  // The iterator is Valid() after this call iff the source contains
42  // an entry that comes at or past target.
43  virtual void Seek(const Slice& target) = 0;
44
45  // Moves to the next entry in the source.  After this call, Valid() is
46  // true iff the iterator was not positioned at the last entry in the source.
47  // REQUIRES: Valid()
48  virtual void Next() = 0;
49
50  // Moves to the previous entry in the source.  After this call, Valid() is
51  // true iff the iterator was not positioned at the first entry in source.
52  // REQUIRES: Valid()
53  virtual void Prev() = 0;
54
55  // Return the key for the current entry.  The underlying storage for
56  // the returned slice is valid only until the next modification of
57  // the iterator.
58  // REQUIRES: Valid()
59  virtual Slice key() const = 0;
60
61  // Return the value for the current entry.  The underlying storage for
62  // the returned slice is valid only until the next modification of
63  // the iterator.
64  // REQUIRES: !AtEnd() && !AtStart()
65  virtual Slice value() const = 0;
66
67  // If an error has occurred, return it.  Else return an ok status.
68  virtual Status status() const = 0;
69
70  // Clients are allowed to register function/arg1/arg2 triples that
71  // will be invoked when this iterator is destroyed.
72  //
73  // Note that unlike all of the preceding methods, this method is
74  // not abstract and therefore clients should not override it.
75  typedef void (*CleanupFunction)(void* arg1, void* arg2);
76  void RegisterCleanup(CleanupFunction function, void* arg1, void* arg2);
77
78 private:
79  struct Cleanup {
80    CleanupFunction function;
81    void* arg1;
82    void* arg2;
83    Cleanup* next;
84  };
85  Cleanup cleanup_;
86
87  // No copying allowed
88  Iterator(const Iterator&);
89  void operator=(const Iterator&);
90};
91
92// Return an empty iterator (yields nothing).
93extern Iterator* NewEmptyIterator();
94
95// Return an empty iterator with the specified status.
96extern Iterator* NewErrorIterator(const Status& status);
97
98}  // namespace leveldb
99
100#endif  // STORAGE_LEVELDB_INCLUDE_ITERATOR_H_
101