cidrx is a simple Go library for efficient IPv6 address pool management. It uses fixed-size bitmap blocks and 128-bit integer arithmetic to allocate and release IPs in O(1) time with minimal heap allocations.

• Large-scale pools: Supports up to 2⁶³ blocks per pool, each block covering 2^(128-blockPrefix) addresses
• Lazy block creation: Blocks are allocated on-demand, minimizing memory usage
• Bitmap-backed: Each block uses a uint64 bitmap for ultra-fast allocation and release
• Low allocations: Pre-reserved free-list and bitwise arithmetic mean zero or minimal heap allocations on the hot path
• Snapshot/Restore: Export pool state and recreate it later via Snapshot and NewPoolFromSnapshot
• Concurrency-safe: Thread-safe via a simple sync.Mutex; optional sharding strategies can further improve throughput

go get github.com/yago-123/cidrx

package main

import (
    "fmt"
    "net"
    "log"
	
    "github.com/yago-123/cidrx"
)

func main() {
    // Create a pool for 2001:db8::/64 split into /120 blocks
    pool, err := cidrx.NewPool("2001:db8::", 64, 120, 1024)
    if err != nil {
        log.Fatal(err)
    }

    // Allocate 10 IPs
    for i := 0; i < 10; i++ {
        ip, errAlloc := pool.Allocate()
        if errAlloc != nil {
            log.Printf("Allocate error: %v", errAlloc)
            continue
        }
        fmt.Println("Got IP:", ip)
    }

    // Release an IP
    err = pool.Release(net.ParseIP("2001:db8::3"))
    if err != nil {
        log.Println("Release error:", err)
    }
}

Constructs a new IPv6 pool.

• netAddress: base IPv6 (e.g. "2001:db8::").
• netPrefixLen: prefix length of the network (0–128).
• blockPrefix: prefix length of each block; must satisfy netPrefix < blockPrefix ≤ 128 and blockPrefix−netPrefix ≤ 63.
• expectedBlocks: estimate for number of blocks to pre-allocate free-list capacity.

Allocates and returns the next available IP in the pool.

Releases a previously allocated IP back to the pool.

Returns an in-memory snapshot of the pool state (configuration + bitmaps).

Rebuilds a Pool from a prior snapshot.

Run the test suite:

go test ./... -v

Run benchmarks:

go test ./... -bench=. -benchmem

All tests run on Linux amd64 (AMD Ryzen 5 5600H). Timings are per-op:

• Hot-path allocate: ~40 ns/op with 1 alloc (16 B) (coming from the net.IP alloc in bitToIP)
• Release: ~48 ns/op with 0 allocs
• Mixed allocate+release: ~112 ns/op
• Concurrent allocate: ~500 ns/op under a single mutex
• Block creation: cost scales with bitmap size (32 B → 32 MB)
• Block-index math: ~2 ns/op with 0 allocs

1. Shard the pool or use per-block locks to reduce mutex blocks
2. Pool or reuse large bitmaps to avoid zeroing overhead on first use