outerleaf

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 3, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrBlobRefEntry = errors.New("outerleaf: blob-ref entry requires nested resolution")

ErrBlobRefEntry is returned by legacy decode helpers when a v3 entry contains a blob reference and nested resolution is required.

Functions

func Decode 

func Decode(payload []byte, scratch []byte) (key []byte, value []byte, ok bool, outScratch []byte, err error)

Decode returns the first key/value in an encoded outer-leaf payload.

func DecodeKeysRangeWithVerify 

func DecodeKeysRangeWithVerify(payload []byte, lower []byte, upper []byte, verifyChecksum bool) ([][]byte, error)

DecodeKeysRangeWithVerify decodes only keys in [lower, upper) from an encoded outer-leaf payload.

func DecodeKeysWithVerify 

func DecodeKeysWithVerify(payload []byte, verifyChecksum bool) ([][]byte, error)

DecodeKeysWithVerify decodes logical keys from an encoded outer-leaf payload.

func DecodeLowerBoundAndKeysOnMatchWithVerify 

func DecodeLowerBoundAndKeysOnMatchWithVerify(payload []byte, target []byte, verifyChecksum bool) (pos int, below bool, above bool, keys [][]byte, err error)

DecodeLowerBoundAndKeysOnMatchWithVerify decodes lower-bound classification for target and materializes full keys only when target falls within block bounds. For below/above classifications, keys are not allocated.

func DecodeValue 

func DecodeValue(payload []byte, scratch []byte) (value []byte, ok bool, outScratch []byte, err error)

DecodeValue returns the first value in an encoded outer-leaf payload.

func DecodeValueForKey 

func DecodeValueForKey(payload []byte, key []byte, scratch []byte) (value []byte, ok bool, found bool, outScratch []byte, err error)

DecodeValueForKey resolves key inside an encoded outer-leaf payload.

ok reports whether payload is an outer-leaf payload. found reports whether key exists in that payload.

func EncodeEntries 

func EncodeEntries(dst []byte, entries []Entry, codec uint8, restartInterval int) ([]byte, error)

EncodeEntries encodes an ordered block of key/value records using v2 layout.

func EncodeEntriesAssumeSorted 

func EncodeEntriesAssumeSorted(dst []byte, entries []Entry, codec uint8, restartInterval int) ([]byte, error)

EncodeEntriesAssumeSorted encodes an ordered block of key/value records using v2 layout without re-validating strict key ordering.

func EncodeSingle 

func EncodeSingle(dst, key, value []byte, codec uint8, restartInterval int) ([]byte, error)

EncodeSingle encodes one key/value record in a v1-compatible payload.

func EncodeSingleBlobRef 

func EncodeSingleBlobRef(dst, key []byte, ptr page.ValuePtr, codec uint8, restartInterval int) ([]byte, error)

EncodeSingleBlobRef encodes one key -> blob pointer entry using v3 layout.

func EncodeTypedEntries 

func EncodeTypedEntries(dst []byte, entries []TypedEntry, codec uint8, restartInterval int) ([]byte, error)

EncodeTypedEntries encodes ordered typed entries using v3 layout.

func EncodeTypedEntriesAssumeSorted 

func EncodeTypedEntriesAssumeSorted(dst []byte, entries []TypedEntry, codec uint8, restartInterval int) ([]byte, error)

EncodeTypedEntriesAssumeSorted encodes ordered typed entries using v3 layout without re-validating strict key ordering.

func HasMagic 

func HasMagic(payload []byte) bool

HasMagic reports whether payload begins with the outer-leaf block magic header. It is a cheap classifier for outer-leaf encoded values.

func NormalizeBlockTargetBytes 

func NormalizeBlockTargetBytes(target int) int

func NormalizeRestartInterval 

func NormalizeRestartInterval(interval int) int

Types

type DecodedBlock 

type DecodedBlock struct {
	// contains filtered or unexported fields
}

DecodedBlock represents a parsed outer-leaf payload.

func DecodeBlock 

func DecodeBlock(payload []byte, scratch []byte) (*DecodedBlock, error)

DecodeBlock parses an outer-leaf payload and keeps the decoded data alive.

func DecodeBlockLease 

func DecodeBlockLease(payload []byte) (*DecodedBlock, error)

DecodeBlockLease parses an outer-leaf payload using lease-owned decode buffers. Callers must call Release on the returned block.

Any slices returned by the decoded block may alias lease-owned storage and become invalid after Release.

func DecodeBlockLeaseWithScratchAndVerify 

func DecodeBlockLeaseWithScratchAndVerify(payload []byte, scratch []byte, dst *DecodedBlock, verifyChecksum bool) (*DecodedBlock, []byte, error)

DecodeBlockLeaseWithScratchAndVerify parses an outer-leaf payload using caller-provided scratch and lease-owned decode buffers.

It returns the decoded block and a caller-owned scratch slice to reuse on the next decode attempt.

Any slices returned by the decoded block may alias lease-owned storage and become invalid after Release.

func DecodeBlockLeaseWithVerify 

func DecodeBlockLeaseWithVerify(payload []byte, verifyChecksum bool) (*DecodedBlock, error)

DecodeBlockLeaseWithVerify parses an outer-leaf payload using lease-owned decode buffers and optional checksum verification. Callers must call Release on the returned block.

Any slices returned by the decoded block may alias lease-owned storage and become invalid after Release.

func DecodeBlockWithVerify 

func DecodeBlockWithVerify(payload []byte, scratch []byte, verifyChecksum bool) (*DecodedBlock, error)

DecodeBlockWithVerify parses an outer-leaf payload and optionally verifies the block checksum.

func (*DecodedBlock) Entries 

func (d *DecodedBlock) Entries(dst []Entry) ([]Entry, error)

Entries decodes all logical key/value records from a parsed block. Returned keys/values reference decoded block storage where possible.

func (*DecodedBlock) EntryCount 

func (d *DecodedBlock) EntryCount() int

func (*DecodedBlock) EntryForKey 

func (d *DecodedBlock) EntryForKey(key []byte) (LookupResult, bool, error)

EntryForKey resolves key inside a decoded block and returns typed payload data.

func (*DecodedBlock) EntryForKeyNoRestartKeys 

func (d *DecodedBlock) EntryForKeyNoRestartKeys(key []byte) (LookupResult, bool, error)

EntryForKeyNoRestartKeys resolves key inside a decoded block without materializing restart key slices.

func (*DecodedBlock) FirstKind 

func (d *DecodedBlock) FirstKind() EntryKind

FirstKind reports the payload kind of the first logical entry.

func (*DecodedBlock) FirstValue 

func (d *DecodedBlock) FirstValue() ([]byte, error)

FirstValue returns the first value stored in the decoded block.

func (*DecodedBlock) Keys 

func (d *DecodedBlock) Keys(dst [][]byte) ([][]byte, error)

Keys decodes all logical keys from a parsed block. Returned key slices reference decoded block storage where possible.

func (*DecodedBlock) KeysRange 

func (d *DecodedBlock) KeysRange(dst [][]byte, lower []byte, upper []byte) ([][]byte, error)

KeysRange decodes only keys in [lower, upper) from a parsed block. Returned key slices reference decoded block storage where possible.

func (*DecodedBlock) KeysRangeLease 

func (d *DecodedBlock) KeysRangeLease(lower []byte, upper []byte) (*KeyLease, error)

KeysRangeLease decodes keys in [lower, upper) and returns them via a lease. Callers must release the lease when finished.

func (*DecodedBlock) LowerBound 

func (d *DecodedBlock) LowerBound(target []byte) (pos int, below bool, above bool, err error)

LowerBound returns the first entry index whose key is >= target and classifies whether target falls below the block range, within it, or above it.

func (*DecodedBlock) RawBytes 

func (d *DecodedBlock) RawBytes() []byte

RawBytes returns the decoded raw payload backing this block.

func (*DecodedBlock) ReclaimTransferredScratchForRelease 

func (d *DecodedBlock) ReclaimTransferredScratchForRelease(scratch []byte) []byte

ReclaimTransferredScratchForRelease hands caller-owned scratch (returned by DecodeBlockLeaseWithScratchAndVerify) back to the block so Release can return it to the outerleaf bytes pool.

It returns nil when ownership was reclaimed; otherwise it returns scratch unchanged.

func (*DecodedBlock) Release 

func (d *DecodedBlock) Release()

Release returns lease-owned decode buffers back to outerleaf pools. Any slices previously returned by this block become invalid after Release. It is safe to call Release multiple times.

func (*DecodedBlock) TypedEntries 

func (d *DecodedBlock) TypedEntries(dst []TypedEntry) ([]TypedEntry, error)

TypedEntries decodes all logical records from a parsed block with kind info.

func (*DecodedBlock) ValueForKey 

func (d *DecodedBlock) ValueForKey(key []byte) ([]byte, bool, error)

ValueForKey resolves a value for the provided key inside the decoded block.

func (*DecodedBlock) VisitTypedEntries 

func (d *DecodedBlock) VisitTypedEntries(fn func(key []byte, kind EntryKind, value []byte, ptr page.ValuePtr) error) error

VisitTypedEntries iterates over decoded logical entries and calls fn for each. Keys and inline values alias decoded block storage; blob refs are surfaced via ptr.

This avoids allocating a full []TypedEntry slice for callers that only need to stream through entries.

type Encoder 

type Encoder struct {
	// contains filtered or unexported fields
}

Encoder reuses encode scratch buffers across outer-leaf block encodes.

It is not safe for concurrent use.

func (*Encoder) EncodeEntries 

func (e *Encoder) EncodeEntries(dst []byte, entries []Entry, codec uint8, restartInterval int) ([]byte, error)

EncodeEntries encodes ordered key/value records using reusable scratch buffers.

func (*Encoder) EncodeEntriesAssumeSorted 

func (e *Encoder) EncodeEntriesAssumeSorted(dst []byte, entries []Entry, codec uint8, restartInterval int) ([]byte, error)

EncodeEntriesAssumeSorted encodes ordered key/value records without re-validating strict ordering and reuses scratch buffers across calls.

func (*Encoder) EncodeSingle 

func (e *Encoder) EncodeSingle(dst, key, value []byte, codec uint8, restartInterval int) ([]byte, error)

EncodeSingle encodes one key/value record using reusable scratch buffers.

func (*Encoder) EncodeTypedEntries 

func (e *Encoder) EncodeTypedEntries(dst []byte, entries []TypedEntry, codec uint8, restartInterval int) ([]byte, error)

EncodeTypedEntries encodes ordered typed entries using v3 layout.

func (*Encoder) EncodeTypedEntriesAssumeSorted 

func (e *Encoder) EncodeTypedEntriesAssumeSorted(dst []byte, entries []TypedEntry, codec uint8, restartInterval int) ([]byte, error)

EncodeTypedEntriesAssumeSorted encodes ordered typed entries using v3 layout without re-validating strict key ordering.

func (*Encoder) Reset 

func (e *Encoder) Reset()

Reset clears reusable encoder slices while keeping allocated capacity.

func (*Encoder) Trim 

func (e *Encoder) Trim(maxRawCap, maxEncCap, maxRestartsCap int)

Trim drops oversized scratch buffers and resets retained buffers to zero len.

type Entry 

type Entry struct {
	Key   []byte
	Value []byte
}

Entry is one key/value record in an outer-leaf block payload.

type EntryKind 

type EntryKind uint8

EntryKind identifies the value payload encoding for a v3 entry. 

const (
	EntryKindInline  EntryKind = 0
	EntryKindBlobRef EntryKind = 1
)

type KeyLease 

type KeyLease struct {
	// contains filtered or unexported fields
}

KeyLease provides explicit ownership for decoded key vectors. Callers must call Release when finished.

func DecodeKeysRangeLeaseWithVerify 

func DecodeKeysRangeLeaseWithVerify(payload []byte, lower []byte, upper []byte, verifyChecksum bool) (*KeyLease, error)

DecodeKeysRangeLeaseWithVerify decodes keys in [lower, upper) and returns a lease that must be released by the caller.

func DecodeLowerBoundAndKeysOnMatchLeaseWithVerify 

func DecodeLowerBoundAndKeysOnMatchLeaseWithVerify(payload []byte, target []byte, verifyChecksum bool) (pos int, below bool, above bool, lease *KeyLease, err error)

DecodeLowerBoundAndKeysOnMatchLeaseWithVerify decodes lower-bound classification for target and returns keys via a lease only when target falls within block bounds.

func (*KeyLease) Keys 

func (l *KeyLease) Keys() [][]byte

Keys returns decoded keys owned by the lease.

func (*KeyLease) Release 

func (l *KeyLease) Release()

Release returns lease-owned buffers to pools. It is idempotent.

type LookupResult 

type LookupResult struct {
	Kind    EntryKind
	Value   []byte
	BlobPtr page.ValuePtr
}

LookupResult is the decoded v3 lookup result kind/payload pair.

func DecodeEntryForKey 

func DecodeEntryForKey(payload []byte, key []byte, scratch []byte) (entry LookupResult, ok bool, found bool, outScratch []byte, err error)

DecodeEntryForKey resolves key inside an encoded outer-leaf payload and returns typed payload info (inline value or blob reference).

ok reports whether payload is an outer-leaf payload. found reports whether key exists in that payload.

func DecodeEntryForKeyWithVerify 

func DecodeEntryForKeyWithVerify(payload []byte, key []byte, scratch []byte, verifyChecksum bool) (entry LookupResult, ok bool, found bool, outScratch []byte, err error)

DecodeEntryForKeyWithVerify resolves key inside an encoded outer-leaf payload and optionally verifies the block checksum.

ok reports whether payload is an outer-leaf payload. found reports whether key exists in that payload.

type TypedEntry 

type TypedEntry struct {
	Key     []byte
	Kind    EntryKind
	Value   []byte
	BlobPtr page.ValuePtr
}

TypedEntry describes one key entry with either inline bytes or a blob ref.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.