Object Pool Pattern — Recycling Resources for Performance

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// BROKEN: Race condition in unsynchronized pool
class UnsafePool<T> {
    private available: T[] = [];
    
    acquire(): T | null {
        // Thread A: checks length = 1, proceeds
        // Thread B: checks length = 1, proceeds (same time!)
        if (this.available.length > 0) {
            // Thread A: pops the object
            // Thread B: pops... UNDEFINED! Array is now empty
            return this.available.pop()!;
        }
        return null;
    }
}
 
// Timeline of disaster:
// T=0: available = [obj1]
// T=1: Thread A calls acquire(), sees length=1
// T=1: Thread B calls acquire(), sees length=1
// T=2: Thread A calls pop(), gets obj1, available = []
// T=2: Thread B calls pop(), gets undefined!
// Result: Thread B has an undefined object, will crash later

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

import { Mutex } from 'async-mutex';
 
class ThreadSafePool<T extends Poolable> {
    private available: T[] = [];
    private inUse: Set<T> = new Set();
    private mutex = new Mutex();
 
    async acquire(): Promise<T> {
        // Only one thread can execute this block at a time
        const release = await this.mutex.acquire();
        
        try {
            while (this.available.length > 0) {
                const obj = this.available.pop()!;
                
                if (obj.validate()) {
                    this.inUse.add(obj);
                    return obj;
                } else {
                    await this.destroyObject(obj);
                }
            }
            
            // Create new if under max size
            if (this.inUse.size < this.maxSize) {
                const newObj = await this.factory();
                this.inUse.add(newObj);
                return newObj;
            }
            
            throw new Error('Pool exhausted');
        } finally {
            release();
        }
    }
 
    async release(obj: T): Promise<void> {
        const release = await this.mutex.acquire();
        
        try {
            if (!this.inUse.has(obj)) {
                throw new Error('Object not from this pool');
            }
            
            this.inUse.delete(obj);
            await obj.reset();
            this.available.push(obj);
        } finally {
            release();
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

// Conceptual: Lock-free pool using compare-and-swap (CAS)
// Note: JavaScript doesn't have true CAS; this illustrates the concept
 
class LockFreePool<T> {
    // Atomic reference to head of available stack
    private availableHead: AtomicReference<PoolNode<T> | null>;
    // Atomic counter for in-use tracking
    private inUseCount: AtomicInteger = new AtomicInteger(0);
    
    acquire(): T | null {
        while (true) {
            // Read current head
            const head = this.availableHead.get();
            
            if (head === null) {
                // Pool empty, need to create or fail
                return this.tryCreateNew();
            }
            
            // Attempt to CAS head to next node
            // This succeeds only if no other thread modified head
            if (this.availableHead.compareAndSet(head, head.next)) {
                // Success! We own this node's object
                this.inUseCount.incrementAndGet();
                return head.object;
            }
            
            // CAS failed, another thread got there first
            // Loop and retry with new head
        }
    }
    
    release(obj: T): void {
        const node = new PoolNode(obj);
        
        while (true) {
            const head = this.availableHead.get();
            node.next = head;
            
            if (this.availableHead.compareAndSet(head, node)) {
                this.inUseCount.decrementAndGet();
                return; // Success
            }
            // CAS failed, retry
        }
    }
}
 
// Lock-free is complex but eliminates lock contention
// Use only when profiling shows lock contention is a bottleneck

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

// Thread-local pools: each thread has its own mini-pool
class ThreadLocalPool<T extends Poolable> {
    // Each thread gets its own local pool
    private threadLocal: ThreadLocal<LocalPool<T>>;
    private globalPool: GlobalPool<T>;
    private localPoolSize: number;
    
    constructor(config: PoolConfig<T>) {
        this.globalPool = new GlobalPool(config);
        this.localPoolSize = config.localPoolSize ?? 2;
        
        this.threadLocal = new ThreadLocal(() => 
            new LocalPool<T>(this.localPoolSize)
        );
    }
    
    acquire(): T {
        const localPool = this.threadLocal.get();
        
        // Try local pool first (no contention!)
        const local = localPool.tryAcquire();
        if (local !== null) {
            return local;
        }
        
        // Local empty, get from global pool
        // This is the only point of contention
        const global = this.globalPool.acquire();
        return global;
    }
    
    release(obj: T): void {
        const localPool = this.threadLocal.get();
        
        // Try to return to local pool first
        if (localPool.tryRelease(obj)) {
            return; // No contention!
        }
        
        // Local pool full, return to global
        this.globalPool.release(obj);
    }
}
 
// Thread-local pools dramatically reduce contention:
// - 95% of acquires hit the local pool (zero contention)
// - Only overflow/underflow touches the global pool
// - Global pool uses coarse-grained locking (rarely contended)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

async acquire(): Promise<T> {
    while (this.available.length > 0) {
        const obj = this.available.pop()!;
        
        // Validate before returning
        if (await this.config.validate(obj)) {
            this.inUse.add(obj);
            return obj;
        }
        
        // Object is stale — destroy and try next
        console.log('Discarding stale pooled object');
        await this.config.destroy(obj);
    }
    
    // No valid objects available, create new
    return this.createNew();
}
 
// Validation implementation for database connection
function validateConnection(conn: DatabaseConnection): boolean {
    // Quick check: is the socket still connected?
    if (!conn.isConnected()) {
        return false;
    }
    
    // Deeper check: can we actually communicate?
    try {
        conn.query('SELECT 1'); // Lightweight ping
        return true;
    } catch {
        return false;
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65

class PoolWithEvictor<T extends Poolable> {
    private evictorInterval: NodeJS.Timer | null = null;
    private evictionIntervalMs: number = 30000; // Every 30 seconds
    private timeBetweenEvictionRunsMs: number = 500; // Pause between checks
    private numTestsPerEvictionRun: number = 3; // Check 3 objects per run
 
    startEvictor(): void {
        this.evictorInterval = setInterval(
            () => this.runEviction(),
            this.evictionIntervalMs
        );
    }
 
    private async runEviction(): Promise<void> {
        const objectsToTest = Math.min(
            this.numTestsPerEvictionRun,
            this.available.length
        );
        
        for (let i = 0; i < objectsToTest; i++) {
            // Get an object from the pool (don't mark as in-use)
            const obj = this.available.shift();
            if (!obj) break;
            
            // Test it
            const isValid = await this.validateWithTimeout(obj, 5000);
            
            if (isValid) {
                // Still good, put it back (at the end, for LRU behavior)
                this.available.push(obj);
            } else {
                // Stale, destroy it
                console.log('Evictor: removing stale object');
                await this.config.destroy(obj);
                
                // Optionally: create replacement to maintain min size
                if (this.getSize() < this.config.minSize) {
                    await this.createAndAddObject();
                }
            }
            
            // Brief pause between tests to avoid overwhelming resources
            await this.sleep(this.timeBetweenEvictionRunsMs);
        }
    }
 
    private async validateWithTimeout(
        obj: T, 
        timeoutMs: number
    ): Promise<boolean> {
        return new Promise((resolve) => {
            const timeout = setTimeout(() => resolve(false), timeoutMs);
            
            this.config.validate(obj)
                .then((result) => {
                    clearTimeout(timeout);
                    resolve(result);
                })
                .catch(() => {
                    clearTimeout(timeout);
                    resolve(false);
                });
        });
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

class KeepalivePool<T extends Poolable> {
    private keepaliveIntervalMs: number = 60000; // Every minute
    private keepaliveInterval: NodeJS.Timer | null = null;
 
    startKeepalive(): void {
        this.keepaliveInterval = setInterval(
            () => this.sendKeepalives(),
            this.keepaliveIntervalMs
        );
    }
 
    private async sendKeepalives(): Promise<void> {
        // Keep connections warm by using them
        for (const obj of this.available) {
            try {
                // Send a minimal operation to prevent timeout
                await this.config.keepalive(obj);
            } catch {
                // Keepalive failed — mark for eviction on next validation
                obj.markPotentiallyStale();
            }
        }
    }
}
 
// Example keepalive implementations:
const keepaliveStrategies = {
    database: (conn) => conn.query('SELECT 1'),
    http: (client) => client.head('/health'),
    redis: (client) => client.ping(),
    socket: (socket) => socket.write(Buffer.from([0])), // TCP keepalive
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

interface PooledItem<T> {
    object: T;
    lastUsedAt: Date;
    createdAt: Date;
}
 
class IdleTimeoutPolicy<T> {
    private idleTimeoutMs: number = 300000; // 5 minutes default
    private minIdle: number = 2;  // Keep at least 2 even if idle
 
    shouldEvict(item: PooledItem<T>, currentSize: number): boolean {
        // Never evict below minimum
        if (currentSize <= this.minIdle) {
            return false;
        }
        
        const idleMs = Date.now() - item.lastUsedAt.getTime();
        return idleMs > this.idleTimeoutMs;
    }
}
 
// Usage in maintenance loop
private performMaintenance(): void {
    const toEvict: PooledItem<T>[] = [];
    
    for (const item of this.available) {
        if (this.evictionPolicy.shouldEvict(item, this.getSize())) {
            toEvict.push(item);
        }
    }
    
    for (const item of toEvict) {
        this.removeFromAvailable(item);
        this.config.destroy(item.object);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

class MaxLifetimePolicy<T> {
    private maxLifetimeMs: number = 3600000; // 1 hour default
 
    shouldEvict(item: PooledItem<T>): boolean {
        const ageMs = Date.now() - item.createdAt.getTime();
        return ageMs > this.maxLifetimeMs;
    }
}
 
// Why max lifetime?
// 1. Prevents credential/token leakage over time
// 2. Ensures fresh connections pick up server config changes
// 3. Releases resources that may have accumulated state
// 4. Spreads out reconnection cost (avoids thundering herd)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

class LRUPool<T extends Poolable> {
    private available: LinkedList<PooledItem<T>> = new LinkedList();
    private maxSize: number;
    private softMaxSize: number; // Trigger eviction above this
 
    release(obj: T): void {
        const item = this.inUse.get(obj);
        this.inUse.delete(obj);
        obj.reset();
        
        // Add to head (most recently used)
        this.available.addFirst(item);
        
        // Evict from tail if over soft max
        while (this.available.size > this.softMaxSize) {
            const lru = this.available.removeLast();
            this.config.destroy(lru.object);
        }
    }
 
    acquire(): T {
        if (this.available.size > 0) {
            // Take from head (most recently used = warmest)
            const item = this.available.removeFirst();
            this.inUse.set(item.object, item);
            return item.object;
        }
        // ...create new or wait
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

class FIFOPool<T extends Poolable> {
    private available: Queue<PooledItem<T>> = new Queue();
 
    acquire(): T | null {
        // Take from front (oldest = first in)
        const item = this.available.dequeue();
        if (item) {
            this.inUse.set(item.object, item);
            return item.object;
        }
        return null;
    }
 
    release(obj: T): void {
        const item = this.inUse.get(obj);
        this.inUse.delete(obj);
        obj.reset();
        
        // Add to back (will be used after older objects)
        this.available.enqueue(item);
    }
}
 
// FIFO ensures:
// 1. All objects get used roughly equally
// 2. No objects sit idle forever while others are used constantly
// 3. Age-based eviction works more predictably
// 4. Resource utilization is balanced

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

interface PoolSizingConfig {
    requestsPerSecond: number;
    averageUsageDurationMs: number;
    peakMultiplier: number;       // Typically 1.5-2.0
    minimumIdleFraction: number;  // Typically 0.25-0.5
}
 
function calculatePoolSize(config: PoolSizingConfig): {
    minSize: number;
    maxSize: number;
    initialSize: number;
} {
    const {
        requestsPerSecond,
        averageUsageDurationMs,
        peakMultiplier,
        minimumIdleFraction,
    } = config;
    
    // Average concurrent usage (Little's Law)
    const averageConcurrent = 
        requestsPerSecond * (averageUsageDurationMs / 1000);
    
    // Max size handles peak load
    const maxSize = Math.ceil(averageConcurrent * peakMultiplier);
    
    // Min size prevents cold starts during normal operation
    const minSize = Math.ceil(averageConcurrent * minimumIdleFraction);
    
    // Initial size balances startup time vs. wasted resources
    const initialSize = Math.ceil((minSize + maxSize) / 2);
    
    return { minSize, maxSize, initialSize };
}
 
// Example: API server calling a database
const sizing = calculatePoolSize({
    requestsPerSecond: 500,
    averageUsageDurationMs: 20,
    peakMultiplier: 2.0,
    minimumIdleFraction: 0.5,
});
 
console.log(sizing);
// { minSize: 5, maxSize: 20, initialSize: 13 }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

interface InfrastructureConstraints {
    databaseMaxConnections: number;
    applicationServerCount: number;
    reservedConnections: number;  // For admin, monitoring, etc.
}
 
function calculateMaxPoolSize(
    constraints: InfrastructureConstraints
): number {
    const availableConnections = 
        constraints.databaseMaxConnections - 
        constraints.reservedConnections;
    
    return Math.floor(
        availableConnections / constraints.applicationServerCount
    );
}
 
// Example
const maxPerServer = calculateMaxPoolSize({
    databaseMaxConnections: 100,
    applicationServerCount: 8,
    reservedConnections: 4,  // For monitoring dashboards, migrations
});
 
console.log(`Max pool size per server: ${maxPerServer}`);
// Max pool size per server: 12

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

interface PoolMetrics {
    // Gauge metrics (current state)
    totalSize: number;
    activeCount: number;
    idleCount: number;
    waitingCount: number;
    
    // Counter metrics (cumulative)
    acquireCount: number;
    releaseCount: number;
    createCount: number;
    destroyCount: number;
    timeoutCount: number;
    validationFailureCount: number;
    
    // Histogram/timing metrics
    acquireTimeMs: {
        min: number;
        max: number;
        mean: number;
        p50: number;
        p95: number;
        p99: number;
    };
    usageTimeMs: {  // Time objects are borrowed
        min: number;
        max: number;
        mean: number;
        p50: number;
        p95: number;
        p99: number;
    };
}
 
class InstrumentedPool<T extends Poolable> {
    private metrics: PoolMetrics;
    private acquireHistogram: Histogram;
    private usageHistogram: Histogram;
 
    async acquire(): Promise<T> {
        const startTime = performance.now();
        this.metrics.waitingCount++;
        
        try {
            const obj = await this.doAcquire();
            
            const acquireTime = performance.now() - startTime;
            this.acquireHistogram.record(acquireTime);
            this.metrics.acquireCount++;
            this.metrics.activeCount++;
            this.metrics.idleCount--;
            
            return obj;
        } catch (error) {
            if (error.message.includes('timeout')) {
                this.metrics.timeoutCount++;
            }
            throw error;
        } finally {
            this.metrics.waitingCount--;
        }
    }
 
    release(obj: T): void {
        const item = this.inUse.get(obj);
        if (item) {
            const usageTime = Date.now() - item.borrowedAt.getTime();
            this.usageHistogram.record(usageTime);
        }
        
        this.metrics.releaseCount++;
        this.metrics.activeCount--;
        this.metrics.idleCount++;
        
        this.doRelease(obj);
    }
 
    getMetrics(): PoolMetrics {
        return {
            ...this.metrics,
            acquireTimeMs: this.acquireHistogram.getSnapshot(),
            usageTimeMs: this.usageHistogram.getSnapshot(),
        };
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

import { Gauge, Counter, Histogram, Registry } from 'prom-client';
 
class PrometheusPoolMetrics<T> {
    private registry: Registry;
    
    private totalSize: Gauge;
    private activeCount: Gauge;
    private idleCount: Gauge;
    private waitingCount: Gauge;
    
    private acquireTotal: Counter;
    private timeoutTotal: Counter;
    private createTotal: Counter;
    private destroyTotal: Counter;
    
    private acquireDuration: Histogram;
    private usageDuration: Histogram;
 
    constructor(poolName: string) {
        this.registry = new Registry();
        
        const labelNames = ['pool'];
        const labels = { pool: poolName };
 
        this.totalSize = new Gauge({
            name: 'object_pool_size_total',
            help: 'Total number of objects in the pool',
            labelNames,
        });
 
        this.activeCount = new Gauge({
            name: 'object_pool_active_count',
            help: 'Number of objects currently borrowed',
            labelNames,
        });
 
        this.acquireDuration = new Histogram({
            name: 'object_pool_acquire_duration_seconds',
            help: 'Time to acquire an object from the pool',
            labelNames,
            buckets: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5],
        });
        
        // ... additional metrics
    }
 
    recordAcquire(durationMs: number): void {
        this.acquireTotal.inc();
        this.acquireDuration.observe(durationMs / 1000);
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

class FairPool<T extends Poolable> {
    private waitQueue: Array<{
        resolve: (obj: T) => void;
        reject: (error: Error) => void;
        requestedAt: Date;
        timeoutId: NodeJS.Timeout;
    }> = [];
 
    release(obj: T): void {
        this.inUse.delete(obj);
        obj.reset();
 
        // FIFO: serve the waiter who has waited longest
        if (this.waitQueue.length > 0) {
            const waiter = this.waitQueue.shift()!;  // First in = first out
            clearTimeout(waiter.timeoutId);
            this.inUse.add(obj);
            waiter.resolve(obj);
            return;
        }
 
        this.available.push(obj);
    }
 
    // Clients join the queue in order, served in same order
    private waitForObject(timeoutMs: number): Promise<T> {
        return new Promise((resolve, reject) => {
            const waiter = {
                resolve,
                reject,
                requestedAt: new Date(),
                timeoutId: setTimeout(() => {
                    this.removeFromWaitQueue(waiter);
                    reject(new Error('Pool timeout'));
                }, timeoutMs),
            };
            
            // Add to END of queue (FIFO)
            this.waitQueue.push(waiter);
        });
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

enum AcquisitionPriority {
    CRITICAL = 0,   // Health checks, system operations
    HIGH = 1,       // User-facing requests
    NORMAL = 2,     // Background processing
    LOW = 3,        // Batch jobs, analytics
}
 
class PriorityPool<T extends Poolable> {
    // Separate queues per priority
    private waitQueues: Map<AcquisitionPriority, Waiter[]> = new Map([
        [AcquisitionPriority.CRITICAL, []],
        [AcquisitionPriority.HIGH, []],
        [AcquisitionPriority.NORMAL, []],
        [AcquisitionPriority.LOW, []],
    ]);
 
    acquire(priority: AcquisitionPriority = AcquisitionPriority.NORMAL): Promise<T> {
        const available = this.tryGetAvailable();
        if (available) {
            return Promise.resolve(available);
        }
        
        return this.waitForObject(priority);
    }
 
    release(obj: T): void {
        this.inUse.delete(obj);
        obj.reset();
 
        // Serve highest priority waiter first
        for (const priority of [
            AcquisitionPriority.CRITICAL,
            AcquisitionPriority.HIGH,
            AcquisitionPriority.NORMAL,
            AcquisitionPriority.LOW,
        ]) {
            const queue = this.waitQueues.get(priority)!;
            if (queue.length > 0) {
                const waiter = queue.shift()!;
                waiter.resolve(obj);
                return;
            }
        }
 
        this.available.push(obj);
    }
}
 
// Usage
const connection = await pool.acquire(AcquisitionPriority.CRITICAL);