profile_start

Builtin index · REPL & diagnostics

profile_start()

Input: no input · Output: no output

What it is

Takes no arguments. Starts a named profiling window and returns a Record handle -- t0 (wall-clock seconds) and mem0 (RSS bytes, NaN if unsupported) -- to pass unmodified to profile_end. t0/mem0 are semi-internal (read by profile_end, not meant to be inspected directly); mem0 is NaN on a platform current_rss_bytes doesn't support (anything but Windows/Linux). Because the handle is an ordinary value rather than mutated global state (unlike tic), multiple windows — p1 = profile_start(), p2 = profile_start() — can overlap or nest without clobbering each other. Uses SystemTime rather than a monotonic clock, trading tic/toc's clock-step immunity for a value that can round-trip through a Record field — prefer tic/toc for sub-millisecond or clock-step-sensitive timing. See also timer/preciseTimer above for a controllable object, and profiling_mode/profile_stats below for per-builtin call-count and time attribution (no memory) across a whole recording window instead of one region's time and memory.

Overloads

One call shape — this function is not overloaded.

Examples

No documentation example calls this form yet. The REPL & diagnostics chapter is where one belongs.

How it works

profile_start()/profile_end(handle) -- a named-window counterpart to tic/toc above. tic/toc are a single global lap timer (one self.tic_start field), which is fine for timing one thing at a time but can't have two windows open at once. profile_start() returns a plain Record instead of mutating interpreter state, so prof1 = profile_start() and prof2 = profile_start() can overlap or nest without clobbering each other -- ordinary Qu values, not a second global. Wall-clock time is captured via SystemTime, not Instant: Instant has no defined epoch and can't round-trip through a Value::Num, which a Record field must be. That trades away tic/toc's monotonic-clock guarantee (a clock step during the window can skew the reading) for being a plain value -- fine at the seconds-scale this is meant for; use tic/toc for sub-millisecond or clock-step-sensitive timing. Memory is process RSS (resource::current_rss_bytes, shared with qu-cli's --profile/--max-memory watchdog) sampled once at each end, not polled -- a single huge allocation that also frees before the matching profile_end call is invisible to this, same coarse-sampling trade-off qu-cli's own resource monitor documents for itself. .mem is NaN on a platform current_rss_bytes doesn't support (anything but Windows/Linux), never a fabricated number.

From the note above this builtin in the interpreter, where the reasoning was written down as it was built.