kala 1.0.0

Timing with nanosecond precision on multiple architectures.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

//! `kala` provides a simple API for timing sections of code with _sub-nanosecond
//! precision._ It can run and time a function while preventing interference from CPU
//! and compiler instruction reordering. It uses CPU hardware clock counters
//! like the _[Time Stamp Counter][tsc]_ (TSC) on [x86-64] or the _[Cycle Counter
//! Register][ccnt]_ (CCNT) on [AArch64] (with an `std::time::Instant` fallback on
//! other architectures).
//!
//! # Example
//!
//! ```
//! use kala::Stopwatch;
//!
//! let sw = Stopwatch::new(); // Most efficient to create once and re-use.
//! let nanos: f64 = sw.time(|| 2 + 3).to_nanos(); // Runs closure _once_.
//! println!("Function took {nanos:.2} nanos");
//! ```
//!
//! # Note on Precision
//!
//! While `kala` goes to extreme lengths to provide the highest level of timing
//! precision, ultimately **measurement precision depends on your CPU**. Some
//! CPUs---especially those using the `AArch64` architecture---have very coarse
//! CPU time counters. For instance, the Apple M1 and M2 (but not M3 and later)
//! use a CPU time counter with a 24 MHz frequency. Thus the clock "ticks" every
//! ~41.67 nanoseconds. **No other clock source on that CPU can offer better
//! granularity.**
//!
//! It's still possible to extract finer timing precision from such data, but
//! that requires collecting many measurements with an excellent experiment
//! design and great statistics. This is the job of benchmarking harnesses that
//! _use_ `kala`, not `kala` itself.
//!
//! See the API docs for [`kala::Duration`][Duration] for advice on avoiding
//! conversion losses and getting the highest precision.
//!
//! [x86-64]: https://en.wikipedia.org/wiki/X86-64
//! [aarch64]: https://en.wikipedia.org/wiki/AArch64
//! [tsc]: https://en.wikipedia.org/wiki/Time_Stamp_Counter
//! [ccnt]: https://support.arm.com/documentation/ddi0211/k/system-control-coprocessor/system-control-coprocessor-register-descriptions/c15--cycle-counter-register--ccnt-
#![deny(missing_docs)]
#![deny(clippy::all)]
#![deny(clippy::doc_markdown)]
#![deny(clippy::missing_errors_doc)]
#![deny(clippy::missing_panics_doc)]
#![deny(clippy::must_use_candidate)]
#![deny(clippy::missing_safety_doc)]
#![deny(clippy::return_self_not_must_use)]
#![deny(clippy::semicolon_if_nothing_returned)]

mod arch;
mod stopwatch;
mod time;

#[cfg(test)]
mod test_utils;

pub use stopwatch::Stopwatch;
pub use time::Duration;