hyperpb-go

hyperpb is a highly optimized dynamic message library for Protobuf designed for read-only workloads. It serves as a high-performance drop-in replacement for dynamicpb (the canonical solution in protobuf-go).

Key characteristics:

• Performance: Uses an efficient VM based on table-driven parsing (TDP), beating dynamicpb by up to 10x and often outperforming generated code by 2-3x.
• Read-Only: It is optimized for reading and reflection. Mutation is not supported; any operation attempting to mutate an already-parsed message will panic.
• Reflection-Based: Currently, it only supports manipulating messages through the protoreflect API.

The parser uses an optimized equality check for tag matching. Each field parser contains the expected tag (a fusion of the field number and wire type).

1. Matching: If the tag matches, the parser calls the corresponding parser thunk, which consumes the field value and may advance the field table pointer.
2. Non-matching (Retry): If the tag does not match, the parser advances the field table pointer and retries a limited number of times.
3. Fallback: If retries fail, the parser enters a fallback mode where it performs a full varint decode of the tag, searches the number table, and potentially skips unknown fields.

To reduce allocation latency and bypass the Go garbage collector, use hyperpb.Shared. A hyperpb.Shared instance acts as a pool of resources shared by messages resulting from the same parse.

Workflow:

1. Create or retain a hyperpb.Shared instance.
2. Use shared.NewMessage(msgType) to obtain a message.
3. Call shared.Free() to reclaim resources for reuse.

CRITICAL: A message (msg) must not outlive the call to shared.Free(). Failure to follow this will result in memory errors that Go cannot protect you from.

type requestContext struct {
    shared *hyperpb.Shared
    types map[string]*hyperpb.MessageType
    // Additional context fields...
}

func (c *requestContext) Handle(req Request) {
    msgType := c.types[req.Type]
    msg := c.shared.NewMessage(msgType)
    defer c.shared.Free()

    c.process(msg, req, ...)
}

The hyperpb architecture is split into two primary stages to maximize performance:

1. The Compiler: A runtime component that consumes descriptors to generate Types. These Types act as highly optimized programs for parsing specific Protobuf messages. The compiler determines memory layout (including headers, bitfields for optional/bool fields, and field storage) and selects Archetypes (specialized parsing strategies) for each field.
2. The Interpreter: A highly optimized VM that executes the programs generated by the compiler. It uses a threaded interpreter model where state is passed by-value to minimize stack spilling, and it manages its own recursion stack rather than using Go's native recursion.

To avoid the overhead of full varint decoding, the parser uses Partial Tag Decode. Since parser thunks know the expected wire format, the parser can compare raw bytes without performing full shifts or variable-length masking.

The process:

1. Byte Loading: The parser loads up to 8 bytes. It uses bitwise operations to count sign bits (treating the uint64 as a SIMD-like vector) to detect overlong tags (up to 10 bytes).
2. Masking: It uses the varint byte length to mask off bytes after the highest relevant order one. For 8, 9, or 10-byte varints, no masking is applied.
3. Clearing: Sign bits are cleared. For a match to succeed, all bytes beyond the non-zero bytes for the tag must be zero.
4. Caching: This partially decoded value is cached once per record to be compared against tdp.Tag values in the subsequent phase.

A *tdp.Type is a pointer to a location within a tdp.Library (a large byte buffer). It contains the compiled instructions for parsing and accessing a message. Key components include:

• Field Layout: Fields are laid out in field index order following the tdp.Type to facilitate efficient reflection.
• TypeParser: Contains tdp.FieldParsers, which include offsets and parsing information, as well as a hand-written hashmap mapping field numbers to field indices for fast resynchronization.
• No reflect.Type: The compiled type does not use reflect.Type for dynamic messages. Instead, it relies on raw loads and stores to avoid the overhead of Go's reflection and write barriers.

To achieve high performance and avoid Garbage Collector (GC) overhead, hyperpb uses an arena-based memory model:

• Arena Allocation: All memory is allocated on arenas (via the arena package). Fields are often zero-copy references to the original parse input.
• GC Side-stepping: The implementation leverages specific Go memory semantics to avoid write barriers. By storing pointers in heap memory that is not of 'GC shape' (using uintptr or similar techniques) and ensuring those pointers are transitively reachable by the GC via the arena, the library avoids the performance penalty of atomic global updates during pointer stores.
• Zero-copy: Where possible, fields are references to the original input buffer to minimize allocations.

To verify performance and ensure changes do not degrade speed, use the provided Makefile commands. The package includes benchmarks comparing it against protobuf-go and dynamicpb.

• make bench: Runs all benchmarks.
• make profile: Runs a CPU profile and opens a local pprof instance.
• make asm: Dumps the assembly of the benchmarks for manual inspection.