Resource Limits Quick Start Guide

5-Minute Integration

1. Basic Setup

use heliosdb_common::{
    ResourceLimitsConfig, ResourceLimitsManager,
    QueryLimits, FdTracker,
};

// Create unified manager
let manager = ResourceLimitsManager::new(
    ResourceLimitsConfig::production()
);

2. Query Execution with Limits

// Begin tracking a query
let guard = manager.query_limits.begin_query("username").await?;

// Execute query with automatic resource tracking
for row in execute_query(sql) {
    // Check limits periodically
    guard.check_timeout()?;
    guard.update_memory(current_memory)?;
    guard.update_rows_processed(row_count)?;

    // Process row...
}

// Guard automatically releases on drop

3. File Descriptor Tracking

use heliosdb_common::{FdGuard, FdId, FdInfo, FdType};

// Track file descriptor with RAII
let guard = FdGuard::new(
    &manager.fd_tracker,
    FdId::new("file-1"),
    FdInfo::new(FdType::DatabaseFile, "storage")
        .with_path("/data/db/file.db")
)?;

// Use file...
// Guard drops, FD automatically unregistered

4. Health Monitoring

// Check system health
let health = manager.health_check().await;
if !health.is_healthy {
    warn!("System degraded: {}", health.summary());
}

// Check if should apply backpressure
if manager.should_apply_backpressure() {
    // Slow down request processing
    tokio::time::sleep(Duration::from_millis(100)).await;
}

// Check if should reject requests
if manager.should_reject_requests() {
    return Err(HeliosError::ResourceExhausted(
        "System overloaded".into()
    ));
}

Common Configurations

Production (Default)

let config = ResourceLimitsConfig::production();
// - 60s query timeout
// - 1GB memory per query
// - 1M result rows max
// - 100 concurrent queries
// - 10k file descriptors

High Load (Analytical)

let config = ResourceLimitsConfig::high_load();
// - 10min query timeout
// - 10GB memory per query
// - 100M result rows max
// - 10 concurrent queries
// - 65k file descriptors

Constrained (Edge/IoT)

let config = ResourceLimitsConfig::constrained();
// - 5s query timeout
// - 100MB memory per query
// - 10k result rows max
// - 200 concurrent queries
// - 2.5k file descriptors

Quick Troubleshooting

Query Timeouts

// Check query stats
let stats = manager.query_limits.stats();
if stats.queries_timeout > threshold {
    // Queries timing out - increase limits or optimize queries
}

FD Exhaustion

// Check FD usage
if manager.fd_tracker.is_soft_limit_exceeded() {
    let stale = manager.fd_tracker.get_stale_fds();
    warn!("High FD usage, {} stale FDs", stale.len());

    // Cleanup stale FDs
    manager.fd_tracker.cleanup_stale_fds();
}

Memory Pressure

let snapshot = manager.get_usage_snapshot().await;
if snapshot.memory_usage > 0.9 {
    // Critical memory pressure
    // - Reduce cache sizes
    // - Kill long-running queries
    // - Reject new queries
}

Best Practices

Always use RAII guards - Never manually manage resources
Configure timeouts appropriately - Different for dev/prod
Monitor resource usage - Set up periodic health checks
Implement graceful degradation - Use backpressure signals
Test under load - Verify limits work as expected

More Information

Full documentation: docs/resource-leak-prevention.md
Example code: examples/resource_leak_prevention.rs
Implementation report: RESOURCE_LEAK_PREVENTION_IMPLEMENTATION_REPORT.md