Skip to content

Architecture

Jump to bottom
giganutt edited this page Jul 4, 2026 · 1 revision

Architecture and Design

System Overview

The Linux Swap Optimizer is a comprehensive system designed to reduce CPU and system load during AI development and general application usage on low-end systems. It achieves this through intelligent swap management, process prioritization across multiple categories, adaptive monitoring, and OS-level optimizations.

Core Components

1. SwapOptimizer Class

The main orchestrator that coordinates all optimization activities.

Responsibilities:

  • Configuration management
  • System monitoring
  • Swap parameter optimization
  • Process priority management across 5 categories
  • OS-level kernel optimization
  • Adaptive decision making

2. Swap Management Module

Handles all Linux kernel swap parameter modifications.

Key Parameters:

  • vm.swappiness - Controls kernel's tendency to swap
  • vm.vfs_cache_pressure - Balances cache vs memory reclaim
  • vm.page_cluster - Controls page clustering during swap
  • vm.min_free_kbytes - Ensures minimum free memory
  • vm.watermark_scale_factor - Improves watermark calculations
  • vm.dirty_ratio - Dirty page ratio for responsiveness
  • vm.dirty_background_ratio - Background dirty page handling
  • kernel.sched_min_granularity_ns - Scheduler granularity (kernel-dependent)
  • kernel.sched_wakeup_granularity_ns - Wakeup granularity (kernel-dependent)

Note: Some kernel parameters may not be available on all Linux distributions. The system gracefully handles unavailable parameters by logging them at debug level and continuing with available optimizations.

3. System Monitor

Continuously tracks system metrics for adaptive decisions.

Monitored Metrics:

  • CPU usage percentage
  • Memory usage percentage
  • System load averages (1, 5, 15 min)
  • Swap usage statistics
  • Process categories (AI, IDE, interactive, normal, background)

4. Process Manager

Identifies and prioritizes processes across 5 categories.

Process Categories:

  • AI processes (highest priority)
  • IDE processes (high priority)
  • Interactive applications (medium priority)
  • Normal processes (default priority)
  • Background processes (low priority)

Detection Methods:

  • Process name matching against configurable lists
  • Command line analysis
  • Real-time process tracking
  • Automatic categorization algorithm

Priority Settings:

  • CPU priority (nice values): -10 to +5
  • I/O priority (ionice classes): 1-3 with levels 0-7

Priority Adjustments:

  • Nice value adjustment (CPU priority)
  • I/O nice value adjustment (I/O priority)
  • Real-time scheduling for critical processes
  • Category-based priority tiers

5. Adaptive Controller

Makes dynamic decisions based on system state.

Decision Logic:

IF (optimize_all_apps enabled AND user processes detected):
    Maintain optimal swap settings
ELSE IF (AI/IDE processes detected):
    Maintain optimal swap settings
ELSE IF (CPU > threshold OR Memory > threshold):
    Increase swappiness to prevent OOM
ELSE:
    Decrease swappiness to reduce swap activity

Data Flow

┌─────────────────┐
│  Configuration  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ SwapOptimizer   │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
┌────────┐ ┌────────────┐
│ Monitor │ │ Process    │
│         │ │ Manager    │
└────┬────┘ └─────┬──────┘
     │             │
     └──────┬──────┘
            ▼
     ┌──────────────┐
     │ Adaptive     │
     │ Controller   │
     └──────┬───────┘
            │
            ▼
     ┌──────────────┐
     │ Swap Manager │
     └──────────────┘

Design Principles

1. Safety First

  • Original settings always backed up before modification
  • Conservative default values
  • Graceful degradation on errors
  • One-command rollback capability

2. AI-Aware

  • Specifically tuned for AI/IDE workloads
  • Process detection for common AI tools
  • Priority management for AI applications
  • Memory optimization for ML frameworks

3. Adaptive

  • Real-time monitoring
  • Dynamic parameter adjustment
  • Load-based decision making
  • Self-tuning behavior

4. Low-End Optimized

  • Minimal CPU overhead
  • Efficient memory usage
  • Fast I/O operations
  • Reduced system calls

Technical Details

Swap Parameter Optimization

vm.swappiness

  • Default: 10 (vs system default 60)
  • Purpose: Reduces aggressive swapping
  • Effect: Keeps more data in RAM, reduces disk I/O

vm.vfs_cache_pressure

  • Default: 75 (vs system default 100)
  • Purpose: Better cache retention
  • Effect: Improves file system performance

vm.page-cluster

  • Default: 0 (vs system default 3)
  • Purpose: Disables page clustering
  • Effect: Faster individual page swaps, less burst I/O

vm.min_free_kbytes

  • Default: 65536 (64MB)
  • Purpose: Ensures memory for critical operations
  • Effect: Prevents OOM situations

vm.watermark_scale_factor

  • Default: 200 (vs system default 10)
  • Purpose: Improves memory watermark calculations
  • Effect: Better memory pressure handling

Process Priority System

CPU Priority (nice)

  • Range: -20 (highest) to 19 (lowest)
  • AI Processes: Set to -5 (elevated priority)
  • Effect: Better CPU time allocation

I/O Priority (ionice)

  • Classes: 1 (realtime), 2 (best-effort), 3 (idle)
  • AI Processes: Class 1, level 4
  • Effect: Reduced I/O latency

Adaptive Algorithm

while monitoring:
    load = get_system_load()
    
    if load.cpu > cpu_threshold or load.memory > memory_threshold:
        current = read_sysctl('vm.swappiness')
        if current < 30:
            new = min(current + 10, 30)
            write_sysctl('vm.swappiness', new)
    else:
        current = read_sysctl('vm.swappiness')
        if current > config.swappiness:
            new = max(current - 5, config.swappiness)
            write_sysctl('vm.swappiness', new)
    
    set_process_priorities()
    sleep(check_interval)

Performance Characteristics

CPU Overhead

  • Monitoring: < 1% CPU
  • Optimization: < 0.5% CPU
  • Total: < 2% CPU overhead

Memory Usage

  • Base: ~20MB RSS
  • Per process: ~1KB
  • Total: < 50MB typical

I/O Impact

  • Read: Minimal (config files)
  • Write: Periodic sysctl updates
  • Network: None

Security Considerations

Privilege Requirements

  • Root access: Required for sysctl modifications
  • Process priority: Requires appropriate permissions
  • Service: Runs as root user

Security Measures

  • No network connections
  • No external dependencies beyond psutil
  • Configuration file validation
  • Safe parameter ranges enforced

Extensibility

Adding New Process Types

Edit ai_processes in config.json:

"ai_processes": [
  "python", "node", "code", "cursor",
  "your_new_process"
]

Custom Monitoring Metrics

Extend _get_system_load() method:

def _get_system_load(self) -> Dict[str, float]:
    # Add custom metrics here
    custom_metric = get_custom_metric()
    return {
        'cpu_percent': cpu_percent,
        'custom_metric': custom_metric
    }

Additional Swap Parameters

Add to _save_original_settings() and optimize_swap_settings():

self._write_sysctl('vm.new_parameter', value)

Limitations

  1. Linux Only: Designed specifically for Linux kernel
  2. Root Required: Cannot run without root privileges
  3. Kernel Version: Requires kernel 3.10+
  4. Process Detection: Limited to name-based matching
  5. Swap Device: Does not manage swap device creation

Future Enhancements

Planned Features

  • Machine learning-based prediction
  • Per-process memory cgroups
  • Swap device management
  • GPU memory optimization
  • Network-aware swap (for distributed systems)

Research Areas

  • AI workload pattern recognition
  • Predictive pre-fetching
  • Dynamic swap partition sizing
  • Cross-node swap coordination

Last Updated: 2026-07-03 Version: 2.0.0

Clone this wiki locally