Skip to main content

main

hotpath_macros

Attribute Macro main 

Source 
#[main]
Expand description

Initializes the hotpath profiling system and generates a performance report on program exit.

This attribute macro should be applied to your program’s main (or other entry point) function to enable profiling. It creates a guard that initializes the background measurement processing thread and automatically displays a performance summary when the program exits. Additionally it creates a measurement guard that will be used to measure the wrapper function itself.

For programmatic control over the same options, see HotpathGuardBuilder.

§Parameters

  • percentiles - Array of percentile values (0.0-100.0) to compute, e.g. [50, 95, 99.9]. Default: [95]
  • format - Output format: "table" (default), "json", "json-pretty", or "none"
  • limit - Global maximum number of items shown in each report section (functions, channels, streams, futures, threads). 0 = unlimited.
  • functions_limit - Maximum number of functions shown in the report. Overrides limit for functions.
  • channels_limit - Maximum number of channels shown in the report. Overrides limit for channels.
  • streams_limit - Maximum number of streams shown in the report. Overrides limit for streams.
  • futures_limit - Maximum number of futures shown in the report. Overrides limit for futures.
  • threads_limit - Maximum number of threads shown in the report. Overrides limit for threads.
  • output_path - File path for the report. Defaults to stdout. Overridden by HOTPATH_OUTPUT_PATH env var.
  • report - Report sections spec: "all", "auto", an exact list like "functions-timing,channels", or auto with exclusions like "auto,-threads". Default: auto (function and thread sections plus every instrumented section with data). Overridden by HOTPATH_REPORT env var.
  • allocator - Optional allocator used when hotpath-alloc is enabled. The path must name a unit struct implementing GlobalAlloc (e.g. mimalloc::MiMalloc); it is used both as the type and the value of the inner allocator. Defaults to std::alloc::System.

Environment variable precedence for report output: HOTPATH_LIMIT, HOTPATH_FUNCTIONS_LIMIT, HOTPATH_CHANNELS_LIMIT, HOTPATH_STREAMS_LIMIT, HOTPATH_FUTURES_LIMIT, and HOTPATH_THREADS_LIMIT override the matching macro arguments. Per-resource env vars override HOTPATH_LIMIT.

§Examples

Basic usage with default settings (P95 percentile, table format):

#[hotpath::main]
fn main() {
    // Your code here
}

Custom percentiles:

#[tokio::main]
#[hotpath::main(percentiles = [50, 90, 95, 99.9])]
async fn main() {
    // Your code here
}

JSON output to file:

#[hotpath::main(format = "json-pretty", output_path = "report.json")]
fn main() {
    // Your code here
}

Select exact report sections, or hide a section from the auto report:

#[hotpath::main(report = "functions-timing,channels")]
fn main() {
    // Your code here
}
#[hotpath::main(report = "auto,-threads")]
fn main() {
    // Your code here
}

Per-resource limits:

#[hotpath::main(limit = 10, functions_limit = 20, channels_limit = 5)]
fn main() {
    // Your code here
}

§Usage with Tokio

When using with tokio, place #[tokio::main] before #[hotpath::main]:

#[tokio::main]
#[hotpath::main]
async fn main() {
    // Your code here
}

§Limitations

Only one hotpath guard can be active at a time. Creating a second guard (either via this macro or via HotpathGuardBuilder) will cause a panic.

§See Also