cpu_load 0.1.2

[English](#en) | [中文](#zh)

---

<a id="en"></a>

# cpu_load : Real-time CPU Monitoring with Intelligent Core Selection

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Design](#design)
- [Tech Stack](#tech-stack)
- [Project Structure](#project-structure)
- [History](#history)

## Overview

cpu_load is high-performance Rust library for real-time CPU load monitoring and intelligent core selection, built on the **compio** async ecosystem.

Traditional CPU load APIs (like `sysinfo`) require waiting ~200ms between calls to get accurate readings. This library solves that problem by running background sampling tasks, allowing instant access to pre-collected metrics without blocking.

The library continuously samples CPU usage in background tasks, maintaining up-to-date load metrics for global CPU and individual cores. Through atomic operations and lock-free data structures, it delivers high-performance monitoring suitable for concurrent applications.

## Features

- Real-time background sampling of CPU metrics
- Thread-safe atomic operations for concurrent access
- Intelligent core selection via lazy round-robin algorithm
- Standard Rust iterator pattern support
- Zero runtime allocation with pre-allocated structures
- Seamless compio async runtime integration

## Usage

### Basic Monitoring

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

// Initialize with 500ms sampling interval
let monitor = CpuLoad::init(Duration::from_millis(500));

// Global CPU load (0-100)
let global = monitor.global();
println!("Global: {global}%");

// Specific core load
if let Some(load) = monitor.core(0) {
  println!("Core 0: {load}%");
}

// Core count
println!("Cores: {}", monitor.len());
```

### Intelligent Core Selection

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

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

// Get idlest core index for task assignment
let core = monitor.idlest();
println!("Idlest core: {core}");
```

### Iterator Pattern

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

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

// Iterate all core loads
for (i, load) in monitor.into_iter().enumerate() {
  println!("Core {i}: {load}%");
}

// Collect to vector
let loads: Vec<u8> = monitor.into_iter().collect();

// Filter high-load cores
let high: Vec<usize> = monitor
  .into_iter()
  .enumerate()
  .filter(|(_, load)| *load > 80)
  .map(|(i, _)| i)
  .collect();
```

## API Reference

### CpuLoad

Main structure for CPU load monitoring.

| Method | Description |
|--------|-------------|
| `new() -> Arc<Self>` | Create monitor with default 1s interval |
| `init(interval: Duration) -> Arc<Self>` | Create monitor, start background sampling |
| `global(&self) -> u8` | Current global CPU load (0-100) |
| `core(&self, idx: usize) -> Option<u8>` | Specific core load (0-100) |
| `len(&self) -> usize` | Number of CPU cores |
| `is_empty(&self) -> bool` | Check if no cores |
| `idlest(&self) -> usize` | Index of idlest CPU core |

Implements `Default` trait, equivalent to `CpuLoad::new()`.

### CpuLoadIter

Iterator over core loads, implements `Iterator<Item = u8>` and `ExactSizeIterator`.

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

## Design

```mermaid
graph TD
  A[CpuLoad::init] --> B[Create Arc Instance]
  B --> C[Spawn Background Task]
  B --> D[Return Arc to Caller]

  C --> E[Initial Delay 100ms]
  E --> F[Sample CPU Metrics]
  F --> G[Sleep Interval]
  G --> H{Weak Ref Valid?}
  H -->|Yes| F
  H -->|No| I[Task Ends]

  J[idlest Call] --> K{sorting flag?}
  K -->|true| L[Use Current Rank]
  K -->|false| M{cursor >= n?}
  M -->|No| N[Return rank at cursor]
  M -->|Yes| O{CAS sorting?}
  O -->|Fail| N
  O -->|Success| P[Sort by Load]
  P --> Q[Update Rank Array]
  Q --> R[Reset cursor to 0]
  R --> S[Return rank 0]
```

### Key Principles

**Separation of Concerns**: Background sampling isolated from API access.

**Lock-free Design**: Atomic operations prevent thread contention.

**Lazy Evaluation**: Core sorting occurs only when cursor exhausts rank array.

**Memory Efficiency**: Pre-allocated Box<[Atomic]> prevents runtime allocation.

## Tech Stack

| Component | Purpose |
|-----------|---------|
| Rust 2024 | Modern language features |
| compio | Async runtime (io-uring/IOCP) |
| sysinfo | Cross-platform system info |
| Atomic ops | Lock-free synchronization |

### compio Ecosystem

compio leverages platform-specific I/O primitives:

- **Linux**: io-uring for high-throughput I/O
- **Windows**: IOCP for optimal performance
- **Cross-platform**: Consistent API

## Project Structure

```
cpu_load/
├── src/
│   ├── lib.rs      # Main implementation
│   └── iter.rs     # Iterator
├── tests/
│   └── main.rs     # Integration tests
├── readme/
│   ├── en.md       # English docs
│   └── zh.md       # Chinese docs
└── Cargo.toml
```

## History

CPU load monitoring traces back to early Unix systems where `load average` measured system demand—average processes in run queue over 1, 5, and 15 minutes.

The mid-2000s shift from single-core to multi-core processors created need for per-core tracking. This library builds on that evolution with real-time per-core metrics.

The lazy round-robin algorithm draws inspiration from distributed system load balancers. Rather than maintaining continuously sorted lists (computationally expensive), it uses on-demand sorting triggered by access patterns.

Atomic operations in monitoring became prominent with multi-threaded applications. Traditional lock-based approaches caused significant overhead in high-frequency scenarios. This library embraces lock-free patterns standard in high-performance systems programming.

Fun fact: The term "load average" was coined by the TENEX operating system in the early 1970s at BBN Technologies. TENEX later influenced Unix development, and the concept persists in modern systems via `/proc/loadavg` on Linux.

---

## About

This project is an open-source component of [js0.site ⋅ Refactoring the Internet Plan](https://js0.site).

We are redefining the development paradigm of the Internet in a componentized way. Welcome to follow us:

* [Google Group](https://groups.google.com/g/js0-site)
* [js0site.bsky.social](https://bsky.app/profile/js0site.bsky.social)

---

<a id="zh"></a>

# 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` 延续至今。

---

## 关于

本项目为 [js0.site ⋅ 重构互联网计划](https://js0.site) 的开源组件。

我们正在以组件化的方式重新定义互联网的开发范式，欢迎关注：

* [谷歌邮件列表](https://groups.google.com/g/js0-site)
* [js0site.bsky.social](https://bsky.app/profile/js0site.bsky.social)