fastalloc-go

README

fastalloc-go

high-performance, pre-allocated memory pool library for go

overview

fastalloc-go provides production-grade object pooling to reduce allocations and gc pressure in performance-critical go applications. it uses go 1.18+ generics for type safety without interface overhead.

features

• multiple pool types: generic, fixed, growing, sharded, and sync.pool wrapper
• type-safe generics: zero interface casting overhead
• lifecycle hooks: constructor, reset, validate, health check, destructor
• growth strategies: none, linear, exponential, custom
• metrics & monitoring: built-in statistics and prometheus export
• lock-free operations: cas-based allocators for high concurrency
• zero dependencies: core library has no external deps

installation

go get gitlab.com/TIVisionOSS/golang/fastalloc-go

quick start

package main

import (
    "gitlab.com/TIVisionOSS/golang/fastalloc-go/pkg/fastalloc"
)

type Request struct {
    ID   string
    Data []byte
}

func main() {
    pool, _ := fastalloc.NewPool[*Request](fastalloc.Config[*Request]{
        InitialCapacity: 1000,
        MaxCapacity:     10000,
        New: func() *Request {
            return &Request{Data: make([]byte, 0, 4096)}
        },
        Reset: func(r *Request) {
            r.ID = ""
            r.Data = r.Data[:0]
        },
    })
    defer pool.Close()
    
    req := pool.Get()
    req.ID = "123"
    pool.Put(req)
}

builder pattern

pool := fastalloc.NewPoolBuilder[*Connection]().
    WithInitialCapacity(100).
    WithMaxCapacity(1000).
    WithGrowthStrategy(fastalloc.GrowthDouble).
    WithIdleTimeout(5 * time.Minute).
    WithHealthCheck(func(c *Connection) bool {
        return c.IsAlive()
    }).
    WithConstructor(NewConnection).
    WithDestructor(func(c *Connection) { c.Close() }).
    WithMetrics(true).
    Build()

http server example

var pool = fastalloc.NewPool[*Buffer](config)

func handler(w http.ResponseWriter, r *http.Request) {
    buf := pool.Get()
    defer pool.Put(buf)
    
    buf.WriteString("response")
    w.Write(buf.Bytes())
}

performance

• <50ns per operation for typed pools
• 50%+ gc pressure reduction
• linear scalability up to NumCPU
• 2-10x faster than sync.Pool for known types

see benchmark results for detailed measurements.

documentation

• architecture - system design and components
• api reference - detailed api documentation
• performance guide - tuning and optimization
• migration guide - migrating from sync.Pool
• design rationale - why we made certain choices

examples

• basic usage
• http server
• worker pool
• custom types
• grpc service
• metrics

testing

make test          # run all tests
make test-race     # run with race detector
make bench         # run benchmarks
make cover         # generate coverage report

contributing

see CONTRIBUTING.md for guidelines.

license

dual-licensed under MIT OR Apache-2.0. see LICENSE-MIT and LICENSE-APACHE.

author

developed by Eshan Roy eshanized@proton.me for Tonmoy Infrastructure & Vision

links

• repository: https://gitlab.com/TIVisionOSS/go/fastalloc-go
• issues: https://gitlab.com/TIVisionOSS/go/fastalloc-go/-/issues