auto_bench_fct 1.0.1

A library for automatically benchmarking function call count and execution time in Rust.
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
59
60
61
62
63
64
65
66
67
68
69
70
71

[![Latest version](https://img.shields.io/crates/v/auto_bench_fct.svg)](https://crates.io/crates/auto_bench_fct)
[![Documentation](https://docs.rs/auto_bench_fct/badge.svg)](https://docs.rs/auto_bench_fct)

A library for automatically benchmarking function call count and execution time in Rust.

Minimal setup is required to use this library, a macro attribute is provided
to enable automatic benchmarking of functions, and a function to print the results.

- Enable the `disable` feature to disable the library, which will make the macros and
  functions to do nothing, allowing to keep the code in production without performance overhead.
- Enable the `disable_hy` feature to disable only the call stack hierarchy tracking, which will
  make the macros `#[auto_bench_fct_hy]` behave like `#[auto_bench_fct]`.
- Enable the `log` feature to log the results using the `log` crate with the info level.
  This crate supports multithreaded programs, and uses wall time to measure the execution time of
  functions, which is suitable for most use cases.

# Installation

Run
```bash
cargo add auto_bench_fct
```
or add the following to your `Cargo.toml`:

```toml
[dependencies]
auto_bench_fct = "1"
```

# Usage

## Define which functions to benchmark

Add the `#[auto_bench_fct]` macro attribute to a function to track its execution time and calls
count, or addd the `#[auto_bench_fct_hy]` macro attribute to track its execution time
and calls count both globally and in the call stack hierarchy.

## Print the results

- Print the benchmark of functions with the macro attribute `#[auto_bench_fct]`
  or `#[auto_bench_fct_hy]` grouped by function using [`print_bench_fct_results`].
- Print the benchmark of functions with the macro attribute `#[auto_bench_fct_hy]` grouped by
  function and call stack context using [`print_bench_fct_hy_results`].

## Usage recommendations

Use the `#[auto_bench_fct_hy]` macro attribute for functions you want to benchmark, and
use `#[auto_bench_fct]` instead only if you want to exclude the function from the call stack
hierarchy.
When not wanting to debug the call stack hierarchy due to the performance overhead,
enable the feature `disable_hy`.
When not wanting to debug the function calls at all, enable the feature `disable`.

# Note about recursive functions

Recursive functions are supported and will be tracked correctly,
tracking only the root function call execution time.
Though, mutual recursion is not supported, meaning that if two functions call each other
recursively, it may create a huge number of entries in the metrics.

# Note about performance

This library is designed to be used in development and testing environments.
It may have a large performance overhead, mostly if used on recursive functions
or in functions with a large number of calls and a small execution time.
The macro `#[auto_bench_fct_hy]` has a larger performance overhead than `#[auto_bench_fct]`
and should not be used in non-heavy functions.

# License

This library is licensed under the GNU General Public License v3.0 (GPL-3.0).