add sync.Pool for fringe and leaf

Author: gaissmai

README.md

@@ -149,9 +149,7 @@ other methods unmodified to the underlying Table.
 Some delegated methods are pointless without a payload.
 
 ```golang
-   type Lite struct {
-   	 Table[struct{}]
-   }
+   type Lite struct { ...  }
      // Lite is just a convenience wrapper for Table, instantiated with an
      // empty struct as payload. Lite is ideal for simple IP ACLs
      // (access-control-lists) with plain true/false results without a payload.

dumper.go

@@ -97,7 +97,7 @@ func (n *node[V]) dump(w io.Writer, path stridePath, depth int, is4 bool) {
 		fmt.Fprintln(w)
 
 		// skip values if the payload is the empty struct
-		if _, ok := any(n.prefixes.Items[0]).(struct{}); !ok {
+		if _, ok := any(n.prefixes.Items[0]).(zeroStruct); !ok {
 
 			// print the values for this node
 			fmt.Fprintf(w, "%svalues(#%d):", indent, nPfxCount)
@@ -147,7 +147,7 @@ func (n *node[V]) dump(w io.Writer, path stridePath, depth int, is4 bool) {
 
 				// Lite: val is the empty struct, don't print it
 				switch any(pc.value).(type) {
-				case struct{}:
+				case zeroStruct:
 					fmt.Fprintf(w, " %s:{%s}", addrFmt(addr, is4), pc.prefix)
 				default:
 					fmt.Fprintf(w, " %s:{%s, %v}", addrFmt(addr, is4), pc.prefix, pc.value)
@@ -169,7 +169,7 @@ func (n *node[V]) dump(w io.Writer, path stridePath, depth int, is4 bool) {
 
 				// Lite: val is the empty struct, don't print it
 				switch any(pc.value).(type) {
-				case struct{}:
+				case zeroStruct:
 					fmt.Fprintf(w, " %s:{%s}", addrFmt(addr, is4), fringePfx)
 				default:
 					fmt.Fprintf(w, " %s:{%s, %v}", addrFmt(addr, is4), fringePfx, pc.value)

example_lite_concurrent_test.go

@@ -89,15 +89,16 @@ func (lf *SyncLite) Delete(pfx netip.Prefix) {
 func ExampleLite_concurrent() {
 	wg := sync.WaitGroup{}
 
-	syncTbl := NewSyncLite().WithPool()
+	syncLite := NewSyncLite()
+	syncLite.WithPool()
 
 	wg.Add(1)
 	go func() {
 		defer wg.Done()
 		for range 1_000_000 {
 			for _, s := range exampleIPs {
 				ip := netip.MustParseAddr(s)
-				_ = syncTbl.Contains(ip)
+				_ = syncLite.Contains(ip)
 			}
 		}
 	}()
@@ -108,7 +109,7 @@ func ExampleLite_concurrent() {
 		for range 10_000 {
 			for _, s := range examplePrefixes {
 				pfx := netip.MustParsePrefix(s)
-				syncTbl.Insert(pfx)
+				syncLite.Insert(pfx)
 			}
 		}
 	}()
@@ -119,7 +120,7 @@ func ExampleLite_concurrent() {
 		for range 10_000 {
 			for _, s := range examplePrefixes {
 				pfx := netip.MustParsePrefix(s)
-				syncTbl.Delete(pfx)
+				syncLite.Delete(pfx)
 			}
 		}
 	}()

lite.go

@@ -7,6 +7,13 @@ import (
 	"net/netip"
 )
 
+type zeroStruct struct{}
+
+// zeroStruct must implement Cloner.
+func (z zeroStruct) Clone() zeroStruct {
+	return zeroStruct{}
+}
+
 // Lite is just a convenience wrapper for Table, instantiated with an
 // empty struct as payload. Lite is ideal for simple IP ACLs
 // (access-control-lists) with plain true/false results without a payload.
@@ -20,7 +27,7 @@ import (
 //   - Update
 //   - UpdatePersist
 type Lite struct {
-	Table[struct{}]
+	Table[zeroStruct]
 }
 
 // WithPool is an adapter for the underlying table.

multipool.go

@@ -0,0 +1,187 @@
+package bart
+
+import (
+	"net/netip"
+	"sync"
+	"sync/atomic"
+)
+
+// multiPool groups sub-pools for internal node, leaf, and fringe types.
+// Each sub-multiPool handles allocation, reuse, and statistics tracking
+// for its corresponding node type.
+type multiPool[V any] struct {
+	node   *nodePool[V]
+	leaf   *leafPool[V]
+	fringe *fringePool[V]
+}
+
+// newMultiPool initializes and returns a new pool structure with sub-pools
+// for internal, leaf, and fringe nodes.
+func newMultiPool[V any]() *multiPool[V] {
+	return &multiPool[V]{
+		node:   newNodePool[V](),
+		leaf:   newLeafPool[V](),
+		fringe: newFringePool[V](),
+	}
+}
+
+// getNode obtains a *node[V] from the pool.
+// If the parent pool is nil, a new instance is returned without tracking.
+func (mp *multiPool[V]) getNode() *node[V] {
+	if mp == nil {
+		return new(node[V])
+	}
+	mp.node.currentLive.Add(1)
+	return mp.node.Get().(*node[V])
+}
+
+// getLeaf obtains a *leafNode[V] from the pool, initialized with
+// a prefix and value. If the pool is nil, a fresh instance is created.
+func (mp *multiPool[V]) getLeaf(pfx netip.Prefix, val V) *leafNode[V] {
+	if mp == nil {
+		return &leafNode[V]{prefix: pfx, value: val}
+	}
+	mp.leaf.currentLive.Add(1)
+	l := mp.leaf.Get().(*leafNode[V])
+	l.prefix = pfx
+	l.value = val
+	return l
+}
+
+// getFringe obtains a *fringeNode[V] from the pool, initialized with a value.
+// If the pool is nil, a new instance is returned without tracking.
+func (mp *multiPool[V]) getFringe(val V) *fringeNode[V] {
+	if mp == nil {
+		return &fringeNode[V]{value: val}
+	}
+	mp.fringe.currentLive.Add(1)
+	f := mp.fringe.Get().(*fringeNode[V])
+	f.value = val
+	return f
+}
+
+// putNode returns an internal node back to its pool for reuse.
+// If the pool is nil, the node is discarded.
+func (mp *multiPool[V]) putNode(n *node[V]) {
+	if mp != nil {
+		n.reset() // clear internal state but keep allocated memory
+		mp.node.currentLive.Add(-1)
+		mp.node.Put(n)
+	}
+}
+
+// putLeaf returns a leaf node back to its pool for reuse.
+// If the pool is nil, the node is discarded.
+func (mp *multiPool[V]) putLeaf(l *leafNode[V]) {
+	if mp != nil {
+		mp.leaf.currentLive.Add(-1)
+		mp.leaf.Put(l)
+	}
+}
+
+// putFringe returns a fringe node back to its pool for reuse.
+// If the pool is nil, the node is discarded.
+func (mp *multiPool[V]) putFringe(f *fringeNode[V]) {
+	if mp != nil {
+		mp.fringe.currentLive.Add(-1)
+		mp.fringe.Put(f)
+	}
+}
+
+// nodeStats returns the number of currently live (checked-out) nodes
+// and the total number of *node[V] objects ever allocated by this pool.
+func (mp *multiPool[V]) nodeStats() (live int64, total int64) {
+	if mp == nil {
+		return 0, 0
+	}
+	return mp.node.currentLive.Load(), mp.node.totalAllocated.Load()
+}
+
+// leafStats returns the current number of in-use leaf nodes and
+// the total number created across the pool's lifetime.
+func (mp *multiPool[V]) leafStats() (live int64, total int64) {
+	if mp == nil {
+		return 0, 0
+	}
+	return mp.leaf.currentLive.Load(), mp.leaf.totalAllocated.Load()
+}
+
+// leafStats returns the current number of in-use fringe nodes and
+// the total number created across the pool's lifetime.
+func (mp *multiPool[V]) fringeStats() (live int64, total int64) {
+	if mp == nil {
+		return 0, 0
+	}
+	return mp.fringe.currentLive.Load(), mp.fringe.totalAllocated.Load()
+}
+
+// ##################################################################
+
+// nodePool is a type-safe wrapper around sync.Pool,
+// specialized for managing *node[V] instances.
+//
+// It supports efficient memory reuse and tracks allocation
+// and usage statistics to aid debugging and profiling.
+type nodePool[V any] struct {
+	sync.Pool
+	totalAllocated atomic.Int64 // total number of *node[V] instances ever created
+	currentLive    atomic.Int64 // number of currently checked-out (in-use) nodes
+}
+
+// newNodePool constructs and returns a nodePool with tracking enabled.
+func newNodePool[V any]() *nodePool[V] {
+	np := &nodePool[V]{}
+	np.New = func() any {
+		np.totalAllocated.Add(1)
+		return new(node[V])
+	}
+	return np
+}
+
+// ##################################################################
+
+// leafPool is a sync.Pool wrapper for *leafNode[V] objects.
+// It tracks allocation and reuse statistics for monitoring purposes.
+type leafPool[V any] struct {
+	sync.Pool
+	totalAllocated atomic.Int64
+	currentLive    atomic.Int64
+}
+
+// newLeafPool initializes a leafPool instance with a node constructor.
+func newLeafPool[V any]() *leafPool[V] {
+	lp := &leafPool[V]{}
+	lp.New = func() any {
+		lp.totalAllocated.Add(1)
+		return new(leafNode[V])
+	}
+	return lp
+}
+
+// ##################################################################
+
+// fringePool is a type-safe wrapper around sync.Pool,
+// specialized for managing *node[V] instances.
+//
+// It efficiently reuses node memory and tracks statistics
+// on allocations and active use for debugging and performance tuning.
+type fringePool[V any] struct {
+	sync.Pool // embedded Sync Pool for *node[V]
+
+	totalAllocated atomic.Int64 // total number of *node[V] ever allocated
+	currentLive    atomic.Int64 // number of nodes currently in use (not returned to pool)
+}
+
+// newFringePool creates and returns a new pool for *fringeNode[V] instances.
+//
+// The pool uses sync.Pool internally, and defines a New function
+// that creates new nodes with statistical tracking.
+func newFringePool[V any]() *fringePool[V] {
+	fp := &fringePool[V]{}
+	fp.New = func() any {
+		fp.totalAllocated.Add(1)
+
+		return new(fringeNode[V])
+	}
+	return fp
+}