Breezy timer ⏲️

Breezy timer's objective is to be a very simple timing library, which can be put into production code without changing the final performance. See section how does it work for further information.

Aim

• simple to use
• use directly in production code,
• no need to modify code when releasing, simply de-activate feature!

Note: due to the structure, and the use of locking mechanism (thread safety), this package is not suitable for very high performance timings. It takes, on my average machine, about 500ns per update (whether start or stop). If you try to time blocks of code which are of this order of magnitude of speed, the readings will be quite useless. Generally, if you want to benchmark pieces of code of that order of speed, you probably want to use individual benchmark files, with tools such as Criterion.

Usage

Add these lines to your Cargo.toml: ``` [dependencies] breezy-timer = "0.1.2"

[features] breezytimer = ["breezy-timer/breezytimer"] `` When compiling, simply add thefeaturebreezy_timer` if you want to have the times, e.g.

cargo build foocrate --release --features breezy_timer

if the feature is not explicitely provided, all timers will disappear at compilation.

API

prepare_timer!(): must be called before any other timer related function

start_timer!("foo"): creates or updates timer called foo to ProcessTime::now()

stop_timer!("foo"): computes the ProcessTime since the last start_timer!("foo") was called, and adds it to the timer state

elapsed_ns!("foo"): returns the sum of the nano secondes spent in the timer foo. When feature not active, returns 0u128

get_timers_map!(): returns a clone of the HashMap containing all the timers and their TimerState: When feature not active, returns an empty HashMap

Example

Taken from examples/basic_example.rs ```rust

use cputime::ProcessTime; use criterion::blackbox;

use breezytimer::{preparetimer, starttimer, stoptimer, elapsedns, gettimers_map};

// must be called before prepare_timer!();

fn main(){ let mut vectors = Vec::new();

start_timer!("total");
for _ in 0..10 {
    start_timer!("allocations");
    let vec: Vec<u8> = (0..102400).map(|_| { rand::random::<u8>() }).collect();
    vectors.push(vec);
    stop_timer!("allocations");

    start_timer!("sum");
    let mut total = 0;
    for v in vectors.iter() {
        total += v.iter().map(|x| *x as u32).sum::<u32>();
    }
    // used so that compiler doesn't simply remove the loop because nothing is done with total
    black_box(total);
    stop_timer!("sum");
}
stop_timer!("total");

println!("{:?}", get_timers_map!());
println!(" - allocations: {}ns\n - sum: {}ns\n - total: {}ns", elapsed_ns!("allocations"), elapsed_ns!("sum"), elapsed_ns!("total"));

} ```

How does it work

features are a rust compilation mechanism which allows you to do conditional compilation. This crate makes use of this together with macros, in order to make it so that a normal compilation (without the feature activated) will leave no trace of the library in the final code. Hence, there is no performance drop when releasing, making the transition between development to release painless.

Structure

When activated, the library creates a global thread safe HashMap containing the names of the timers and their current state. The states are a structure which containes the last ProcessTime, and the total number of nano seconds in the timer.

When we call start_timer("foo"), what happens entry foo in the global hash map is created if it doesn't exist, or updated, and its start time is set to ProcessTime::now().

When stop_timer!("foo") is called, the entry foo is fetched the elapsed time since the last start_timer!("foo") is added to the total nanoseconds variable.

Future work

• Add get_json!(): macro to get the timers formatted in json of shape `{"timer-name": totalelapsedns}
• Check performance gain with simpler hasher (by default, HashMap uses DOS-safe hasher)

License

This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

PR requests are welcome highly welcome!

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