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

Exponential Backoff: Connection creation uses exponential backoff with jitter
Priority Eviction: Four priority levels for connection cleanup:
- low: Routine maintenance
- medium: Connection acquisition failure
- high: Configuration changes
- urgent: Connection recovery events
Adaptive Cleanup: Maintenance thread dynamically adjusts processing frequency
Wait Queue: Fair connection allocation to waiting clients
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
}

4.3 KiB Raw Blame History