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

API docs of the tsc-timer crate master branch

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

// 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!(has_invariant_tsc(), "The TSC is not invariant!");

let (duration, result) 
    = Duration::span(|| black_box(fibonacci(black_box(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-timer by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.