kala 2.1.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

`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).

```rust
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");
```

`kala` is _not_ a benchmarking harness; it won't run a closure in a loop and 
report summary statistics. You need to provide that on top of `kala`.

[See the API documentation.][docs]

# Comparison With Other Libraries

- [`quanta`][quanta]
  - Does not prevent interference from CPU and compiler instruction reordering.
  - Less precise TSC frequency estimation.
- [`clocksource`][clocksource]
  - Does not prevent interference from CPU and compiler instruction reordering.
  - Does not appear to use CPU hardware clocks; always goes through OS APIs.
- [`libcpucycles`][libcpucycles]
  - Focused on counting _cycles_, not _time_[^1].
  - C library.

The are other libraries in the same space, but all of them either don't use CPU
hardware clocks, don't handle CPU/compiler instruction reordering or usually
both.

[^1]: CPU cycles don't map cleanly to time due to factors like dynamic frequency 
scaling, memory latency and others.

# Contributing

_Every part_ of this library was _written by hand_ by a professional software
engineer with decades of experience. **No AI-authored code, text or images are
included**.

This project **[rejects _all_ contributions containing AI content][ai-policy]**.
There are **no exceptions**. 

[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-
[quanta]: https://crates.io/crates/quanta
[libcpucycles]: https://cpucycles.cr.yp.to/
[clocksource]: https://crates.io/crates/clocksource
[docs]: https://docs.rs/kala
[ai-policy]: https://codeberg.org/Valloric/kala/src/branch/main/AI_POLICY.md