Iprof

Logs a report as text: a title line, a header, then one line per zone with its self time and hierarchical time in milliseconds, its call count and its heat. Rows below min_self_time or min_hier_time (milliseconds, 0 for all) are skipped.

#import "Iprof"(IMPORT_MODE = .CLIENT, MANUAL_MODE = true, USE_GRAPHICS = false, DO_HISTORY = false);

main :: () {
    Prof_init_highlevel();
    zones[0].name = "work";
    zones[0].initted = true;
    zone_begin(0);
    zone_end();
    update(true);
    log_text_report(create_report());
}

Writes a report to filename as CSV: the command line, then name,self (ms),hier (ms),calls per zone. A name with a quote or a comma is quoted. A failed write logs an error.

#import "Iprof"(IMPORT_MODE = .CLIENT, MANUAL_MODE = true, USE_GRAPHICS = false, DO_HISTORY = false);

main :: () {
    Prof_init_highlevel();
    zones[0].name = "work";
    zones[0].initted = true;
    zone_begin(0);
    zone_end();
    update(true);
    save_csv_report(create_report(), "profile.csv");
}

Chooses which smoothing speed get_value reads: 0 reacts fastest, higher numbers average over more frames.

Resets the smoothed values and variances to zero.

The smoothed value at the speed set with set_smoothing.

Picks what the report and overlay show for each zone.

#import "Iprof"(IMPORT_MODE = .CLIENT, MANUAL_MODE = true, USE_GRAPHICS = false, DO_HISTORY = false);

main :: () {
    set_report_mode(.HIERARCHICAL_TIME);
    assert(displayed_quantity == .HIERARCHICAL_TIME);
}

How many times zone already appears on the open-zone stack above stack.

Starts the clock and the zone tables. Everything that needs them calls it first, so calling it yourself is optional.

Opens a zone and returns its node in the call tree.

Opens the zone in slot zone_index of zones (manual mode). Close it with zone_end(). The slot needs a name and initted = true first. Time until the matching zone_end counts toward the zone, and toward its parent for the hierarchical time.

#import "Iprof"(IMPORT_MODE = .CLIENT, MANUAL_MODE = true, USE_GRAPHICS = false, DO_HISTORY = false);

main :: () {
    zones[0].name = "work";
    zones[0].initted = true;
    zone_begin(0);
    // ... the code to time ...
    zone_end();
}

Closes the zone most recently opened with zone_begin. Calling it with no zone open fails an assert.

#import "Iprof"(IMPORT_MODE = .CLIENT, MANUAL_MODE = true, USE_GRAPHICS = false, DO_HISTORY = false);

main :: () {
    zones[0].name = "outer";
    zones[0].initted = true;
    zones[1].name = "inner";
    zones[1].initted = true;

    zone_begin(0);
    zone_begin(1);
    zone_end();  // closes "inner"
    zone_end();  // closes "outer"
}

The hash-table key of a zone under a given parent.

Makes a call tree node for zone under parent.

Adds a node to the zone hash table, growing the table when it is half full.

Resets the zone hash table to size slots, which must be a power of two. It fails while a zone is open.

Starts the profiling runtime at the top of main.

Calls func on every node of the call tree.

Sets up the frame history and the report state. Call it once before the first update. update and create_report call it too, so calling it twice is fine.

#import "Iprof"(IMPORT_MODE = .CLIENT, MANUAL_MODE = true, USE_GRAPHICS = false, DO_HISTORY = false);

main :: () {
    Prof_init_highlevel();
    Prof_init_highlevel();  // calling it again does nothing
}

Folds new_value into a smoothed value, one factor per smoothing speed.

Sets every smoothing speed of a value at once, so it starts at new_value instead of easing in.

Zeroes a node's totals for the next frame.

Adds a node's self time to the frame total.

Files a node's totals for the frame into its smoothed history.

Adds a node's self time to the hierarchical time of each ancestor, counting a recursive zone once.

How uneven a value is over time, from 0 (steady) to 1 (jumpy), as its spread relative to its mean.

Orders two rows by one of the report's columns, largest first, then by name.

Orders rows of the expanded call graph view.

Adds a node's figures into its zone's row of the report.

Adds a node's figures into the rows of the expanded call graph view.

Builds a report of the frames recorded by update: one row per zone, in the current Report_Mode. The report lives in temporary storage, so print or save it before the next reset_temporary_storage. Rows of zones that were never called, or never initted in manual mode, are left out when printed.

#import "Iprof"(IMPORT_MODE = .CLIENT, MANUAL_MODE = true, USE_GRAPHICS = false, DO_HISTORY = false);

main :: () {
    Prof_init_highlevel();
    zones[0].name = "work";
    zones[0].initted = true;
    zone_begin(0);
    zone_end();
    update(true);

    report := create_report();
    assert(report.records.count == 1);
    assert(report.records[0].name == "work");
}

Moves the overlay's highlighted row to row num.

Moves the highlighted row by num rows. The cursor is clamped when the report is built.

Shows the frame num frames back in the history, clamped to the history's length.

Steps the shown frame by delta: positive goes forward in time, negative back.

Opens the call graph of the zone under the cursor.

Moves the selection to the parent of the selected zone in the call graph.

Opens a zone for the rest of the enclosing procedure. The plugin inserts it; a client program uses it to time a procedure without writing zone_end.

Opens zone index and closes it when the procedure returns, unless a profiler call is already running.

Creates the metaprogram plugin that +Iprof loads.

Reads the plugin options (-csv, -min_size, -modules) and prepares the plugin.

Asks the compiler to send procedure bodies to the plugin.

Adds the profiling runtime to the program being compiled.

Handles one compiler message: instruments the procedure bodies that are big enough.

Adds a call to the user's hook next to Iprof's own at a point in the program's life.

Does nothing; the work happens in message and shutdown.

Adds the final report code to the program once the compile is over.

Prints the plugin's options.

Tells the overlay where the mouse is, so it can highlight the row under it.

The graph scale in use for the current report mode.

Shows the frame the mouse is over in the graph.

Draws the report as an overlay with its top left corner at x, y, using the callbacks in config. Call it every frame after update.

#import "Math";
#import "Iprof"(IMPORT_MODE = .CLIENT, MANUAL_MODE = true, DO_HISTORY = true);

config: Config;
config.draw_text = (x: float, y: float, text: string, color: Vector4) { /* draw with your renderer */ };
config.text_width = (text: string) -> float { return 8.0 * text.count; };
config.draw_rectangle = (x0: float, y0: float, x1: float, y1: float, color: Vector4) { /* ... */ };

update(true);
draw(10, 10, 400, 300, *config);

Draws the history graph of the selected zone inside the given rectangle.

How the module is imported. METAPROGRAM makes it a plugin that instruments your code; CLIENT pulls the profiling runtime into the program.

What a report shows for each zone: time spent in the zone itself, time including its callees, call counts, or the call graph.

The table create_report builds: a title, column headers and one Report_Row per zone.

One zone's line in a report: its name, self and hierarchical time in seconds, and its call count.

Where a zone came from in the source, as the plugin records it.

The last NUM_FRAME_SLOTS values of one zone quantity, for the overlay's graph.

A named piece of code to time. In manual mode, fill name and set initted in a slot of zones.

A smoothed value with its variance and a short history. It holds the same measure at several smoothing speeds.

The vertical scale the overlay's graphs are drawn at, and how fast it eases toward a new target.

Where a graph sits on screen: origin and size.

The smoothed self time, hierarchical time and call count of one zone in the call tree.

The running totals of one zone in one place of the call tree (the same zone under another parent is a separate node).

How the overlay draws: the callbacks that draw text, rectangles and lines, the sizes of the font, and the colours. Fill in draw_text, text_width and draw_rectangle at least; the others have do-nothing defaults.