Documentation
¶
Overview ¶
Package binaryutil provides utility functions for working with binary data.
Package binaryutil provides functions for reading binary primitives from byte slices. It is used internally for BSON parsing and wire protocol operations.
The functions in this package are designed for use in BSON operations. Signed integer functions (ReadI32, ReadI64) use manual bit-shifting rather than encoding/binary to avoid unsafe signed/unsigned conversions and comply with gosec G115. Bounds-check elimination (BCE) hints help the compiler inline these functions.
Benchmarking across different ARM64 architectures (Apple M-series) revealed non-deterministic performance discrepancies between using the "encoding/binary" standard library and manual bit-shifting ("straight-lining").
Without Loss of Generality (WLOG), benchmarking observed that:
- On Apple M1 Pro: Standard library (ReadU32) outperformed manual bit-shifting (ReadI32) by ~2x (~0.08ns vs ~0.16ns).
- On Apple M4 Max: Manual bit-shifting (ReadI32) outperformed the standard library (ReadU32) by ~1.6x (~0.03ns vs ~0.05ns).
Further testing showed that "straight-lining" the ReadU32 implementation to match ReadI32 normalized performance to ~0.03ns on the M4 Max, even though the generated assembly for both approaches is virtually equivalent.
The generated assembly is nearly identical for both approaches. These sub-nanosecond variations likely stem from microarchitecture differences (instruction caching, branch prediction) rather than the code itself.
Since network I/O dominates driver latency, these differences do not have a significant impact on driver performance. The implementation favors security compliance and readability over hardware-specific tuning.
Index ¶
- func Append32[T ~uint32 | ~int32](dst []byte, v T) []byte
- func Append64[T ~uint64 | ~int64](dst []byte, v T) []byte
- func ReadCString(src []byte) (string, []byte, bool)
- func ReadCStringBytes(src []byte) ([]byte, []byte, bool)
- func ReadI32(src []byte) (int32, []byte, bool)
- func ReadI64(src []byte) (int64, []byte, bool)
- func ReadU32(src []byte) (uint32, []byte, bool)
- func ReadU64(src []byte) (uint64, []byte, bool)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Append32 ¶
Append32 appends a uint32 or int32 value to dst in little-endian byte order. Byte shifting is done directly to prevent overflow security errors, in compliance with gosec G115.
See: https://cs.opensource.google/go/go/+/refs/tags/go1.19:src/encoding/binary/binary.go;l=92
func Append64 ¶
Append64 appends a uint64 or int64 value to dst in little-endian byte order. Byte shifting is done directly to prevent overflow security errors, in compliance with gosec G115.
See: https://cs.opensource.google/go/go/+/refs/tags/go1.19:src/encoding/binary/binary.go;l=119
func ReadCString ¶
ReadCString reads a null-terminated C string from src as a string. It delegates to ReadCStringBytes to maintain a single source of truth for C string parsing logic.
func ReadCStringBytes ¶
ReadCStringBytes reads a null-terminated C string from src as a byte slice. This is the base implementation used by ReadCString to ensure a single source of truth for C string parsing logic.
func ReadI32 ¶
ReadI32 reads an int32 from src in little-endian byte order. Byte shifting is done directly to prevent overflow security errors, in compliance with gosec G115. ReadU32 and ReadI32 are separate functions to avoid unsafe casting between unsigned and signed integers.
See: https://cs.opensource.google/go/go/+/refs/tags/go1.19:src/encoding/binary/binary.go;l=79
func ReadI64 ¶
ReadI64 reads an int64 from src in little-endian byte order. Byte shifting is done directly to prevent overflow security errors, in compliance with gosec G115. ReadU64 and ReadI64 are separate functions to avoid unsafe casting between unsigned and signed integers.
See: https://cs.opensource.google/go/go/+/refs/tags/go1.19:src/encoding/binary/binary.go;l=101
Types ¶
This section is empty.
Source Files