x86/x86_64 time-stamp-counter (TSC) based timer

![Travis-CI Status] ![Appveyor Status] ![Latest Version] ![docs]

API docs of the tsc crate master branch

This library provides a time-stamp counter (TSC) based timer for micro benchmarking:

```rust // The function we want to time: pub fn fibonacci(n: u64) -> u64 { match n { 0 | 1 => 1, n => fibonacci(n - 1) + fibonacci(n - 2), } }

// Non-invariant TSCs might produce unreliable results: assert!(hasinvarianttsc(), "The TSC is not invariant!");

let (duration, result) = Duration::span(|| blackbox(fibonacci(blackbox(8))));

assert_eq!(result, 34);

println!("Reference cycle count: {} cycles.", duration.cycles()); //! // On my machine prints: "Reference cycle count: 951 cycles." ```

Notes

• The TSC runs at a different frequency than the CPU clock frequency, so the cycles reported here are "reference cycles" and not real CPU clock cycles.

• If the TSC is not invariant (Nehalem-and-later) the measurements might not be very accurate due to turbo boost, speed-step, power management, etc.

• Converting "reference cycles" to time (e.g., nanoseconds) is, in general, not possible to do reliably in user-space.

• One might want to disable preemption and hard interrupts before timing (see How to Benchmark Code Execution Times on Intel® IA-32 and IA-64 Instruction Set Architectures) to further improve the accuracy of the measurements.

  References

  • How to Benchmark Code Execution Times on Intel® IA-32 and IA-64 Instruction Set Architectures
  • Pitfalls of TSC usage
  • Time Stamps Counters
  • SO answer to "Get CPU cycle count"
  • So answer to "Using Time stamp counter to get the time stamp"

License

This project is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)

• MIT License (LICENSE-MIT)

at your option.

Contributing

We welcome all people who want to contribute.

Contributions in any form (issues, pull requests, etc.) to this project must adhere to Rust's [Code of Conduct].

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in tsc by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.