Crate 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.

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.

Structs

FUNCTION_METRICS

Stores the function call count and total duration for each function. The function index is a unique u32 identifier for the function. Mapping: (Function name, Function index) -> (Call count, Total duration)

FUNCTION_METRICS_HIERARCHY

Stores the function call count and total duration for each function in a specific call stack. The function index is a unique u32 identifier for the function. Mapping: (function index stack) -> (Function name, Function index) -> (Call count, Total duration)

Constants

CALL_STACK

Stores the current call stack of function indices. The function index is a unique u32 identifier for the function.

Functions

get_bench_fct_hy_results

Gets the raw function metrics grouped by call stack hierarchy. The function index is a unique u32 identifier for the function. Mapping: (function index stack) -> (Function name, Function index) -> (Call count, Total duration) This map is filled by execution of functions with the macro attribute #[auto_bench_fct_hy].

get_bench_fct_results

Gets the raw function metrics. The function index is a unique u32 identifier for the function. Mapping: (Function name, Function index) -> (Call count, Total duration) This map is filled by execution of functions with the macro attribute #[auto_bench_fct] or #[auto_bench_fct_hy].

print_bench_fct_hy_results

Prints the function hierarchy benchmark results in stdout. If the log feature is enabled, it will log the results using log::info!. If the disable_hy feature is enabled, this function does nothing. If the disable feature is enabled, this function does nothing.

print_bench_fct_results

Prints the function benchmark results in stdout. If the log feature is enabled, it will log the results using log::info!. If the disable feature is enabled, this function does nothing.

Attribute Macros

auto_bench_fct

Add the #[auto_bench_fct] macro attribute to a function to enable automatic benchmarking. It will store in a map the number of calls and the total duration of the function execution.

auto_bench_fct_hy

Add the #[auto_bench_fct_hy] macro attribute to a function to enable automatic benchmarking with hierarchy computation. It will do the same as #[auto_bench_fct], but it will also track he call stack, allowing to display the hierarchy of function calls.