encoding

Documentation

Overview

Package encoding provides serialization utilities for fingerprints and payloads.

Both WriteEntry and WriteEntryGeneric use unsafe native-endian writes and are only correct on little-endian architectures (amd64, arm64).

Index

• func ReadEntry(buf []byte, slot, entrySize, fpSize, payloadSize int) (uint32, uint64)
• func ReadFP(buf []byte, fpSize int) uint32
• func ReadPayload(buf []byte, payloadSize int) uint64
• func WriteEntry(basePtr unsafe.Pointer, pos, entrySize int, fp uint32, payload uint64, ...)
• func WriteEntryGeneric(basePtr unsafe.Pointer, pos, entrySize int, fp uint32, payload uint64, ...)

Functions

func ReadEntry

func ReadEntry(buf []byte, slot, entrySize, fpSize, payloadSize int) (uint32, uint64)

ReadEntry reads a fingerprint and payload from buf at the given slot position. This is the safe read counterpart to WriteEntry/WriteEntryGeneric.

func ReadFP

func ReadFP(buf []byte, fpSize int) uint32

ReadFP reads a little-endian fingerprint of fpSize bytes from buf. This is the safe read counterpart to the fp portion of WriteEntry/WriteEntryGeneric.

ReadFP, ReadPayload, and ReadEntry exist to verify the WriteEntry round-trip in tests; the production query path reads fingerprints/payloads via the streamhash package's own unpack helpers, not these.

func ReadPayload

func ReadPayload(buf []byte, payloadSize int) uint64

ReadPayload reads a little-endian payload of payloadSize bytes from buf. This is the safe read counterpart to the payload portion of WriteEntry/WriteEntryGeneric.

func WriteEntry

func WriteEntry(basePtr unsafe.Pointer, pos, entrySize int, fp uint32, payload uint64, fpShift uint)

WriteEntry packs a fingerprint and payload into a little-endian entry of entrySize bytes at position pos in the buffer starting at basePtr. The entry is stored as: fp | (payload << fpShift), where fpShift is fingerprintSize * 8. Callers should compute fpShift once before the loop.

Only supports entrySize 1, 4, 5, and 8; panics for other sizes. Use WriteEntryGeneric for arbitrary entry sizes. WriteEntry does not delegate to WriteEntryGeneric in the default case because adding that call pushes the function over the compiler's inlining budget, preventing inlining and causing a ~6x regression in the fast paths. When inlined at call sites that pass a constant entrySize, the compiler eliminates the unused switch branches.

Inlining budget: current cost 71, budget 80. Adding another case would likely exceed the budget and silently de-inline all paths.

func WriteEntryGeneric

func WriteEntryGeneric(basePtr unsafe.Pointer, pos, entrySize int, fp uint32, payload uint64, fpShift uint)

WriteEntryGeneric packs a fingerprint and payload into a little-endian entry of arbitrary size at position pos in the buffer starting at basePtr. Same calling convention as WriteEntry but handles all entry sizes. Prefer WriteEntry for sizes 1, 4, 5, and 8 — it uses wider writes and is inlineable, so the compiler can eliminate dead branches when entrySize is a constant.