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/export.h"
19#include "leveldb/slice.h"
20#include "leveldb/status.h"
21
22namespace leveldb {
23
24class LEVELDB_EXPORT Iterator {
25 public:
26 Iterator();
27
28 Iterator(const Iterator&) = delete;
29 Iterator& operator=(const Iterator&) = delete;
30
31 virtual ~Iterator();
32
33 // An iterator is either positioned at a key/value pair, or
34 // not valid. This method returns true iff the iterator is valid.
35 virtual bool Valid() const = 0;
36
37 // Position at the first key in the source. The iterator is Valid()
38 // after this call iff the source is not empty.
39 virtual void SeekToFirst() = 0;
40
41 // Position at the last key in the source. The iterator is
42 // Valid() after this call iff the source is not empty.
43 virtual void SeekToLast() = 0;
44
45 // Position at the first key in the source that is at or past target.
46 // The iterator is Valid() after this call iff the source contains
47 // an entry that comes at or past target.
48 virtual void Seek(const Slice& target) = 0;
49
50 // Moves to the next entry in the source. After this call, Valid() is
51 // true iff the iterator was not positioned at the last entry in the source.
52 // REQUIRES: Valid()
53 virtual void Next() = 0;
54
55 // Moves to the previous entry in the source. After this call, Valid() is
56 // true iff the iterator was not positioned at the first entry in source.
57 // REQUIRES: Valid()
58 virtual void Prev() = 0;
59
60 // Return the key for the current entry. The underlying storage for
61 // the returned slice is valid only until the next modification of
62 // the iterator.
63 // REQUIRES: Valid()
64 virtual Slice key() const = 0;
65
66 // Return the value for the current entry. The underlying storage for
67 // the returned slice is valid only until the next modification of
68 // the iterator.
69 // REQUIRES: Valid()
70 virtual Slice value() const = 0;
71
72 // If an error has occurred, return it. Else return an ok status.
73 virtual Status status() const = 0;
74
75 // Clients are allowed to register function/arg1/arg2 triples that
76 // will be invoked when this iterator is destroyed.
77 //
78 // Note that unlike all of the preceding methods, this method is
79 // not abstract and therefore clients should not override it.
80 using CleanupFunction = void (*)(void* arg1, void* arg2);
81 void RegisterCleanup(CleanupFunction function, void* arg1, void* arg2);
82
83 private:
84 // Cleanup functions are stored in a single-linked list.
85 // The list's head node is inlined in the iterator.
86 struct CleanupNode {
87 // True if the node is not used. Only head nodes might be unused.
88 bool IsEmpty() const { return function == nullptr; }
89 // Invokes the cleanup function.
90 void Run() {
91 assert(function != nullptr);
92 (*function)(arg1, arg2);
93 }
94
95 // The head node is used if the function pointer is not null.
96 CleanupFunction function;
97 void* arg1;
98 void* arg2;
99 CleanupNode* next;
100 };
101 CleanupNode cleanup_head_;
102};
103
104// Return an empty iterator (yields nothing).
105LEVELDB_EXPORT Iterator* NewEmptyIterator();
106
107// Return an empty iterator with the specified status.
108LEVELDB_EXPORT Iterator* NewErrorIterator(const Status& status);
109
110} // namespace leveldb
111
112#endif // STORAGE_LEVELDB_INCLUDE_ITERATOR_H_
113