cpu_load 0.1.4

Real-time CPU load monitoring with intelligent core selection / 实时 CPU 负载监控与智能核心选择
Documentation

English | 中文

cpu_load : Real-time CPU Monitoring with Intelligent Core Selection

Table of Contents

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

use cpu_load::CpuLoad;

// Use default 1s sampling interval
let monitor = CpuLoad::new();

// 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());

Custom Sampling Interval

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

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

Intelligent Core Selection

use cpu_load::CpuLoad;

let monitor = CpuLoad::new();

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

Iterator Pattern

use cpu_load::CpuLoad;

let monitor = CpuLoad::new();

// 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() -> Self Create monitor with default 1s interval
init(interval: Duration) -> 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.

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

Design

graph TD
  A[CpuLoad::new/init] --> B[Create Instance]
  B --> C[Spawn Background Task]
  B --> D[Return CpuLoad]

  C --> E[Initial Delay 100ms]
  E --> F[Sample CPU Metrics]
  F --> G[Sleep Interval]
  G --> H{Stop Signal?}
  H -->|No| F
  H -->|Yes| I[Free Memory via defer]

  J[idlest Call] --> K{cursor >= n?}
  K -->|No| L[Return rank at cursor]
  K -->|Yes| M{CAS sorting?}
  M -->|Fail| N[Spin Wait]
  N --> L
  M -->|Success| O[Sort by Load]
  O --> P[Reset cursor]
  P --> Q[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.

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

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

目录

概述

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

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

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

特性

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

使用

基本监控

use cpu_load::CpuLoad;

// 使用默认 1 秒采样间隔
let monitor = CpuLoad::new();

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

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

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

自定义采样间隔

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

// 自定义采样间隔 500ms
let monitor = CpuLoad::init(Duration::from_millis(500));

智能核心选择

use cpu_load::CpuLoad;

let monitor = CpuLoad::new();

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

迭代器模式

use cpu_load::CpuLoad;

let monitor = CpuLoad::new();

// 遍历所有核心负载
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() -> Self 使用默认 1 秒间隔创建监控器
init(interval: Duration) -> 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。

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

设计

graph TD
  A[CpuLoad::new/init] --> B[创建实例]
  B --> C[启动后台任务]
  B --> D[返回 CpuLoad]

  C --> E[初始延迟 100ms]
  E --> F[采样 CPU 指标]
  F --> G[休眠间隔]
  G --> H{停止信号?}
  H -->|否| F
  H -->|是| I[通过 defer 释放内存]

  J[idlest 调用] --> K{cursor >= n?}
  K -->|否| L[返回 cursor 处的 rank]
  K -->|是| M{CAS sorting?}
  M -->|失败| N[自旋等待]
  N --> L
  M -->|成功| O[按负载排序]
  O --> P[重置 cursor]
  P --> Q[返回 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 ⋅ 重构互联网计划 的开源组件。

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