Kacho.ASyncObjectPool 1.1.2

AsyncObjectPool

A high-performance, async-friendly object pool for .NET, designed to efficiently manage reusable objects with dynamic scaling based on usage patterns.

Overview

AsyncObjectPool<T> provides a thread-safe, asynchronous object pool that supports dynamic growth and shrinking based on demand. It uses a Channel<T> for object storage and retrieval, with configurable policies for pool size, timeouts, and disposal. The pool is ideal for scenarios requiring expensive resource initialization, such as database connections, HTTP clients, or other heavy objects.

Features

• Asynchronous Operations: Supports async object creation, renting, and returning.
• Dynamic Scaling: Automatically grows or shrinks the pool based on demand, using configurable growth and shrink thresholds.
• Timeout Policies: Customizable behavior for handling timeouts (e.g., wait, create new, or trigger monitoring).
• Metrics: Provides real-time insights into pool usage, including active rentals, idle objects, and timeouts.
• Exponential Moving Averages (EMA): Tracks rental times and idle ratios for adaptive pool management.
• Disposable Support: Handles both IDisposable and IAsyncDisposable objects for proper resource cleanup.

Installation

Install via NuGet:

dotnet add package Kacho.AsyncObjectPool

Usage

Basic Example

using Kacho.AsyncObjectPool;
using System.Threading.Channels;

async Task Main()
{
    // Create a pool for strings with an async generator
    var pool = new AsyncObjectPool<string>(
        objectGenerator: async () =>
        {
            await Task.Delay(100); // Simulate expensive creation
            return "PooledObject";
        },
        options: new AsyncObjectPoolOptions
        {
            InitialPoolSize = 5,
            MinPoolSize = 2,
            MaxPoolSize = 10,
            TimeoutBehavior = TimeoutBehavior.CreateNewImmediately
        });

    // Initialize the pool
    await pool.InitializeAsync();

    // Use an object from the pool
    await pool.UseAsync(async obj =>
    {
        Console.WriteLine($"Using object: {obj}");
        await Task.Delay(50);
    });

    // Use with return value
    string result = await pool.UseAsync(async obj =>
    {
        await Task.Delay(50);
        return obj + "-Processed";
    });

    Console.WriteLine($"Result: {result}");

    // Check pool metrics
    var metrics = pool.Metrics;
    Console.WriteLine($"Current Pool Size: {metrics.CurrentSize}, Active Rentals: {metrics.ActiveRentals}");
}

Configuration Options

The AsyncObjectPoolOptions class allows customization of pool behavior:

• InitialPoolSize: Number of objects to create on initialization (default: 10).
• MinPoolSize: Minimum number of objects in the pool (default: 5).
• MaxPoolSize: Maximum number of objects in the pool (default: 100).
• GrowthFactor: Factor for pool growth when timeouts occur (default: 0.5).
• MaxShrinkSize: Maximum number of objects to remove in one shrink cycle (default: int.MinValue).
• MaxGrowthSize: Maximum number of objects to add in one growth cycle (default: int.MaxValue).
• ShrinkIdleThreshold: Idle ratio threshold for shrinking the pool (default: 0.2).
• EmaRentTimeAlpha: Smoothing factor for rental time EMA (default: 0.1).
• EmaIdleRatioAlpha: Smoothing factor for idle ratio EMA (default: 0.5).
• MonitoringLoopDelayMs: Delay between monitoring cycles in milliseconds (default: 2000).
• TimeoutBehavior: Behavior when no objects are available within the timeout period (default: CreateNewImmediately).

Timeout Behaviors

The TimeoutBehavior enum defines how the pool handles cases when no objects are available within the specified timeout:

• WaitForAvailable: Waits until an object becomes available.
• CreateNewImmediately: Creates a new object immediately.
• TriggerMonitoringWaitForAvailable: Signals the monitoring loop and waits for an object.
• TriggerMonitoringCreateNewImmediately: Signals the monitoring loop and creates a new object.

Metrics

The Metrics property provides insights into pool performance:

• CurrentSize: Total objects in the pool (active + idle).
• ActiveRentals: Number of objects currently in use.
• IdleCount: Number of objects available in the pool.
• CurrentTimeouts: Number of timeouts since the last monitoring cycle.
• ActiveRatio: Ratio of active rentals to total pool size.
• IdleRatio: Ratio of idle objects to total pool size.
• EmaRentTimeTicks: EMA of rental durations in ticks.

Notes

• The pool uses Channel<T> for efficient, thread-safe object management.
• Objects must implement IDisposable or IAsyncDisposable for proper cleanup.
• The pool dynamically adjusts its size based on usage patterns, using EMA to smooth out fluctuations.
• Ensure the objectGenerator function is thread-safe and handles exceptions appropriately.

License

MIT License