github.com/cockroachdb/cockroach@v20.2.0-alpha.1+incompatible/pkg/kv/kvserver/diskmap/disk_map.go (about)

     1  // Copyright 2018 The Cockroach Authors.
     2  //
     3  // Use of this software is governed by the Business Source License
     4  // included in the file licenses/BSL.txt.
     5  //
     6  // As of the Change Date specified in that file, in accordance with
     7  // the Business Source License, use of this software will be governed
     8  // by the Apache License, Version 2.0, included in the file
     9  // licenses/APL.txt.
    10  
    11  package diskmap
    12  
    13  import "context"
    14  
    15  // Factory is an interface that can produce SortedDiskMaps.
    16  type Factory interface {
    17  	// Close the factory, freeing up associated resources.
    18  	Close()
    19  	// NewSortedDiskMap returns a fresh SortedDiskMap with no contents.
    20  	NewSortedDiskMap() SortedDiskMap
    21  	// NewSortedDiskMultiMap returns a fresh SortedDiskMap with no contents that permits
    22  	// duplicate keys.
    23  	NewSortedDiskMultiMap() SortedDiskMap
    24  }
    25  
    26  // SortedDiskMapIterator is a simple iterator used to iterate over keys and/or
    27  // values.
    28  // Example use of iterating over all keys:
    29  // 	var i SortedDiskMapIterator
    30  // 	for i.Rewind(); ; i.Next() {
    31  // 		if ok, err := i.Valid(); err != nil {
    32  //			// Handle error.
    33  // 		} else if !ok {
    34  //			break
    35  // 		}
    36  // 		key := i.UnsafeKey()
    37  //		// Do something.
    38  // 	}
    39  type SortedDiskMapIterator interface {
    40  	// SeekGE sets the iterator's position to the first key greater than or equal
    41  	// to the provided key.
    42  	SeekGE(key []byte)
    43  	// Rewind seeks to the start key.
    44  	Rewind()
    45  	// Valid must be called after any call to Seek(), Rewind(), or Next(). It
    46  	// returns (true, nil) if the iterator points to a valid key and
    47  	// (false, nil) if the iterator has moved past the end of the valid range.
    48  	// If an error has occurred, the returned bool is invalid.
    49  	Valid() (bool, error)
    50  	// Next advances the iterator to the next key in the iteration.
    51  	Next()
    52  
    53  	// UnsafeKey returns the same value as Key, but the memory is invalidated on
    54  	// the next call to {Next,Rewind,Seek,Close}.
    55  	UnsafeKey() []byte
    56  	// UnsafeValue returns the same value as Value, but the memory is
    57  	// invalidated on the next call to {Next,Rewind,Seek,Close}.
    58  	UnsafeValue() []byte
    59  
    60  	// Close frees up resources held by the iterator.
    61  	Close()
    62  }
    63  
    64  // SortedDiskMapBatchWriter batches writes to a SortedDiskMap.
    65  type SortedDiskMapBatchWriter interface {
    66  	// Put writes the given key/value pair to the batch. The write to the
    67  	// underlying store happens on Flush(), Close(), or when the batch writer
    68  	// reaches its capacity.
    69  	Put(k []byte, v []byte) error
    70  	// Flush flushes all writes to the underlying store. The batch can be reused
    71  	// after a call to Flush().
    72  	Flush() error
    73  	// The number of put calls since the last time the writer was flushed.
    74  	NumPutsSinceFlush() int
    75  	// Close flushes all writes to the underlying store and frees up resources
    76  	// held by the batch writer.
    77  	Close(context.Context) error
    78  }
    79  
    80  // SortedDiskMap is an on-disk map. Keys are iterated over in sorted order.
    81  type SortedDiskMap interface {
    82  	// NewIterator returns a SortedDiskMapIterator that can be used to iterate
    83  	// over key/value pairs in sorted order.
    84  	NewIterator() SortedDiskMapIterator
    85  	// NewBatchWriter returns a SortedDiskMapBatchWriter that can be used to
    86  	// batch writes to this map for performance improvements.
    87  	NewBatchWriter() SortedDiskMapBatchWriter
    88  	// NewBatchWriterCapacity is identical to NewBatchWriter, but overrides the
    89  	// SortedDiskMapBatchWriter's default capacity with capacityBytes.
    90  	NewBatchWriterCapacity(capacityBytes int) SortedDiskMapBatchWriter
    91  
    92  	// Clear clears the map's data for reuse.
    93  	Clear() error
    94  
    95  	// Close frees up resources held by the map.
    96  	Close(context.Context)
    97  }