Remove GetBlock/PutBlock, GetN/PutN; split pool into themed files

- Remove GetBlock, PutBlock and blocking support (Cond/Mutex, blockedShards)
- Remove GetN, PutN; callers use Get/Put in a loop
- Update README: drop GetBlock/PutBlock from docs
- Split pool.go into themed files:
  - config.go: errors, GcLevel, CleanupPolicy, Config, GrowthPolicy, validation
  - poolable.go: Poolable, Fields, Allocator, Cleaner
  - cleanup.go: startCleaner, cleanup, filterUsableObjects, reinsertKeptObjects
  - pool.go: Shard, ShardedPool, NewPool, Get, Put, clear, Close, runtime linknames
- Adjust tests for removed APIs (initShards, TestClear, TestClose, TestClearRaceCondition)

Author: AlexsanderHamir

README.md

@@ -170,7 +170,7 @@ type GrowthPolicy struct {
 }
 ```
 
-> If the pool reaches its limit, it returns nil. To avoid this behavior, you can use GetBlock() or PutBlock(), which block until resources become available.
+> If the pool reaches its limit, Get() returns nil.
 
 ## Cleanup Policy
 

pool/cleanup.go

@@ -0,0 +1,122 @@
+package pool
+
+import (
+	"time"
+)
+
+// startCleaner starts the background cleanup goroutine.
+func (p *ShardedPool[T, P]) startCleaner() {
+	p.cleanWg.Add(1)
+	go func() {
+		defer p.cleanWg.Done()
+		ticker := time.NewTicker(p.cfg.Cleanup.Interval)
+		defer ticker.Stop()
+
+		for {
+			select {
+			case <-ticker.C:
+				p.cleanup()
+			case <-p.stopClean:
+				return
+			}
+		}
+	}()
+}
+
+// cleanup removes idle objects based on the [CleanupPolicy].
+func (p *ShardedPool[T, P]) cleanup() {
+	if !p.cfg.Cleanup.Enabled {
+		return
+	}
+
+	for _, shard := range p.Shards {
+		p.cleanupShard(shard)
+	}
+}
+
+func (p *ShardedPool[T, P]) cleanupShard(shard *Shard[T, P]) {
+	oldHead := p.tryTakeOwnership(shard)
+	if oldHead == nil {
+		return
+	}
+
+	keptHead, keptTail, evictedCount := p.filterUsableObjects(oldHead)
+
+	if evictedCount > 0 {
+		p.CurrentPoolLength.Add(-int64(evictedCount))
+	}
+
+	if keptHead != nil {
+		p.reinsertKeptObjects(shard, keptHead, keptTail)
+	}
+}
+
+func (p *ShardedPool[T, P]) tryTakeOwnership(shard *Shard[T, P]) P {
+	head := P(shard.Head.Load())
+	if head == nil {
+		return nil
+	}
+	if !shard.Head.CompareAndSwap(head, nil) {
+		return nil
+	}
+	return head
+}
+
+// filterUsableObjects filters objects based on usage count and returns the kept head, kept tail, and number of evicted objects.
+func (p *ShardedPool[T, P]) filterUsableObjects(head P) (keptHead, keptTail P, evictedCount int) {
+	current := head
+
+	for current != nil {
+		next := current.GetNext()
+		usageCount := current.GetUsageCount()
+
+		if usageCount >= p.cfg.Cleanup.MinUsageCount {
+			current.ResetUsage()
+			if keptHead == nil {
+				keptHead = current
+			} else {
+				keptTail.SetNext(current)
+			}
+			keptTail = current
+		} else {
+			current.SetNext(nil)
+			evictedCount++
+		}
+		current = next
+	}
+
+	if keptHead == nil {
+		return nil, nil, evictedCount
+	}
+
+	keptTail.SetNext(nil)
+	return keptHead, keptTail, evictedCount
+}
+
+func (p *ShardedPool[T, P]) reinsertKeptObjects(shard *Shard[T, P], keptHead, keptTail P) {
+	// Find the shard index for this shard
+	var shardID int
+	for i, s := range p.Shards {
+		if s == shard {
+			shardID = i
+			break
+		}
+	}
+
+	// Set the correct shard index for all kept objects
+	current := keptHead
+	for current != nil {
+		current.SetShardIndex(shardID)
+		current = current.GetNext()
+	}
+
+	for {
+		currentHead := P(shard.Head.Load())
+		if currentHead != nil {
+			keptTail.SetNext(currentHead)
+		}
+		if shard.Head.CompareAndSwap(currentHead, keptHead) {
+			break
+		}
+	}
+}

pool/config.go

@@ -0,0 +1,145 @@
+// Config, cleanup policy, growth policy, and validation for the pool.
+package pool
+
+import (
+	"errors"
+	"fmt"
+	"runtime"
+	"time"
+)
+
+// Common errors that may be returned by the pool.
+var (
+	// ErrNoAllocator is returned when attempting to get an object but no allocator is configured.
+	ErrNoAllocator = errors.New("no allocator configured")
+
+	// ErrNoCleaner is returned when attempting to create a pool but no cleaner is configured.
+	ErrNoCleaner = errors.New("no cleaner configured")
+)
+
+// GcLevel offers different levels for clean up configuration.
+// These presets control how aggressively GenPool reclaims memory.
+// Note: Go's GC may still run unless you explicitly suppress it via debug.SetGCPercent(-1)
+type GcLevel string
+
+var (
+	// GcDisable disables GenPool's cleanup completely.
+	// Objects will stay in the pool indefinitely unless manually cleared.
+	GcDisable GcLevel = "disable"
+
+	// GcLow performs cleanup at long intervals with minimal aggression.
+	// Good for low-latency, high-reuse scenarios.
+	GcLow GcLevel = "low"
+
+	// GcModerate performs cleanup at regular intervals and evicts objects
+	// that are lightly used. Balances reuse and memory usage.
+	GcModerate GcLevel = "moderate"
+
+	// GcAggressive enables frequent cleanup and removes objects
+	// that are not reused often. Best for memory-constrained environments.
+	GcAggressive GcLevel = "aggressive"
+)
+
+// The number of shards is tied to GOMAXPROCS (max OS threads running Go code in parallel).
+// To reduce sharding, adjust GOMAXPROCS via runtime.GOMAXPROCS(n) before creating the pool.
+var (
+	numShards = runtime.GOMAXPROCS(0)
+)
+
+// CleanupPolicy defines how the pool should clean up unused objects.
+type CleanupPolicy struct {
+	// Enabled determines if automatic cleanup is enabled.
+	Enabled bool
+	// Interval is how often the cleanup should run.
+	Interval time.Duration
+	// MinUsageCount is the number of usage BELOW which an object will be evicted.
+	MinUsageCount int64
+}
+
+// DefaultCleanupPolicy returns a default cleanup configuration based on specified level.
+func DefaultCleanupPolicy(level GcLevel) CleanupPolicy {
+	switch level {
+	case GcDisable:
+		return CleanupPolicy{}
+	case GcLow:
+		return CleanupPolicy{
+			Enabled:       true,
+			Interval:      10 * time.Minute,
+			MinUsageCount: 1,
+		}
+	case GcModerate:
+		return CleanupPolicy{
+			Enabled:       true,
+			Interval:      2 * time.Minute,
+			MinUsageCount: 2,
+		}
+	case GcAggressive:
+		return CleanupPolicy{
+			Enabled:       true,
+			Interval:      30 * time.Second,
+			MinUsageCount: 3,
+		}
+	default:
+		// Fallback to moderate if unrecognized
+		return CleanupPolicy{
+			Enabled:       true,
+			Interval:      2 * time.Minute,
+			MinUsageCount: 2,
+		}
+	}
+}
+
+// Config holds configuration options for the pool.
+type Config[T any, P Poolable[T]] struct {
+	// Cleanup defines the cleanup policy for the pool
+	Cleanup CleanupPolicy
+
+	// Growth defined the growth policy for the pool
+	Growth GrowthPolicy
+
+	// Allocator is the function to create new objects
+	Allocator Allocator[T]
+
+	// Cleaner is the function to clean objects before returning them to the pool
+	Cleaner Cleaner[T]
+}
+
+// GrowthPolicy controls how the pool is allowed to grow.
+// If unset, the pool will grow indefinitely, and any cleanup will rely solely on the CleanupPolicy.
+type GrowthPolicy struct {
+	// MaxPoolSize defines the maximum number of objects the pool is allowed to grow to.
+	MaxPoolSize int64
+
+	// Enable activates growth control. If disabled, the pool will grow and shrink freely based on your configuration.
+	Enable bool
+}
+
+// DefaultConfig returns a default pool configuration for type T.
+func DefaultConfig[T any, P Poolable[T]](allocator Allocator[T], cleaner Cleaner[T]) Config[T, P] {
+	return Config[T, P]{
+		Cleanup:   DefaultCleanupPolicy(GcModerate),
+		Allocator: allocator,
+		Cleaner:   cleaner,
+	}
+}
+
+func validateConfig[T any, P Poolable[T]](cfg Config[T, P]) error {
+	if cfg.Allocator == nil {
+		return fmt.Errorf("%w: allocator is required", ErrNoAllocator)
+	}
+	if cfg.Cleaner == nil {
+		return fmt.Errorf("%w: cleaner is required", ErrNoCleaner)
+	}
+
+	return nil
+}
+
+func validateCleanupConfig[T any, P Poolable[T]](cfg Config[T, P]) error {
+	if cfg.Cleanup.Interval <= 0 {
+		return errors.New("cleanup interval must be greater than 0")
+	}
+	if cfg.Cleanup.MinUsageCount <= 0 {
+		return errors.New("minimum usage count must be greater than 0")
+	}
+	return nil
+}