github.com/cockroachdb/pebble@v0.0.0-20231214172447-ab4952c5f87b/internal/keyspan/iter.go (about) 1 // Copyright 2018 The LevelDB-Go and Pebble Authors. All rights reserved. Use 2 // of this source code is governed by a BSD-style license that can be found in 3 // the LICENSE file. 4 5 package keyspan 6 7 import ( 8 "github.com/cockroachdb/pebble/internal/base" 9 "github.com/cockroachdb/pebble/internal/manifest" 10 ) 11 12 // FragmentIterator defines an iterator interface over spans. The spans 13 // surfaced by a FragmentIterator must be non-overlapping. This is achieved by 14 // fragmenting spans at overlap points (see Fragmenter). 15 // 16 // A Span returned by a FragmentIterator is only valid until the next 17 // positioning method. Some implementations (eg, keyspan.Iter) may provide 18 // longer lifetimes but implementations need only guarantee stability until the 19 // next positioning method. 20 type FragmentIterator interface { 21 // SeekGE moves the iterator to the first span covering a key greater than 22 // or equal to the given key. This is equivalent to seeking to the first 23 // span with an end key greater than the given key. 24 SeekGE(key []byte) *Span 25 26 // SeekLT moves the iterator to the last span covering a key less than the 27 // given key. This is equivalent to seeking to the last span with a start 28 // key less than the given key. 29 SeekLT(key []byte) *Span 30 31 // First moves the iterator to the first span. 32 First() *Span 33 34 // Last moves the iterator to the last span. 35 Last() *Span 36 37 // Next moves the iterator to the next span. 38 // 39 // It is valid to call Next when the iterator is positioned before the first 40 // key/value pair due to either a prior call to SeekLT or Prev which 41 // returned an invalid span. It is not allowed to call Next when the 42 // previous call to SeekGE, SeekPrefixGE or Next returned an invalid span. 43 Next() *Span 44 45 // Prev moves the iterator to the previous span. 46 // 47 // It is valid to call Prev when the iterator is positioned after the last 48 // key/value pair due to either a prior call to SeekGE or Next which 49 // returned an invalid span. It is not allowed to call Prev when the 50 // previous call to SeekLT or Prev returned an invalid span. 51 Prev() *Span 52 53 // Error returns any accumulated error. 54 // 55 // TODO(jackson): Lift errors into return values on the positioning methods. 56 Error() error 57 58 // Close closes the iterator and returns any accumulated error. Exhausting 59 // the iterator is not considered to be an error. It is valid to call Close 60 // multiple times. Other methods should not be called after the iterator has 61 // been closed. 62 Close() error 63 } 64 65 // TableNewSpanIter creates a new iterator for range key spans for the given 66 // file. 67 type TableNewSpanIter func(file *manifest.FileMetadata, iterOptions SpanIterOptions) (FragmentIterator, error) 68 69 // SpanIterOptions is a subset of IterOptions that are necessary to instantiate 70 // per-sstable span iterators. 71 type SpanIterOptions struct { 72 // RangeKeyFilters can be used to avoid scanning tables and blocks in tables 73 // when iterating over range keys. 74 RangeKeyFilters []base.BlockPropertyFilter 75 } 76 77 // Iter is an iterator over a set of fragmented spans. 78 type Iter struct { 79 cmp base.Compare 80 spans []Span 81 index int 82 } 83 84 // Iter implements the FragmentIterator interface. 85 var _ FragmentIterator = (*Iter)(nil) 86 87 // NewIter returns a new iterator over a set of fragmented spans. 88 func NewIter(cmp base.Compare, spans []Span) *Iter { 89 i := &Iter{} 90 i.Init(cmp, spans) 91 return i 92 } 93 94 // Count returns the number of spans contained by Iter. 95 func (i *Iter) Count() int { 96 return len(i.spans) 97 } 98 99 // Init initializes an Iter with the provided spans. 100 func (i *Iter) Init(cmp base.Compare, spans []Span) { 101 *i = Iter{ 102 cmp: cmp, 103 spans: spans, 104 index: -1, 105 } 106 } 107 108 // SeekGE implements FragmentIterator.SeekGE. 109 func (i *Iter) SeekGE(key []byte) *Span { 110 // NB: manually inlined sort.Search is ~5% faster. 111 // 112 // Define f(j) = false iff the span i.spans[j] is strictly before `key` 113 // (equivalently, i.spans[j].End ≤ key.) 114 // 115 // Define f(-1) == false and f(n) == true. 116 // Invariant: f(index-1) == false, f(upper) == true. 117 i.index = 0 118 upper := len(i.spans) 119 for i.index < upper { 120 h := int(uint(i.index+upper) >> 1) // avoid overflow when computing h 121 // i.index ≤ h < upper 122 if i.cmp(key, i.spans[h].End) >= 0 { 123 i.index = h + 1 // preserves f(i-1) == false 124 } else { 125 upper = h // preserves f(j) == true 126 } 127 } 128 129 // i.index == upper, f(i.index-1) == false, and f(upper) (= f(i.index)) == 130 // true => answer is i.index. 131 if i.index >= len(i.spans) { 132 return nil 133 } 134 return &i.spans[i.index] 135 } 136 137 // SeekLT implements FragmentIterator.SeekLT. 138 func (i *Iter) SeekLT(key []byte) *Span { 139 // NB: manually inlined sort.Search is ~5% faster. 140 // 141 // Define f(-1) == false and f(n) == true. 142 // Invariant: f(index-1) == false, f(upper) == true. 143 i.index = 0 144 upper := len(i.spans) 145 for i.index < upper { 146 h := int(uint(i.index+upper) >> 1) // avoid overflow when computing h 147 // i.index ≤ h < upper 148 if i.cmp(key, i.spans[h].Start) > 0 { 149 i.index = h + 1 // preserves f(i-1) == false 150 } else { 151 upper = h // preserves f(j) == true 152 } 153 } 154 // i.index == upper, f(i.index-1) == false, and f(upper) (= f(i.index)) == 155 // true => answer is i.index. 156 157 // Since keys are strictly increasing, if i.index > 0 then i.index-1 will be 158 // the largest whose key is < the key sought. 159 i.index-- 160 if i.index < 0 { 161 return nil 162 } 163 return &i.spans[i.index] 164 } 165 166 // First implements FragmentIterator.First. 167 func (i *Iter) First() *Span { 168 if len(i.spans) == 0 { 169 return nil 170 } 171 i.index = 0 172 return &i.spans[i.index] 173 } 174 175 // Last implements FragmentIterator.Last. 176 func (i *Iter) Last() *Span { 177 if len(i.spans) == 0 { 178 return nil 179 } 180 i.index = len(i.spans) - 1 181 return &i.spans[i.index] 182 } 183 184 // Next implements FragmentIterator.Next. 185 func (i *Iter) Next() *Span { 186 if i.index >= len(i.spans) { 187 return nil 188 } 189 i.index++ 190 if i.index >= len(i.spans) { 191 return nil 192 } 193 return &i.spans[i.index] 194 } 195 196 // Prev implements FragmentIterator.Prev. 197 func (i *Iter) Prev() *Span { 198 if i.index < 0 { 199 return nil 200 } 201 i.index-- 202 if i.index < 0 { 203 return nil 204 } 205 return &i.spans[i.index] 206 } 207 208 // Error implements FragmentIterator.Error. 209 func (i *Iter) Error() error { 210 return nil 211 } 212 213 // Close implements FragmentIterator.Close. 214 func (i *Iter) Close() error { 215 return nil 216 } 217 218 func (i *Iter) String() string { 219 return "fragmented-spans" 220 }