Documentation
¶
Overview ¶
Package journal provides an abstraction of an append-only log with optimistic concurrency control.
Index ¶
- Variables
- func IsEmpty(ctx context.Context, j Journal) (bool, error)
- func IsFresh(ctx context.Context, j Journal) (bool, error)
- func RunBenchmarks(b *testing.B, newStore func(b *testing.B) Store)
- func RunTests(t *testing.T, newStore func(t *testing.T) Store)
- type CompareFunc
- type Journal
- type Position
- type RangeFunc
- type Store
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotFound is returned by [Journal.Get] and [Journal.Range] if the // requested record does not exist, either because it has been truncated or // because the given position has not been written yet. ErrNotFound = errors.New("record not found") // ErrConflict is returned by [Journal.Append] if there is already a record at // the specified position. ErrConflict = errors.New("optimistic concurrency conflict") )
Functions ¶
func RunBenchmarks ¶ added in v0.6.0
RunBenchmarks runs benchmarks against a Store implementation.
Types ¶
type CompareFunc ¶ added in v0.3.0
CompareFunc is a function that compares a record to some datum.
If the record is less than the datum, cmp is negative. If the record is greater than the datum, cmp is positive. Otherwise, the record is considered equal to the datum.
type Journal ¶
type Journal interface {
// Bounds returns the half-open range [begin, end) describing the positions
// of the first and last journal records that are available for reading.
Bounds(ctx context.Context) (begin, end Position, err error)
// Get returns the record at the given position.
//
// It returns [ErrNotFound] if there is no record at the given position.
Get(ctx context.Context, pos Position) (rec []byte, err error)
// Range invokes fn for each record in the journal, in order, starting with
// the record at the given position.
//
// It returns [ErrNotFound] if there is no record at the given position.
Range(ctx context.Context, pos Position, fn RangeFunc) error
// Append adds a record to the journal.
//
// end must be the next "unused" position in the journal; the first position
// is always 0.
//
// If there is already a record at the given position then [ErrConflict] is
// returned, indicating an optimistic concurrency conflict.
//
// The behavior is undefined if end is greater than the next position.
Append(ctx context.Context, end Position, rec []byte) error
// Truncate removes journal records in the half-open range [0, end). That
// is, it removes the oldest records up to, but not including, the record at
// the given position.
//
// If it returns a non-nil error the truncation may have been partially
// applied. That is, some of the records may have been removed but not all.
// The implementation must guarantee that the oldest records are removed
// first, such that there is never a "gap" between positions.
//
// The behavior is undefined if end is greater than the next position.
Truncate(ctx context.Context, end Position) error
// Close closes the journal.
Close() error
}
A Journal is an append-only log of binary records.
type Position ¶
type Position uint64
Position is the index of a record within a Journal. The first record is always at position 0.
func BinarySearch ¶ added in v0.3.0
func BinarySearch( ctx context.Context, j Journal, begin, end Position, cmp CompareFunc, ) (pos Position, rec []byte, err error)
BinarySearch performs a binary search of j to find the position of the record for which cmp() returns zero.
func FirstRecord ¶ added in v0.4.0
FirstRecord returns the oldest record in a journal.
type RangeFunc ¶
A RangeFunc is a function used to range over the records in a Journal.
If err is non-nil, ranging stops and err is propagated up the stack. Otherwise, if ok is false, ranging stops without any error being propagated.
type Store ¶
type Store interface {
// Open returns the journal with the given name.
Open(ctx context.Context, name string) (Journal, error)
}
Store is a collection of journals.
func WithTelemetry ¶ added in v0.2.1
func WithTelemetry( s Store, p trace.TracerProvider, m metric.MeterProvider, l *slog.Logger, ) Store
WithTelemetry returns a Store that adds telemetry to s.
Source Files