Help us shape the future of Go! Take the 2026 Go Developer Survey

outerleaf

package
v0.6.1 Latest Latest
Warning

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

 Go to latest Published: Jul 1, 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.