profiler.lua File Reference

Go to the source code of this file.

Functions
	exampleConsolePrint ()
	Placeholder example function illustrating a custom console print callback.
module	setGetTimeFunction (fn)
	Override the timing function used by the profiler to measure elapsed time.
module	getInfo ()
	Return the internal profiler report cache and full report list for inspection.
module	attachPrintFunction (fn, verbose)
	Attach a custom print function to receive profiler output strings.
module	start ()
	Start a new profiling session and begin instrumenting function calls.
module	pause ()
	Pause an active profiling session without discarding collected data.
module	resume ()
	Resume profiling after a pause and accumulate the paused interval duration.
module	stop ()
	Stop the profiler and record the stop timestamp.
module	report (filename)
	Write the profiling report to a file, stopping profiling if not already stopped.
module	configuration (overrides)
	Modify the configuration of the profiler module programmatically.

Function Documentation

attachPrintFunction()

module attachPrintFunction	(	fn	,
		verbose	)

Attach a custom print function to receive profiler output strings.

Registers an external function that the profiler will call with string arguments during report generation. If verbose mode is enabled, the attached function is called for every output line written to the report file. Regardless of verbose setting, the total time summary line is always forwarded to the attached function. Pass nil as fn to detach a previously registered print function.

Parameters

fn	(function) The print callback to attach. Must accept a single string parameter
verbose	(boolean) If true, every report output line is forwarded to fn. Defaults to false

-- Attach a simple console printer
profiler.attachPrintFunction(print, false)
 
-- Attach a verbose logger that receives every output line
local function myLogger(msg)
    wx.wxLogMessage(msg)
end
profiler.attachPrintFunction(myLogger, true)

See also

module.report() where the attached function is invoked

Note

Documentation generated by AI on 2026-03-03

configuration()

module configuration

(

overrides

)

Modify the configuration of the profiler module programmatically.

Accepts a table of override values whose keys must match existing configuration parameter names. Invalid keys are reported via print(). Valid overrides are deep-copied before being applied to prevent external mutation. After applying overrides, column formatting patterns are rebuilt to reflect the new configuration.

Parameters

overrides

(table) Table of configuration overrides. Valid keys are: outputFile (string): Name of this profiler file (excluded from reports) emptyToThis (string): Replacement string for rows with no measurable time fW (number): Width of the file column in characters fnW (number): Width of the function name column in characters lW (number): Width of the line number column in characters tW (number): Width of the time taken column in characters rW (number): Width of the relative percentage column in characters cW (number): Width of the call count column in characters reportSaved (string): Confirmation text prefix for file output

-- Override file and function name column widths
local overrides = {
    fW = 100,   -- Change the file column to 100 characters (from 55)
    fnW = 120,  -- Change the function column to 120 characters (from 45)
}
profiler.configuration(overrides)
 
-- Change the placeholder for unmeasured functions
profiler.configuration({ emptyToThis = "N/A" })

Note

Invalid keys in the overrides table are reported to stdout but do not raise an error

Documentation generated by AI on 2026-03-03

exampleConsolePrint()

exampleConsolePrint

(

)

Placeholder example function illustrating a custom console print callback.

This function serves as a documentation example showing the expected signature and purpose of a user-defined print callback for use with module.attachPrintFunction(). It is not implemented and should be replaced with a real logging or console output function in the caller's codebase. The function must accept a single string parameter representing the output line produced by the profiler.

Note

This is an example stub only; it contains no implementation

See also

module.attachPrintFunction() to register a real implementation of this pattern

Note

Documentation generated by AI on 2026-03-03

getInfo()

module getInfo

(

)

Return the internal profiler report cache and full report list for inspection.

Provides direct access to the two primary internal data structures used by the profiler: reportCache (a table keyed by formatted title strings) and allReports (an ordered array of all report entries). This function is intended for debugging and programmatic inspection of raw profiling data without generating a report file.

Returns

(table) reportCache - table of report entries keyed by formatted title string

(table) allReports - ordered array of all report entry tables, each containing fields: title (string), count (number), timer (number), callTime (number)

Note

Data is only meaningful after a profiling session has been started and stopped

See also

module.report() to write this data to a formatted file instead

Note

Documentation generated by AI on 2026-03-03

pause()

module pause

(

)

Pause an active profiling session without discarding collected data.

Records the current timestamp as the pause start time and removes the debug hook, suspending function call instrumentation. The duration spent in the paused state is later subtracted from total elapsed time when module.resume() is called, ensuring paused intervals do not inflate profiling results.

Note

Call module.resume() to continue profiling; call module.stop() to end the session entirely

See also

module.resume() to continue profiling after a pause

module.stop() to end profiling entirely

Note

Documentation generated by AI on 2026-03-03

Referenced by SetXNegativeStrokePause(), SetXPositiveStrokePause(), SetZNegativeStrokePause(), and SetZPositiveStrokePause().

report()

module report

(

filename

)

Write the profiling report to a file, stopping profiling if not already stopped.

Sorts all collected function reports by descending execution time, then writes a formatted report to the specified file. The report includes total elapsed time, a formatted table of function call data, and a divider separating measurable from unmeasurable (near-zero time) entries. Functions belonging to the profiler itself and C functions are excluded from the output. If an attached print function exists, the total time and (if verbose) each output line are forwarded to it. The lessTime accumulated during any paused intervals is subtracted from the total time calculation.

Parameters

filename

(string) Path to the output report file. File is created or overwritten. If not provided, defaults to "profiler.log"

Returns

(nil) No return value; output is written directly to file

-- Write report to default location
profiler.start()
-- ... code to profile ...
profiler.stop()
profiler.report("profiler.log")
 
-- Write report to a custom path
profiler.report("C:\\Logs\\my_profile_report.log")

Note

If profiling has not been stopped before calling this function, stop() is called automatically

See also

module.stop() to explicitly stop profiling before reporting

module.attachPrintFunction() to mirror output to a custom logger

Note

Documentation generated by AI on 2026-03-03

resume()

module resume

(

)

Resume profiling after a pause and accumulate the paused interval duration.

Reinstates the debug hook to resume function call instrumentation. If a pause start time was recorded by module.pause(), the elapsed paused duration is added to the running lessTime accumulator so that paused intervals are excluded from the final total time calculation in the report. If resume() is called without a preceding pause(), the debug hook is still reinstated but no time adjustment is made.

Note

The accumulated lessTime is subtracted from total elapsed time in module.report()

See also

module.pause() to pause an active profiling session

module.stop() to end profiling entirely

Note

Documentation generated by AI on 2026-03-03

setGetTimeFunction()

module setGetTimeFunction

(

fn

)

Override the timing function used by the profiler to measure elapsed time.

Replaces the internal getTime function reference used to record call and return timestamps during profiling. By default the profiler uses wh.GetUsecTimestamp for microsecond precision. Supply a replacement function to use an alternative clock source, such as os.clock for millisecond precision or a custom high-resolution timer. The provided function must take no parameters and return a numeric timestamp.

Parameters

fn	(function) Replacement timing function. Must accept no parameters and return a comparable numeric value representing the current time

-- Switch to millisecond precision using os.clock
profiler.setGetTimeFunction(os.clock)
 
-- Use a custom high-resolution timer
profiler.setGetTimeFunction(myLib.getHighResTime)

Warning

The replacement function must be set before calling module.start(); changing the timing function mid-session will produce inconsistent elapsed time calculations

Note

Documentation generated by AI on 2026-03-03

start()

module start

(

)

Start a new profiling session and begin instrumenting function calls.

Clears all previously collected report data, resets counters, records the start timestamp, and installs a debug hook that fires on every function call and return event. If column formatting patterns have not yet been built, they are initialized before profiling begins. The lessTime accumulator used for pause/resume intervals is also reset to zero.

Note

Any data from a previous profiling session is discarded when start() is called

Warning

Installing the debug hook has a measurable performance overhead; results reflect instrumented execution time, not native execution time

See also

module.stop() to end the session

module.pause() to temporarily suspend instrumentation without losing data

module.report() to write collected data to a file

Note

Documentation generated by AI on 2026-03-03

stop()

module stop

(

)

Stop the profiler and record the stop timestamp.

Captures the current high-resolution timestamp as the stop time and removes the debug hook, halting all function call instrumentation. The recorded stop time is used by module.report() to compute total elapsed time. Calling stop() multiple times is safe but will overwrite the previous stop timestamp.

Note

Profiling data accumulated before stop() is called is preserved and available for reporting

See also

module.start() to begin a new profiling session

module.report() to write the collected data to a file

Note

Documentation generated by AI on 2026-03-03