1 // Copyright (c) 2012, Suryandaru Triandana <syndtr@gmail.com> 2 // All rights reserved. 3 // 4 // Use of this source code is governed by a BSD-style license that can be 5 // found in the LICENSE file. 6 7 // Package iterator provides interface and implementation to traverse over 8 // contents of a database. 9 package iterator 10 11 import ( 12 "errors" 13 14 "github.com/syndtr/goleveldb/leveldb/util" 15 ) 16 17 var ( 18 ErrIterReleased = errors.New("leveldb/iterator: iterator released") 19 ) 20 21 // IteratorSeeker is the interface that wraps the 'seeks method'. 22 type IteratorSeeker interface { 23 // First moves the iterator to the first key/value pair. If the iterator 24 // only contains one key/value pair then First and Last would moves 25 // to the same key/value pair. 26 // It returns whether such pair exist. 27 First() bool 28 29 // Last moves the iterator to the last key/value pair. If the iterator 30 // only contains one key/value pair then First and Last would moves 31 // to the same key/value pair. 32 // It returns whether such pair exist. 33 Last() bool 34 35 // Seek moves the iterator to the first key/value pair whose key is greater 36 // than or equal to the given key. 37 // It returns whether such pair exist. 38 // 39 // It is safe to modify the contents of the argument after Seek returns. 40 Seek(key []byte) bool 41 42 // Next moves the iterator to the next key/value pair. 43 // It returns false if the iterator is exhausted. 44 Next() bool 45 46 // Prev moves the iterator to the previous key/value pair. 47 // It returns false if the iterator is exhausted. 48 Prev() bool 49 } 50 51 // CommonIterator is the interface that wraps common iterator methods. 52 type CommonIterator interface { 53 IteratorSeeker 54 55 // util.Releaser is the interface that wraps basic Release method. 56 // When called Release will releases any resources associated with the 57 // iterator. 58 util.Releaser 59 60 // util.ReleaseSetter is the interface that wraps the basic SetReleaser 61 // method. 62 util.ReleaseSetter 63 64 // TODO: Remove this when ready. 65 Valid() bool 66 67 // Error returns any accumulated error. Exhausting all the key/value pairs 68 // is not considered to be an error. 69 Error() error 70 } 71 72 // Iterator iterates over a DB's key/value pairs in key order. 73 // 74 // When encounter an error any 'seeks method' will return false and will 75 // yield no key/value pairs. The error can be queried by calling the Error 76 // method. Calling Release is still necessary. 77 // 78 // An iterator must be released after use, but it is not necessary to read 79 // an iterator until exhaustion. 80 // Also, an iterator is not necessarily safe for concurrent use, but it is 81 // safe to use multiple iterators concurrently, with each in a dedicated 82 // goroutine. 83 type Iterator interface { 84 CommonIterator 85 86 // Key returns the key of the current key/value pair, or nil if done. 87 // The caller should not modify the contents of the returned slice, and 88 // its contents may change on the next call to any 'seeks method'. 89 Key() []byte 90 91 // Value returns the value of the current key/value pair, or nil if done. 92 // The caller should not modify the contents of the returned slice, and 93 // its contents may change on the next call to any 'seeks method'. 94 Value() []byte 95 } 96 97 // ErrorCallbackSetter is the interface that wraps basic SetErrorCallback 98 // method. 99 // 100 // ErrorCallbackSetter implemented by indexed and merged iterator. 101 type ErrorCallbackSetter interface { 102 // SetErrorCallback allows set an error callback of the corresponding 103 // iterator. Use nil to clear the callback. 104 SetErrorCallback(f func(err error)) 105 } 106 107 type emptyIterator struct { 108 util.BasicReleaser 109 err error 110 } 111 112 func (i *emptyIterator) rErr() { 113 if i.err == nil && i.Released() { 114 i.err = ErrIterReleased 115 } 116 } 117 118 func (*emptyIterator) Valid() bool { return false } 119 func (i *emptyIterator) First() bool { i.rErr(); return false } 120 func (i *emptyIterator) Last() bool { i.rErr(); return false } 121 func (i *emptyIterator) Seek(key []byte) bool { i.rErr(); return false } 122 func (i *emptyIterator) Next() bool { i.rErr(); return false } 123 func (i *emptyIterator) Prev() bool { i.rErr(); return false } 124 func (*emptyIterator) Key() []byte { return nil } 125 func (*emptyIterator) Value() []byte { return nil } 126 func (i *emptyIterator) Error() error { return i.err } 127 128 // NewEmptyIterator creates an empty iterator. The err parameter can be 129 // nil, but if not nil the given err will be returned by Error method. 130 func NewEmptyIterator(err error) Iterator { 131 return &emptyIterator{err: err} 132 } 133