Getting Started

This guide will help you get started with using darwin-metrics in your Rust projects.

Installation

Add darwin-metrics to your Cargo.toml:

[dependencies]
darwin-metrics = "0.1.5"

Requirements

macOS El Capitan (10.11) or later
Rust 1.85 or later
Xcode Command Line Tools (for macOS system headers)

Basic Usage

Here's a simple example showing how to retrieve basic system metrics:

// Basic example of darwin-metrics usage
use darwin_metrics::{hardware, process};
use std::time::Duration;

fn main() -> darwin_metrics::Result<()> {
    // Get CPU information
    let cpu_info = hardware::cpu::Cpu::get_metrics()?;
    println!("CPU Usage: {}%", cpu_info.usage);

    // Get memory information
    let memory = hardware::memory::Memory::get_info()?;
    println!("Memory Used: {} bytes", memory.used);
    println!("Memory Available: {} bytes", memory.available);

    // Get process information
    let processes = process::Process::get_all().unwrap();
    println!("Running processes: {}", processes.len());

    Ok(())
}

Using Feature Flags

darwin-metrics is organized with feature flags to allow you to include only the modules you need:

[dependencies]
darwin-metrics = { version = "0.1.5", features = ["cpu", "memory"] }

Available features include:

cpu - CPU monitoring
memory - Memory statistics
gpu - GPU monitoring
process - Process information
thermal - Temperature sensors
power - Power and battery information

Async Support

For non-blocking operations, darwin-metrics provides async functionality:

// Async example with Tokio
use darwin_metrics::{hardware, process};
use std::time::Duration;
use futures::stream::StreamExt; // For the StreamExt trait

#[tokio::main]
async fn main() -> darwin_metrics::Result<()> {
    // Monitor process metrics over time
    let pid = std::process::id();
    let mut stream = process::Process::monitor_metrics(pid, Duration::from_secs(1));

    // Process the metrics stream
    while let Some(process) = stream.next().await {
        if let Ok(proc) = process {
            println!("Process: {} - CPU: {}%, Memory: {}",
                proc.name, proc.cpu_usage, proc.memory_usage);
        }
    }

    Ok(())
}

Error Handling

darwin-metrics provides a robust error handling system that helps you understand what went wrong:

// Error handling example
use darwin_metrics::{Error, Result};

// This is just a hypothetical function to demonstrate error handling
fn potentially_failing_function() -> Result<String> {
    Ok(String::from("success"))
}

fn example() -> Result<()> {
    let result = potentially_failing_function();

    match result {
        Ok(value) => println!("Success: {}", value),
        Err(Error::NotAvailable(msg)) => println!("Resource not available: {}", msg),
        Err(Error::System(msg)) => println!("System error: {}", msg),
        Err(Error::Process(msg)) => println!("Process error: {}", msg),
        Err(err) => println!("Other error: {}", err),
    }

    Ok(())
}

Next Steps

Explore the documentation for each module to learn more about available metrics and functionality: