bytebufferpool

bytebufferpool is a small, focused Go library that implements a sync.Pool-based pool of byte buffers designed to minimize memory allocations and garbage collection pressure in high-throughput services. Instead of allocating a new []byte slice on every request, callers Get a ByteBuffer from the pool, write into it via the same io.Writer/io.ReaderFrom/io.WriterTo-compatible API as bytes.Buffer, and Put it back when done, letting the pool reuse the underlying memory across requests.

What sets it apart from a naive sync.Pool wrapper is its self-calibrating sizing: the pool tracks the distribution of buffer sizes requested over time and periodically recalculates a default and maximum buffer size so that oversized, rarely-needed buffers don’t get pooled forever and waste memory. This anti-fragmentation logic is what backs high-performance projects like fasthttp and quicktemplate, where allocation overhead directly affects request latency and throughput.

What You Get

• A global default Pool accessible via package-level Get()/Put() functions, plus the ability to create isolated Pool instances for distinct buffer size classes.
• A ByteBuffer type that implements io.Writer, io.ReaderFrom, and io.WriterTo, so it drops into code already written against bytes.Buffer.
• Self-calibrating size tracking that periodically recomputes the pool’s default and maximum buffer sizes based on the 95th-percentile of recent usage, avoiding pinned oversized buffers.
• A thread-safe implementation built on sync.Pool and atomic counters, verified by concurrent test cases in the test suite.

Common Use Cases

• Reducing per-request allocations in HTTP servers and routers that build request/response bodies on every call.
• Buffering template rendering output in template engines like quicktemplate without allocating a fresh buffer per render.
• Serializing or encoding data (JSON, protobuf, logs) in tight loops where allocation churn shows up in profiling.
• Any latency-sensitive service that wants bytes.Buffer ergonomics without paying GC costs for short-lived buffers.

Under The Hood

Architecture The library is a single flat package split across two small files: pool.go, which defines the Pool struct (a sync.Pool wrapper plus a per-size-bucket call histogram and atomically-updated defaultSize/maxSize fields), and bytebuffer.go, which defines the ByteBuffer type itself. There’s no internal layering or dependency injection — a package-level defaultPool singleton is exposed through Get()/Put() for the common case, while callers needing isolated calibration can construct their own Pool. The data flow is simple: Get() pulls a buffer from sync.Pool or allocates one at defaultSize; the caller appends to ByteBuffer.B; Put() resets the buffer, records its size in the call histogram, and every calibrateCallsThreshold calls triggers calibrate(), which recomputes defaultSize and maxSize from the observed size distribution. If that calibration logic were removed, the pool would degrade to a plain, uncapped sync.Pool with no anti-fragmentation protection.

Tech Stack Pure Go standard library — sync, sync/atomic, sort, and io — with zero third-party dependencies, declared against go.mod’s go 1.12. There is no build tooling beyond go test; CI is a legacy .travis.yml that runs the test suite, and the module ships as a plain importable Go package with no CLI, server, or ORM surface since it’s a low-level memory-management primitive.

Code Quality The repo has a real test suite: bytebuffer_test.go and pool_test.go exercise both serial and concurrent Get/Put cycles across a range of buffer sizes, bytebuffer_timing_test.go benchmarks ByteBuffer against bytes.Buffer, and bytebuffer_example_test.go provides a runnable godoc example. Error handling is minimal by design, matching the io.Reader/io.Writer contracts it implements. Naming is idiomatic Go and every exported symbol carries a doc comment, but there’s no linter configuration beyond a Go Report Card badge, and the Travis CI setup is inactive along with the rest of the repository (no commits since mid-2024).

API Design The public API is deliberately tiny: package-level Get()/Put() require no setup, and ByteBuffer mirrors bytes.Buffer’s method set (Write, WriteString, WriteByte, Bytes, String, Reset, ReadFrom, WriteTo) closely enough to be a near drop-in replacement in existing code. The self-calibrating sizing removes any manual tuning burden — callers never have to guess or configure a buffer size, they just Get and Put.