vendor/github.com/syndtr/goleveldb/leveldb/iterator/iter.go

   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 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 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 key 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 }