#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum NoReading {
NoClock,
Unreadable,
}
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum ThreadTicks {
Measured(u64),
Absent(NoReading),
}
impl ThreadTicks {
pub fn ticks(self) -> Option<u64> {
match self {
Self::Measured(ticks) => Some(ticks),
Self::Absent(_) => None,
}
}
}
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum OccupancySample {
Measured {
thread_ticks: u64,
wall_ticks: u64,
},
Unmeasured {
wall_ticks: u64,
reason: NoReading,
},
}
impl OccupancySample {
pub fn percent(&self) -> Option<u32> {
let (thread_ticks, wall_ticks) = match *self {
Self::Measured { thread_ticks, wall_ticks } => (thread_ticks, wall_ticks),
Self::Unmeasured { .. } => return None,
};
if wall_ticks == 0 {
return Some(100);
}
let pct = thread_ticks.saturating_mul(100) / wall_ticks;
Some(pct.min(100) as u32)
}
pub fn per_mille(&self) -> Option<u32> {
let (thread_ticks, wall_ticks) = match *self {
Self::Measured { thread_ticks, wall_ticks } => (thread_ticks, wall_ticks),
Self::Unmeasured { .. } => return None,
};
if wall_ticks == 0 {
return Some(1000);
}
let share = thread_ticks.saturating_mul(1000) / wall_ticks;
Some(share.min(1000) as u32)
}
}
#[derive(Debug)]
pub struct OccupancyWindow {
thread_at_start: ThreadTicks,
wall_at_start: u64,
}
impl OccupancyWindow {
pub fn start() -> Self {
let (thread, wall) = clock_pair();
Self { thread_at_start: thread, wall_at_start: wall }
}
pub fn sample(&self) -> OccupancySample {
let (thread, wall) = clock_pair();
let wall_ticks = wall.saturating_sub(self.wall_at_start);
match (self.thread_at_start, thread) {
(ThreadTicks::Measured(start), ThreadTicks::Measured(end)) => {
OccupancySample::Measured {
thread_ticks: end.saturating_sub(start),
wall_ticks,
}
}
(ThreadTicks::Absent(NoReading::Unreadable), _)
| (_, ThreadTicks::Absent(NoReading::Unreadable)) => OccupancySample::Unmeasured {
wall_ticks,
reason: NoReading::Unreadable,
},
_ => OccupancySample::Unmeasured { wall_ticks, reason: NoReading::NoClock },
}
}
}
#[cfg(all(windows, target_arch = "x86_64"))]
pub(crate) fn clock_pair() -> (ThreadTicks, u64) {
(thread_on_core_ticks(), unsafe { core::arch::x86_64::_rdtsc() })
}
#[cfg(not(all(windows, target_arch = "x86_64")))]
pub(crate) fn clock_pair() -> (ThreadTicks, u64) {
static ORIGIN: std::sync::OnceLock<std::time::Instant> = std::sync::OnceLock::new();
let origin = ORIGIN.get_or_init(std::time::Instant::now);
(thread_on_core_ticks(), origin.elapsed().as_nanos() as u64)
}
#[cfg(windows)]
pub fn thread_on_core_ticks() -> ThreadTicks {
#[link(name = "kernel32")]
unsafe extern "system" {
fn GetCurrentThread() -> isize;
fn QueryThreadCycleTime(thread: isize, cycles: *mut u64) -> i32;
}
let mut cycles: u64 = 0;
let ok = unsafe { QueryThreadCycleTime(GetCurrentThread(), &mut cycles) };
if ok == 0 {
return ThreadTicks::Absent(NoReading::Unreadable);
}
ThreadTicks::Measured(cycles)
}
#[cfg(any(target_os = "linux", target_os = "freebsd"))]
pub fn thread_on_core_ticks() -> ThreadTicks {
let mut ts = libc_timespec { tv_sec: 0, tv_nsec: 0 };
let r = unsafe { clock_gettime(CLOCK_THREAD_CPUTIME_ID, &mut ts) };
if r != 0 {
return ThreadTicks::Absent(NoReading::Unreadable);
}
ThreadTicks::Measured(
(ts.tv_sec as u64).saturating_mul(1_000_000_000) + ts.tv_nsec as u64,
)
}
#[cfg(any(target_os = "linux", target_os = "freebsd"))]
#[repr(C)]
struct libc_timespec {
tv_sec: i64,
tv_nsec: i64,
}
#[cfg(target_os = "linux")]
const CLOCK_THREAD_CPUTIME_ID: i32 = 3;
#[cfg(target_os = "freebsd")]
const CLOCK_THREAD_CPUTIME_ID: i32 = 14;
#[cfg(any(target_os = "linux", target_os = "freebsd"))]
#[link(name = "c")]
unsafe extern "C" {
fn clock_gettime(clk_id: i32, tp: *mut libc_timespec) -> i32;
}
#[cfg(not(any(windows, target_os = "linux", target_os = "freebsd")))]
pub fn thread_on_core_ticks() -> ThreadTicks {
ThreadTicks::Absent(NoReading::NoClock)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_spinning_thread_reads_more_of_its_core_than_a_sleeping_one() {
let spinning = OccupancyWindow::start();
let mut x: u64 = 0;
let until = std::time::Instant::now() + std::time::Duration::from_millis(40);
while std::time::Instant::now() < until {
x = x.wrapping_mul(6364136223846793005).wrapping_add(1);
}
std::hint::black_box(x);
let spun = spinning.sample();
let sleeping = OccupancyWindow::start();
std::thread::sleep(std::time::Duration::from_millis(40));
let slept = sleeping.sample();
let (Some(spin_pct), Some(sleep_pct)) = (spun.percent(), slept.percent()) else {
return;
};
assert!(
spin_pct > sleep_pct,
"a thread that ran for its window must read more of its core than one \
that slept through it: spinning {spin_pct}%, sleeping {sleep_pct}%"
);
}
#[test]
fn a_thread_that_sleeps_reads_low_where_the_clock_exists() {
let w = OccupancyWindow::start();
std::thread::sleep(std::time::Duration::from_millis(40));
let Some(pct) = w.sample().percent() else {
return;
};
assert!(pct < 50, "a sleeping thread used almost no core, yet read {pct}%");
}
#[test]
fn a_zero_length_window_reads_full_rather_than_undefined() {
let s = OccupancySample::Measured { thread_ticks: 0, wall_ticks: 0 };
assert_eq!(s.percent(), Some(100), "no interval divides by no interval");
}
#[test]
fn occupancy_saturates_rather_than_exceeding_the_interval() {
let s = OccupancySample::Measured { thread_ticks: 2_000, wall_ticks: 1_000 };
assert_eq!(
s.percent(),
Some(100),
"two clocks of different resolutions must not report 200 percent"
);
}
#[test]
fn an_unmeasured_interval_reports_no_figure_rather_than_a_plausible_one() {
for reason in [NoReading::NoClock, NoReading::Unreadable] {
let s = OccupancySample::Unmeasured { wall_ticks: 1_000, reason };
assert_eq!(
s.percent(),
None,
"an interval with no on-core count has no occupancy to report"
);
}
}
#[test]
fn a_measured_zero_is_not_the_same_finding_as_no_measurement() {
let measured = OccupancySample::Measured { thread_ticks: 0, wall_ticks: 1_000 };
let unmeasured =
OccupancySample::Unmeasured { wall_ticks: 1_000, reason: NoReading::NoClock };
assert_eq!(
measured.percent(),
Some(0),
"a thread that genuinely got no core ran at zero percent"
);
assert_eq!(unmeasured.percent(), None);
assert_ne!(
measured.percent(),
unmeasured.percent(),
"total contention and no clock must not read the same"
);
}
#[test]
fn an_absent_count_yields_no_number_to_a_caller_that_wants_one() {
assert_eq!(ThreadTicks::Measured(7).ticks(), Some(7));
assert_eq!(ThreadTicks::Absent(NoReading::NoClock).ticks(), None);
assert_eq!(ThreadTicks::Absent(NoReading::Unreadable).ticks(), None);
}
#[test]
#[cfg(any(windows, target_os = "linux", target_os = "freebsd"))]
fn this_host_reads_its_own_thread_clock() {
match thread_on_core_ticks() {
ThreadTicks::Measured(_) => {}
ThreadTicks::Absent(reason) => panic!(
"this platform is expected to report thread CPU time, got {reason:?}"
),
}
}
}