cpu_load 0.1.2

# cpu_load : 实时 CPU 监控与智能核心选择

## 目录

- [概述](#概述)
- [特性](#特性)
- [使用](#使用)
- [API 参考](#api-参考)
- [设计](#设计)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [历史](#历史)

## 概述

cpu_load 是高性能 Rust 库，用于实时 CPU 负载监控和智能核心选择，基于 **compio** 异步生态系统构建。

传统 CPU 负载 API（如 `sysinfo`）每次调用需等待约 200ms 才能获取准确读数。本库通过后台采样任务解决此问题，允许即时访问预采集的指标，无需阻塞等待。

库在后台任务中持续采样 CPU 使用率，维护全局 CPU 和各核心的最新负载指标。通过原子操作和无锁数据结构，为并发应用提供高性能监控。

## 特性

- 后台实时采样 CPU 指标
- 线程安全的原子操作支持并发访问
- 惰性轮询算法实现智能核心选择
- 标准 Rust 迭代器模式支持
- 预分配结构实现零运行时分配
- 无缝集成 compio 异步运行时

## 使用

### 基本监控

```rust
use std::time::Duration;
use cpu_load::CpuLoad;

// 初始化，采样间隔 500ms
let monitor = CpuLoad::init(Duration::from_millis(500));

// 全局 CPU 负载 (0-100)
let global = monitor.global();
println!("全局: {global}%");

// 指定核心负载
if let Some(load) = monitor.core(0) {
  println!("核心 0: {load}%");
}

// 核心数
println!("核心数: {}", monitor.len());
```

### 智能核心选择

```rust
use std::time::Duration;
use cpu_load::CpuLoad;

let monitor = CpuLoad::init(Duration::from_millis(100));

// 获取最空闲核心索引用于任务分配
let core = monitor.idlest();
println!("最空闲核心: {core}");
```

### 迭代器模式

```rust
use std::time::Duration;
use cpu_load::CpuLoad;

let monitor = CpuLoad::init(Duration::from_millis(200));

// 遍历所有核心负载
for (i, load) in monitor.into_iter().enumerate() {
  println!("核心 {i}: {load}%");
}

// 收集到向量
let loads: Vec<u8> = monitor.into_iter().collect();

// 过滤高负载核心
let high: Vec<usize> = monitor
  .into_iter()
  .enumerate()
  .filter(|(_, load)| *load > 80)
  .map(|(i, _)| i)
  .collect();
```

## API 参考

### CpuLoad

CPU 负载监控主结构体。

| 方法 | 描述 |
|------|------|
| `new() -> Arc<Self>` | 使用默认 1 秒间隔创建监控器 |
| `init(interval: Duration) -> Arc<Self>` | 创建监控器，启动后台采样 |
| `global(&self) -> u8` | 当前全局 CPU 负载 (0-100) |
| `core(&self, idx: usize) -> Option<u8>` | 指定核心负载 (0-100) |
| `len(&self) -> usize` | CPU 核心数 |
| `is_empty(&self) -> bool` | 检查是否无核心 |
| `idlest(&self) -> usize` | 最空闲 CPU 核心索引 |

实现 `Default` trait，等同于 `CpuLoad::new()`。

### CpuLoadIter

核心负载迭代器，实现 `Iterator<Item = u8>` 和 `ExactSizeIterator`。

```rust
impl<'a> IntoIterator for &'a CpuLoad {
  type Item = u8;
  type IntoIter = CpuLoadIter<'a>;
}
```

## 设计

```mermaid
graph TD
  A[CpuLoad::init] --> B[创建 Arc 实例]
  B --> C[启动后台任务]
  B --> D[返回 Arc 给调用者]

  C --> E[初始延迟 100ms]
  E --> F[采样 CPU 指标]
  F --> G[休眠间隔]
  G --> H{Weak 引用有效?}
  H -->|是| F
  H -->|否| I[任务结束]

  J[idlest 调用] --> K{sorting 标志?}
  K -->|true| L[使用当前 Rank]
  K -->|false| M{cursor >= n?}
  M -->|否| N[返回 cursor 处的 rank]
  M -->|是| O{CAS sorting?}
  O -->|失败| N
  O -->|成功| P[按负载排序]
  P --> Q[更新 Rank 数组]
  Q --> R[重置 cursor 为 0]
  R --> S[返回 rank 0]
```

### 核心原则

**关注点分离**：后台采样与 API 访问隔离。

**无锁设计**：原子操作防止线程竞争。

**惰性求值**：仅当 cursor 耗尽 rank 数组时才排序。

**内存效率**：预分配 Box<[Atomic]> 避免运行时分配。

## 技术栈

| 组件 | 用途 |
|------|------|
| Rust 2024 | 现代语言特性 |
| compio | 异步运行时 (io-uring/IOCP) |
| sysinfo | 跨平台系统信息 |
| 原子操作 | 无锁同步 |

### compio 生态系统

compio 利用平台特定 I/O 原语：

- **Linux**：io-uring 实现高吞吐 I/O
- **Windows**：IOCP 实现最佳性能
- **跨平台**：一致的 API

## 项目结构

```
cpu_load/
├── src/
│   ├── lib.rs      # 主实现
│   └── iter.rs     # 迭代器
├── tests/
│   └── main.rs     # 集成测试
├── readme/
│   ├── en.md       # 英文文档
│   └── zh.md       # 中文文档
└── Cargo.toml
```

## 历史

CPU 负载监控可追溯到早期 Unix 系统，`load average` 衡量系统需求——1、5、15 分钟内运行队列中的平均进程数。

2000 年代中期从单核到多核处理器的转变产生了对每核心跟踪的需求。本库在此演进基础上提供实时每核心指标。

惰性轮询算法灵感来自分布式系统负载均衡器。它不维护连续排序列表（计算成本高），而是根据访问模式按需排序。

原子操作在监控中随多线程应用兴起而变得重要。传统基于锁的方法在高频场景中造成显著开销。本库采用高性能系统编程中的标准无锁模式。

趣闻："load average" 术语由 BBN Technologies 在 1970 年代初的 TENEX 操作系统中创造。TENEX 后来影响了 Unix 开发，该概念通过 Linux 的 `/proc/loadavg` 延续至今。