Connection Pool Module

This module provides a robust connection pooling implementation for managing reusable resources like database connections. It handles connection lifecycle, validation, and efficient resource allocation with minimal overhead.

Features

• Connection Reuse: Efficiently manages reusable connections
• Health Validation: Automatic connection validation
• Dynamic Scaling: Adjusts pool size based on demand
• Intelligent Eviction: Removes stale connections with priority-based cleanup
• Statistics Tracking: Provides detailed pool metrics
• Thread Safety: Fully concurrent-safe implementation
• Graceful Shutdown: Clean resource termination
• Dynamic Configuration: Runtime configuration updates

Basic Usage

Creating a Pool

import db.mysql
import pool
import time

// Define your connection factory function
fn create_conn() !&pool.ConnectionPoolable {
    config := mysql.Config{
        host:     '127.0.0.1'
        port:     3306
        username: 'root'
        password: '12345678'
        dbname:   'mysql'
    }
    db := mysql.connect(config)!
    return &db
}

// Configure pool parameters
config := pool.ConnectionPoolConfig{
    max_conns:      50
    min_idle_conns: 5
    max_lifetime:   2 * time.hour
    idle_timeout:   30 * time.minute
    get_timeout:    5 * time.second
}

// Create connection pool
mut my_pool := pool.new_connection_pool(create_conn, config)!

// Acquire connection
mut conn := my_pool.get()!

// Convert `conn` to a `mysql.DB` object
mut db := conn as mysql.DB

// Use connection `db`
// ... your operations ...
// db.exec()

// Return connection to pool
my_pool.put(conn)!

// When application exits
my_pool.close()

Configuration Options

| Parameter | Default Value | Description | |---------------------|-----------------------|--------------------------------------| | max_conns | 20 | Maximum connections in pool | | min_idle_conns | 5 | Minimum idle connections to maintain | | max_lifetime | 1 hour | Max connection lifetime | | idle_timeout | 30 minutes | Idle connection timeout | | get_timeout | 5 seconds | Connection acquisition timeout | | retry_base_delay | 1 second | Base delay for connection retries | | max_retry_delay | 30 seconds | Maximum retry delay | | max_retry_attempts| 5 | Maximum connection creation attempts |

Advanced Features

Dynamic Configuration Update

new_config := pool.ConnectionPoolConfig{
    max_conns: 100
    min_idle_conns: 10
    // ... other parameters ...
}

my_pool.update_config(new_config)!

Connection Recovery Signal

// After connection maintenance/outage
my_pool.signal_recovery_event()

Statistics Monitoring

stats := my_pool.stats()
println("Active connections: ${stats.active_conns}")
println("Idle connections: ${stats.idle_conns}")
println("Waiting clients: ${stats.waiting_clients}")

Implementation Notes

1. Exponential Backoff: Connection creation uses exponential backoff with jitter
2. Priority Eviction: Four priority levels for connection cleanup:
   • low: Routine maintenance
   • medium: Connection acquisition failure
   • high: Configuration changes
   • urgent: Connection recovery events
3. Adaptive Cleanup: Maintenance thread dynamically adjusts processing frequency
4. Wait Queue: Fair connection allocation to waiting clients
5. Atomic Operations: Non-blocking statistics tracking

Performance Considerations

• Use appropriate min_idle_conns to balance startup time and memory
• Set max_lifetime according to your backend connection limits
• Monitor creation_errors statistic to detect connection issues
• Use evicted_count to identify connection health problems

Example Implementation

// ConnectionPoolable connection interface implementation
struct MyConnection {
    // Your connection state
}

fn (mut c MyConnection) validate() !bool {
    // Connection health check logic
    return true
}

fn (mut c MyConnection) close() ! {
    // Physical close logic
}

fn (mut c MyConnection) reset() ! {
    // Reset connection to initial state
}