API Reference

ResourceTimer

A thread-safe timer that aggregates timing and resource usage data across multiple tasks.

Fields

• storage::Vector{Vector{ResourceAccumulator}}: A matrix of accumulators, indexed by task ID and label index.
• label_to_idx::Dict{Symbol, Int}: A mapping from label symbols to their integer indices.
• labels::Vector{Symbol}: The list of valid labels.

Constructors

ResourceTimer(labels::Vector{Symbol}; ntasks::Int = 256)

Creates a new ResourceTimer with the specified labels. ntasks should be set to the maximum expected task ID (or thread ID) to ensure thread safety.

ResourceAccumulator

A mutable struct that accumulates timing and resource usage statistics for a specific task and label.

Fields

• count::Int: The number of times this accumulator has been updated.
• total_time_ns::UInt64: The total execution time in nanoseconds.
• total_bytes::Int64: The total number of bytes allocated.
• total_gctime_ns::UInt64: The total time spent in garbage collection in nanoseconds.

@meas(timer, task_id, label, expr)

Measure the execution time and memory allocation of expr and record it in timer.

Arguments

• timer: The ResourceTimer instance.
• task_id: An integer representing the current task or thread ID. This determines which accumulator to update.
• label: A bare identifier (e.g. compute, not :compute) naming the code block. Must match one of the labels defined in timer.
• expr: The expression to evaluate and measure.

Example

task_id = 1
@meas rt task_id computation begin
    # ... computation ...
end

record!(acc::ResourceAccumulator, time_ns, bytes, gctime_ns)

Update the accumulator acc with new measurement data.

Arguments

• acc::ResourceAccumulator: The accumulator to update.
• time_ns: The execution time in nanoseconds to add.
• bytes: The number of allocated bytes to add.
• gctime_ns: The garbage collection time in nanoseconds to add.

This function increments the count field by 1 and adds the provided values to the respective total fields.

reset!(rt::ResourceTimer)

Reset all accumulators in the ResourceTimer to zero.

This clears the count, total_time_ns, total_bytes, and total_gctime_ns fields for all labels and tasks.

show(io::IO, rt::ResourceTimer)

Print a formatted summary table of the resource usage statistics accumulated in rt.

The table includes:

• label: The label symbol.
• count: Total number of measurements for that label.
• time: Total execution time in seconds.
• mem: Total memory allocated in Megabytes (MB).
• gctime: Total garbage collection time in seconds.

The output is sorted by total execution time in descending order.