Profiler API Reference

Runtime performance profiling with timing, memory tracking, and sampling support

Import

U std/profiler

Constants

Structs

Timer

High-resolution timer for measuring code execution time.

Fields:

• start_ns: i64 - Start time in nanoseconds
• end_ns: i64 - End time in nanoseconds
• running: i64 - 1 if timer is running

ProfileEntry

Single profiling record for a named code region.

Fields:

• name: str - Profile region name
• call_count: i64 - Number of times called
• total_time_ns: i64 - Total time spent
• min_time_ns: i64 - Minimum time per call
• max_time_ns: i64 - Maximum time per call
• start_time: i64 - Start time (for nested timing)
• depth: i64 - Call depth (for recursion tracking)

Profiler

Main profiling interface with instrumentation support.

Fields:

• entries: i64 - Pointer to ProfileEntry array
• entry_count: i64 - Number of entries
• capacity: i64 - Array capacity
• enabled: i64 - Profiler mode (DISABLED/ENABLED/SAMPLING)
• start_time: i64 - Global start time
• sample_interval: i64 - Sampling interval in ms

MemoryProfiler

Track memory allocations and deallocations.

Fields:

• allocations: i64 - Total allocations count
• deallocations: i64 - Total deallocations count
• bytes_allocated: i64 - Current allocated bytes
• peak_bytes: i64 - Peak allocated bytes
• total_allocated: i64 - Total bytes ever allocated
• enabled: i64 - 1 if enabled

SampleProfiler

Statistical profiler that samples call stacks at intervals.

Fields:

• samples: i64 - Pointer to sample buffer
• sample_count: i64 - Number of samples collected
• capacity: i64 - Buffer capacity
• interval_ms: i64 - Sampling interval
• running: i64 - 1 if sampling active
• thread_handle: i64 - Sampler thread handle

FlameGraphBuilder

Generate flame graph data from stack samples.

Fields:

• stack_samples: i64 - Array of stack samples
• sample_count: i64 - Number of samples
• capacity: i64 - Buffer capacity

Global Functions

Profiler Management

Convenience Functions

Usage

Basic Timing

U std/profiler

F main() -> i64 {
    t := timer()
    t.start()

    # ... code to measure ...
    do_work()

    t.stop()
    ms := t.elapsed_ms()
    us := t.elapsed_us()

    0
}

Instrumentation Profiling

U std/profiler

F main() -> i64 {
    p := get_profiler()
    p.enable()

    # Profile regions
    p.enter("region1")
    do_work()
    p.exit("region1")

    p.enter("region2")
    do_more_work()
    p.exit("region2")

    # Print report
    p.report()

    0
}

Convenience Functions

U std/profiler

F expensive_computation(n: i64) -> i64 {
    sum := 0
    i := 0
    L i < n {
        sum = sum + i
        i = i + 1
    }
    sum
}

F main() -> i64 {
    # Profile with begin/end
    profile_begin("compute")
    result := expensive_computation(1000000)
    profile_end("compute")

    # Or time a function call
    (result2, elapsed) := time_fn(expensive_computation_ptr, 1000000)

    get_profiler().report()

    0
}

Memory Profiling

U std/profiler

F main() -> i64 {
    mem := get_mem_profiler()
    mem.enable()

    # Allocations are tracked automatically
    buffer := malloc(1024)
    mem.track_alloc(1024)

    # Do work...

    free(buffer)
    mem.track_dealloc(1024)

    # Print report
    mem.report()

    0
}

Sampling Profiler

U std/profiler

F main() -> i64 {
    # Sample every 10ms
    sampler := SampleProfiler::new(10)
    sampler.start()

    # Run workload
    run_application()

    # Stop and analyze
    sampler.stop()
    sampler.analyze()

    0
}

Nested Profiling

U std/profiler

F outer() -> i64 {
    profile_begin("outer")

    inner()
    inner()

    profile_end("outer")
    0
}

F inner() -> i64 {
    profile_begin("inner")

    # Do work...
    compute()

    profile_end("inner")
    0
}

F main() -> i64 {
    get_profiler().enable()

    outer()

    get_profiler().report()

    0
}

Report Format

The report() method prints a table with the following columns:

• Name: Profile region name
• Calls: Number of times called
• Total(ms): Total time spent in milliseconds
• Avg(us): Average time per call in microseconds
• Min(us): Minimum time in microseconds
• Max(us): Maximum time in microseconds

Example output:

=== Profiling Report ===
Total time: 1543 ms

Name                          Calls      Total(ms)  Avg(us)   Min(us)   Max(us)
--------------------------------------------------------------------------------
compute                       1000000    1234       1         0         15
io_operation                  5000       309        61        50        150

Overview

The profiler module provides multiple profiling approaches:

1. Timer: Manual high-resolution timing for specific code sections
2. Profiler: Automatic instrumentation with enter/exit markers
3. MemoryProfiler: Track allocations, deallocations, and memory usage
4. SampleProfiler: Statistical profiling with periodic stack sampling
5. FlameGraphBuilder: Generate flame graph visualization data

All profilers use nanosecond-resolution timing and support nested/recursive profiling. The global profiler instances allow easy integration without passing profiler objects through the call chain.