system-profile 0.1.1

# System Profile

[![Crates.io](https://img.shields.io/crates/v/system-profile.svg)](https://crates.io/crates/system-profile)
[![Documentation](https://docs.rs/system-profile/badge.svg)](https://docs.rs/system-profile)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Cached system profile information for runtime optimization decisions.

## Overview

System Profile provides a lazily-initialized, cached view of system resources that applications can use to make intelligent runtime optimization decisions. Information is gathered once at first access and cached for the lifetime of the application.

## Features

- 🚀 **Lazy Initialization** - System profiling only happens on first access
- 💾 **Cached Results** - Profile information is computed once and reused
- 🔧 **Zero Runtime Overhead** - No repeated system calls after initialization
- 🎯 **Targeted Information** - Only gathers what's needed for optimization decisions
- 🌐 **Cross-Platform** - Works on Linux, macOS, and Windows

## Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
system-profile = "0.1.0"
```

## Usage

```rust
use system_profile::SystemProfile;

// Get cached system profile (initialized on first call)
let profile = SystemProfile::global();

// Use profile information for runtime decisions
let worker_count = if profile.cpu_count() > 8 {
    8 // Cap at 8 workers for large systems
} else {
    profile.cpu_count()
};

// Check available memory for workload sizing
let available_memory = profile.available_memory_mb();
if available_memory < 1000 {
    println!("Warning: Low memory available");
}

// Make optimization decisions based on system capabilities
let batch_size = match (profile.cpu_count(), available_memory) {
    (cpu, mem) if cpu >= 8 && mem >= 8000 => 1000,  // High-end system
    (cpu, mem) if cpu >= 4 && mem >= 4000 => 500,   // Mid-range system
    _ => 100,                                         // Conservative default
};
```

## API

### Core Methods

- `SystemProfile::global()` - Get the global cached system profile
- `cpu_count()` - Number of logical CPU cores
- `total_memory_mb()` - Total system memory in megabytes
- `available_memory_mb()` - Available system memory in megabytes
- `is_low_memory()` - Returns true if available memory is below threshold

### Advanced Features

Optional GPU detection (requires `gpu` feature):

```toml
[dependencies]
system-profile = { version = "0.1.0", features = ["gpu"] }
```

## Use Cases

### Parallel Processing Optimization

```rust
use system_profile::SystemProfile;

let profile = SystemProfile::global();
let optimal_workers = profile.cpu_count().min(8);

// Use optimal worker count for parallel processing
rayon::ThreadPoolBuilder::new()
    .num_threads(optimal_workers)
    .build_global()
    .unwrap();
```

### Memory-Aware Caching

```rust
use system_profile::SystemProfile;

let profile = SystemProfile::global();
let cache_size = if profile.available_memory_mb() > 4000 {
    1000 // Large cache for systems with plenty of memory
} else {
    100  // Conservative cache for memory-constrained systems
};
```

### Adaptive Batch Processing

```rust
use system_profile::SystemProfile;

fn determine_batch_size() -> usize {
    let profile = SystemProfile::global();

    match profile.cpu_count() {
        n if n >= 16 => 1000,  // High-performance server
        n if n >= 8 => 500,    // Desktop/workstation
        n if n >= 4 => 250,    // Laptop
        _ => 100,              // Single/dual-core system
    }
}
```

## Performance

- **Initialization**: ~1-5ms (one-time cost)
- **Subsequent Access**: ~1ns (cached value lookup)
- **Memory Overhead**: <1KB per profile instance
- **Thread Safety**: Uses `std::sync::LazyLock` for safe concurrent access

## License

MIT License - see [LICENSE](../../LICENSE) for details.

## Contributing

Contributions welcome! Please see [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.

## Support

- 📚 [Documentation](https://docs.rs/system-profile)
- 🐛 [Issues](https://gitlab.com/deepbrain.space/guardy/-/issues)
- 💬 [Discussions](https://gitlab.com/deepbrain.space/guardy/-/issues)