github.com/insionng/yougam@v0.0.0-20170714101924-2bc18d833463/libraries/syndtr/goleveldb/leveldb/iterator/iter.go (about) 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/insionng/yougam/libraries/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 whould 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 whould 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 whether the iterator is exhausted. 44 Next() bool 45 46 // Prev moves the iterator to the previous key/value pair. 47 // It returns whether the iterator is exhausted. 48 Prev() bool 49 } 50 51 // CommonIterator is the interface that wraps common interator 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 encouter 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 goroutine-safe, but it is safe to use 81 // multiple iterators concurrently, with each in a dedicated goroutine. 82 type Iterator interface { 83 CommonIterator 84 85 // Key returns the key of the current key/value pair, or nil if done. 86 // The caller should not modify the contents of the returned slice, and 87 // its contents may change on the next call to any 'seeks method'. 88 Key() []byte 89 90 // Value returns the key of the current key/value pair, or nil if done. 91 // The caller should not modify the contents of the returned slice, and 92 // its contents may change on the next call to any 'seeks method'. 93 Value() []byte 94 } 95 96 // ErrorCallbackSetter is the interface that wraps basic SetErrorCallback 97 // method. 98 // 99 // ErrorCallbackSetter implemented by indexed and merged iterator. 100 type ErrorCallbackSetter interface { 101 // SetErrorCallback allows set an error callback of the coresponding 102 // iterator. Use nil to clear the callback. 103 SetErrorCallback(f func(err error)) 104 } 105 106 type emptyIterator struct { 107 util.BasicReleaser 108 err error 109 } 110 111 func (i *emptyIterator) rErr() { 112 if i.err == nil && i.Released() { 113 i.err = ErrIterReleased 114 } 115 } 116 117 func (*emptyIterator) Valid() bool { return false } 118 func (i *emptyIterator) First() bool { i.rErr(); return false } 119 func (i *emptyIterator) Last() bool { i.rErr(); return false } 120 func (i *emptyIterator) Seek(key []byte) bool { i.rErr(); return false } 121 func (i *emptyIterator) Next() bool { i.rErr(); return false } 122 func (i *emptyIterator) Prev() bool { i.rErr(); return false } 123 func (*emptyIterator) Key() []byte { return nil } 124 func (*emptyIterator) Value() []byte { return nil } 125 func (i *emptyIterator) Error() error { return i.err } 126 127 // NewEmptyIterator creates an empty iterator. The err parameter can be 128 // nil, but if not nil the given err will be returned by Error method. 129 func NewEmptyIterator(err error) Iterator { 130 return &emptyIterator{err: err} 131 }