88 lines
3.7 KiB
Go
88 lines
3.7 KiB
Go
// Copyright 2023 PingCAP, Inc.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
|
|
package extsort
|
|
|
|
import "context"
|
|
|
|
// ExternalSorter is an interface for sorting key-value pairs in external storage.
|
|
// The key-value pairs are sorted by the key, duplicate keys are automatically removed.
|
|
type ExternalSorter interface {
|
|
// NewWriter creates a new writer for writing key-value pairs before sorting.
|
|
// If the sorter starts sorting or is already sorted, it will return an error.
|
|
//
|
|
// Multiple writers can be opened and used concurrently.
|
|
NewWriter(ctx context.Context) (Writer, error)
|
|
// Sort sorts the key-value pairs written by the writer.
|
|
// It should be called after all open writers are closed.
|
|
//
|
|
// Implementations should guarantee that Sort() is idempotent and atomic.
|
|
// If it returns an error, or process is killed during Sort(), the sorter should be able
|
|
// to recover from the error or crash, and the external storage should not be corrupted.
|
|
Sort(ctx context.Context) error
|
|
// IsSorted returns true if the sorter is already sorted, iterators are ready to create.
|
|
IsSorted() bool
|
|
// NewIterator creates a new iterator for iterating over the key-value pairs after sorting.
|
|
// If the sorter is not sorted yet, it will return an error.
|
|
//
|
|
// Multiple iterators can be opened and used concurrently.
|
|
NewIterator(ctx context.Context) (Iterator, error)
|
|
// Close releases all resources held by the sorter. It will not clean up the external storage,
|
|
// so the sorter can recover from a crash.
|
|
Close() error
|
|
// CloseAndCleanup closes the external sorter and cleans up all resources created by the sorter.
|
|
CloseAndCleanup() error
|
|
}
|
|
|
|
// Writer is an interface for writing key-value pairs to the external sorter.
|
|
type Writer interface {
|
|
// Put adds a key-value pair to the writer.
|
|
//
|
|
// Implementations must not modify or retain slices passed to Put().
|
|
Put(key, value []byte) error
|
|
// Flush flushes all buffered key-value pairs to the external sorter.
|
|
// the writer can be reused after calling Flush().
|
|
Flush() error
|
|
// Close flushes all buffered key-value pairs to the external sorter,
|
|
// and releases all resources held by the writer.
|
|
Close() error
|
|
}
|
|
|
|
// Iterator is an interface for iterating over the key-value pairs after sorting.
|
|
type Iterator interface {
|
|
// Seek moves the iterator to the first key-value pair whose key is greater
|
|
// than or equal to the given key.
|
|
Seek(key []byte) bool
|
|
// First moves the iterator to the first key-value pair.
|
|
First() bool
|
|
// Next moves the iterator to the next key-value pair.
|
|
//
|
|
// Implementations must guarantee the next key is greater than the current key.
|
|
Next() bool
|
|
// Last moves the iterator to the last key-value pair.
|
|
Last() bool
|
|
// Valid returns true if the iterator is positioned at a valid key-value pair.
|
|
Valid() bool
|
|
// Error returns the error, if any, that was encountered during iteration.
|
|
Error() error
|
|
// UnsafeKey returns the key of the current key-value pair, without copying.
|
|
// The memory is only valid until the next call to change the iterator.
|
|
UnsafeKey() []byte
|
|
// UnsafeValue returns the value of the current key-value pair, without copying.
|
|
// The memory is only valid until the next call to change the iterator.
|
|
UnsafeValue() []byte
|
|
// Close releases all resources held by the iterator.
|
|
Close() error
|
|
}
|