github.com/petermattis/pebble@v0.0.0-20190905164901-ab51a2166067/iterator.go (about) 1 // Copyright 2011 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 pebble 6 7 import ( 8 "bytes" 9 "errors" 10 "fmt" 11 ) 12 13 type iterPos int8 14 15 const ( 16 iterPosCur iterPos = 0 17 iterPosNext iterPos = 1 18 iterPosPrev iterPos = -1 19 ) 20 21 // Iterator iterates over a DB's key/value pairs in key order. 22 // 23 // An iterator must be closed after use, but it is not necessary to read an 24 // iterator until exhaustion. 25 // 26 // An iterator is not goroutine-safe, but it is safe to use multiple iterators 27 // concurrently, with each in a dedicated goroutine. 28 // 29 // It is also safe to use an iterator concurrently with modifying its 30 // underlying DB, if that DB permits modification. However, the resultant 31 // key/value pairs are not guaranteed to be a consistent snapshot of that DB 32 // at a particular point in time. 33 type Iterator struct { 34 opts IterOptions 35 cmp Compare 36 equal Equal 37 merge Merge 38 split Split 39 iter internalIterator 40 readState *readState 41 err error 42 key []byte 43 keyBuf []byte 44 value []byte 45 valueBuf []byte 46 valueBuf2 []byte 47 valid bool 48 iterKey *InternalKey 49 iterValue []byte 50 pos iterPos 51 alloc *iterAlloc 52 prefix []byte 53 } 54 55 func (i *Iterator) findNextEntry() bool { 56 i.valid = false 57 i.pos = iterPosCur 58 59 for i.iterKey != nil { 60 key := *i.iterKey 61 switch key.Kind() { 62 case InternalKeyKindDelete: 63 i.nextUserKey() 64 continue 65 66 case InternalKeyKindRangeDelete: 67 // Range deletions are treated as no-ops. See the comments in levelIter 68 // for more details. 69 i.iterKey, i.iterValue = i.iter.Next() 70 continue 71 72 case InternalKeyKindSet: 73 if i.prefix != nil && !bytes.HasPrefix(key.UserKey, i.prefix) { 74 return false 75 } 76 i.keyBuf = append(i.keyBuf[:0], key.UserKey...) 77 i.key = i.keyBuf 78 i.value = i.iterValue 79 i.valid = true 80 return true 81 82 case InternalKeyKindMerge: 83 if i.prefix != nil && !bytes.HasPrefix(key.UserKey, i.prefix) { 84 return false 85 } 86 return i.mergeNext(key) 87 88 default: 89 i.err = fmt.Errorf("invalid internal key kind: %d", key.Kind()) 90 return false 91 } 92 } 93 94 return false 95 } 96 97 func (i *Iterator) nextUserKey() { 98 if i.iterKey == nil { 99 return 100 } 101 done := i.iterKey.SeqNum() == 0 102 if !i.valid { 103 i.keyBuf = append(i.keyBuf[:0], i.iterKey.UserKey...) 104 i.key = i.keyBuf 105 } 106 for { 107 i.iterKey, i.iterValue = i.iter.Next() 108 if done || i.iterKey == nil || !i.equal(i.key, i.iterKey.UserKey) { 109 break 110 } 111 done = i.iterKey.SeqNum() == 0 112 } 113 } 114 115 func (i *Iterator) findPrevEntry() bool { 116 i.valid = false 117 i.pos = iterPosCur 118 119 for i.iterKey != nil { 120 key := *i.iterKey 121 if i.valid { 122 if !i.equal(key.UserKey, i.key) { 123 // We've iterated to the previous user key. 124 i.pos = iterPosPrev 125 return true 126 } 127 } 128 129 switch key.Kind() { 130 case InternalKeyKindDelete: 131 i.value = nil 132 i.valid = false 133 i.iterKey, i.iterValue = i.iter.Prev() 134 continue 135 136 case InternalKeyKindRangeDelete: 137 // Range deletions are treated as no-ops. See the comments in levelIter 138 // for more details. 139 i.iterKey, i.iterValue = i.iter.Prev() 140 continue 141 142 case InternalKeyKindSet: 143 if i.prefix != nil && !bytes.HasPrefix(key.UserKey, i.prefix) { 144 return false 145 } 146 i.keyBuf = append(i.keyBuf[:0], key.UserKey...) 147 i.key = i.keyBuf 148 i.value = i.iterValue 149 i.valid = true 150 i.iterKey, i.iterValue = i.iter.Prev() 151 continue 152 153 case InternalKeyKindMerge: 154 if !i.valid { 155 if i.prefix != nil && !bytes.HasPrefix(key.UserKey, i.prefix) { 156 return false 157 } 158 i.keyBuf = append(i.keyBuf[:0], key.UserKey...) 159 i.key = i.keyBuf 160 i.value = i.iterValue 161 i.valid = true 162 } else { 163 // The existing value is either stored in valueBuf2 or the underlying 164 // iterators value. We append the new value to valueBuf in order to 165 // merge(valueBuf, valueBuf2). Then we swap valueBuf and valueBuf2 in 166 // order to maintain the invariant that the existing value points to 167 // valueBuf2 (in preparation for handling th next merge value). 168 i.valueBuf = append(i.valueBuf[:0], i.iterValue...) 169 i.valueBuf = i.merge(i.key, i.valueBuf, i.value, nil) 170 i.valueBuf, i.valueBuf2 = i.valueBuf2, i.valueBuf 171 i.value = i.valueBuf2 172 } 173 i.iterKey, i.iterValue = i.iter.Prev() 174 continue 175 176 default: 177 i.err = fmt.Errorf("invalid internal key kind: %d", key.Kind()) 178 return false 179 } 180 } 181 182 if i.valid { 183 i.pos = iterPosPrev 184 return true 185 } 186 187 return false 188 } 189 190 func (i *Iterator) prevUserKey() { 191 if i.iterKey == nil { 192 return 193 } 194 if !i.valid { 195 // If we're going to compare against the prev key, we need to save the 196 // current key. 197 i.keyBuf = append(i.keyBuf[:0], i.iterKey.UserKey...) 198 i.key = i.keyBuf 199 } 200 for { 201 i.iterKey, i.iterValue = i.iter.Prev() 202 if i.iterKey == nil || !i.equal(i.key, i.iterKey.UserKey) { 203 break 204 } 205 } 206 } 207 208 func (i *Iterator) mergeNext(key InternalKey) bool { 209 // Save the current key and value. 210 i.keyBuf = append(i.keyBuf[:0], key.UserKey...) 211 i.valueBuf = append(i.valueBuf[:0], i.iterValue...) 212 i.key, i.value = i.keyBuf, i.valueBuf 213 i.valid = true 214 215 // Loop looking for older values for this key and merging them. 216 for { 217 i.iterKey, i.iterValue = i.iter.Next() 218 if i.iterKey == nil { 219 i.pos = iterPosNext 220 return true 221 } 222 key = *i.iterKey 223 if !i.equal(i.key, key.UserKey) { 224 // We've advanced to the next key. 225 i.pos = iterPosNext 226 return true 227 } 228 switch key.Kind() { 229 case InternalKeyKindDelete: 230 // We've hit a deletion tombstone. Return everything up to this 231 // point. 232 return true 233 234 case InternalKeyKindRangeDelete: 235 // Range deletions are treated as no-ops. See the comments in levelIter 236 // for more details. 237 continue 238 239 case InternalKeyKindSet: 240 // We've hit a Set value. Merge with the existing value and return. 241 i.value = i.merge(i.key, i.value, i.iterValue, nil) 242 return true 243 244 case InternalKeyKindMerge: 245 // We've hit another Merge value. Merge with the existing value and 246 // continue looping. 247 i.value = i.merge(i.key, i.value, i.iterValue, nil) 248 i.valueBuf = i.value[:0] 249 continue 250 251 default: 252 i.err = fmt.Errorf("invalid internal key kind: %d", key.Kind()) 253 return false 254 } 255 } 256 } 257 258 // SeekGE moves the iterator to the first key/value pair whose key is greater 259 // than or equal to the given key. Returns true if the iterator is pointing at 260 // a valid entry and false otherwise. 261 func (i *Iterator) SeekGE(key []byte) bool { 262 if i.err != nil { 263 return false 264 } 265 266 i.prefix = nil 267 if lowerBound := i.opts.GetLowerBound(); lowerBound != nil && i.cmp(key, lowerBound) < 0 { 268 key = lowerBound 269 } 270 271 i.iterKey, i.iterValue = i.iter.SeekGE(key) 272 return i.findNextEntry() 273 } 274 275 // SeekPrefixGE moves the iterator to the first key/value pair whose key is 276 // greater than or equal to the given key and shares a common prefix with the 277 // given key. Returns true if the iterator is pointing at a valid entry and 278 // false otherwise. Note that a user-defined Split function must be supplied to 279 // the Comparer. Also note that the iterator will not observe keys not matching 280 // the prefix. 281 func (i *Iterator) SeekPrefixGE(key []byte) bool { 282 if i.err != nil { 283 return false 284 } 285 286 if i.split == nil { 287 panic("pebble: split must be provided for SeekPrefixGE") 288 } 289 290 // Make a copy of the prefix so that modifications to the key after 291 // SeekPrefixGE returns does not affect the stored prefix. 292 prefixLen := i.split(key) 293 i.prefix = make([]byte, prefixLen) 294 copy(i.prefix, key[:prefixLen]) 295 296 if lowerBound := i.opts.GetLowerBound(); lowerBound != nil && i.cmp(key, lowerBound) < 0 { 297 if !bytes.HasPrefix(lowerBound, i.prefix) { 298 i.err = errors.New("pebble: SeekPrefixGE supplied with key outside of lower bound") 299 } else { 300 key = lowerBound 301 } 302 } 303 304 i.iterKey, i.iterValue = i.iter.SeekPrefixGE(i.prefix, key) 305 return i.findNextEntry() 306 } 307 308 // SeekLT moves the iterator to the last key/value pair whose key is less than 309 // the given key. Returns true if the iterator is pointing at a valid entry and 310 // false otherwise. 311 func (i *Iterator) SeekLT(key []byte) bool { 312 if i.err != nil { 313 return false 314 } 315 316 i.prefix = nil 317 if upperBound := i.opts.GetUpperBound(); upperBound != nil && i.cmp(key, upperBound) >= 0 { 318 key = upperBound 319 } 320 321 i.iterKey, i.iterValue = i.iter.SeekLT(key) 322 return i.findPrevEntry() 323 } 324 325 // First moves the iterator the the first key/value pair. Returns true if the 326 // iterator is pointing at a valid entry and false otherwise. 327 func (i *Iterator) First() bool { 328 if i.err != nil { 329 return false 330 } 331 332 i.prefix = nil 333 if lowerBound := i.opts.GetLowerBound(); lowerBound != nil { 334 i.iterKey, i.iterValue = i.iter.SeekGE(lowerBound) 335 } else { 336 i.iterKey, i.iterValue = i.iter.First() 337 } 338 return i.findNextEntry() 339 } 340 341 // Last moves the iterator the the last key/value pair. Returns true if the 342 // iterator is pointing at a valid entry and false otherwise. 343 func (i *Iterator) Last() bool { 344 if i.err != nil { 345 return false 346 } 347 348 i.prefix = nil 349 if upperBound := i.opts.GetUpperBound(); upperBound != nil { 350 i.iterKey, i.iterValue = i.iter.SeekLT(upperBound) 351 } else { 352 i.iterKey, i.iterValue = i.iter.Last() 353 } 354 return i.findPrevEntry() 355 } 356 357 // Next moves the iterator to the next key/value pair. Returns true if the 358 // iterator is pointing at a valid entry and false otherwise. 359 func (i *Iterator) Next() bool { 360 if i.err != nil { 361 return false 362 } 363 switch i.pos { 364 case iterPosCur: 365 i.nextUserKey() 366 case iterPosPrev: 367 // The underlying iterator is pointed to the previous key (this can only 368 // happen when switching iteration directions). We set i.valid to false 369 // here to force the calls to nextUserKey to save the current key i.iter is 370 // pointing at in order to determine when the next user-key is reached. 371 i.valid = false 372 if i.iterKey == nil { 373 // We're positioned before the first key. Need to reposition to point to 374 // the first key. 375 if lowerBound := i.opts.GetLowerBound(); lowerBound != nil { 376 i.iterKey, i.iterValue = i.iter.SeekGE(lowerBound) 377 } else { 378 i.iterKey, i.iterValue = i.iter.First() 379 } 380 } else { 381 i.nextUserKey() 382 } 383 i.nextUserKey() 384 case iterPosNext: 385 } 386 return i.findNextEntry() 387 } 388 389 // Prev moves the iterator to the previous key/value pair. Returns true if the 390 // iterator is pointing at a valid entry and false otherwise. 391 func (i *Iterator) Prev() bool { 392 if i.err != nil { 393 return false 394 } 395 switch i.pos { 396 case iterPosCur: 397 i.prevUserKey() 398 case iterPosNext: 399 // The underlying iterator is pointed to the next key (this can only happen 400 // when switching iteration directions). We set i.valid to false here to 401 // force the calls to prevUserKey to save the current key i.iter is 402 // pointing at in order to determine when the next user-key is reached. 403 i.valid = false 404 if i.iterKey == nil { 405 // We're positioned after the last key. Need to reposition to point to 406 // the last key. 407 if upperBound := i.opts.GetUpperBound(); upperBound != nil { 408 i.iterKey, i.iterValue = i.iter.SeekLT(upperBound) 409 } else { 410 i.iterKey, i.iterValue = i.iter.Last() 411 } 412 } else { 413 i.prevUserKey() 414 } 415 i.prevUserKey() 416 case iterPosPrev: 417 } 418 return i.findPrevEntry() 419 } 420 421 // Key returns the key of the current key/value pair, or nil if done. The 422 // caller should not modify the contents of the returned slice, and its 423 // contents may change on the next call to Next. 424 func (i *Iterator) Key() []byte { 425 return i.key 426 } 427 428 // Value returns the value of the current key/value pair, or nil if done. The 429 // caller should not modify the contents of the returned slice, and its 430 // contents may change on the next call to Next. 431 func (i *Iterator) Value() []byte { 432 return i.value 433 } 434 435 // Valid returns true if the iterator is positioned at a valid key/value pair 436 // and false otherwise. 437 func (i *Iterator) Valid() bool { 438 return i.valid 439 } 440 441 // Error returns any accumulated error. 442 func (i *Iterator) Error() error { 443 return i.err 444 } 445 446 // Close closes the iterator and returns any accumulated error. Exhausting 447 // all the key/value pairs in a table is not considered to be an error. 448 // It is valid to call Close multiple times. Other methods should not be 449 // called after the iterator has been closed. 450 func (i *Iterator) Close() error { 451 if i.readState != nil { 452 i.readState.unref() 453 i.readState = nil 454 } 455 if err := i.iter.Close(); err != nil && i.err != nil { 456 i.err = err 457 } 458 err := i.err 459 if alloc := i.alloc; alloc != nil { 460 *i = Iterator{} 461 iterAllocPool.Put(alloc) 462 } 463 return err 464 } 465 466 // SetBounds sets the lower and upper bounds for the iterator. Note that the 467 // iterator will always be invalidated and must be repositioned with a call to 468 // SeekGE, SeekPrefixGE, SeekLT, First, or Last. 469 func (i *Iterator) SetBounds(lower, upper []byte) { 470 i.prefix = nil 471 i.iterKey = nil 472 i.iterValue = nil 473 i.pos = iterPosCur 474 i.valid = false 475 476 i.opts.LowerBound = lower 477 i.opts.UpperBound = upper 478 i.iter.SetBounds(lower, upper) 479 }