toc — Return elapsed wall-clock time since the latest tic call or a specific tic handle.
toc returns elapsed wall-clock seconds since the latest tic or since an explicit opaque uint64 timer token.
Syntax
elapsed = toc()
elapsed = toc(timerVal)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
timerVal | NumericScalar | No | — | Handle returned by tic. |
Returns
| Name | Type | Description |
|---|---|---|
elapsed | NumericScalar | Elapsed time in seconds. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:toc:NoMatchingTic | toc() is called without a matching prior tic(). | toc: no matching tic |
RunMat:toc:InvalidTimerHandle | The timer handle is missing, malformed, non-finite, negative, or points to a future instant. | toc: invalid timer handle |
RunMat:toc:TooManyInputs | More than one input argument is supplied. | toc: too many input arguments |
How toc works
tocwithout inputs reads the latestticstart and returns elapsed seconds without consuming that timer.toc(t)accepts a handle previously produced byticand measures the time since that handle without altering the stack.- Calling
tocbeforeticraises the MATLAB-compatible error identifierRunMat:toc:NoMatchingTic. - The documented explicit input is the opaque
uint64token returned bytic. Other integer classes and malformed tokens raiseRunMat:toc:InvalidTimerHandle. - RunMat mode accepts timer tokens produced by older RunMat releases as double values. MATLAB compatibility modes require the documented
uint64form. - The stopwatch uses a monotonic host clock, so measurements are immune to wall-clock adjustments.
Does RunMat run toc on the GPU?
The stopwatch lives entirely on the host. toc never transfers tensors or consults acceleration providers, so there are no GPU hooks to implement. Expressions that combine toc with GPU-resident data gather any numeric operands back to the CPU before evaluating the timer logic, and the builtin is excluded from fusion plans entirely.
GPU memory and residency
No. Timing utilities never touch GPU memory. You can freely combine toc with code that produces or consumes gpuArray values—the stopwatch itself still executes on the CPU.
Examples
Measuring elapsed time since the last tic
tic;
pause(0.25);
elapsed = tocUsing toc with an explicit tic handle
token = tic;
heavyComputation();
elapsed = toc(token)Timing nested stages with toc
outer = tic; % Keep the outer timer token
stage1();
inner = tic; % Start a second stopwatch
stage2();
stage2Time = toc(inner);
totalTime = toc(outer)Printing elapsed time without capturing output
tic;
longRunningTask();
toc; % Displays the elapsed seconds because the result is not assignedMeasuring immediately with toc(tic)
elapsed = toc(tic); % Starts a timer and reads it right awayUsing toc with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how toc changes the result.
Run a small toc example, explain the result, then change one input and compare the output.
FAQ
What happens if I call toc before tic?⌄
The builtin raises RunMat:toc:NoMatchingTic, matching MATLAB's behaviour when no stopwatch start exists.
Does toc remove the matching tic?⌄
No. Both toc and toc(timerVal) are read operations, so repeated calls report increasing elapsed times from the same start.
Can I reuse a tic handle after calling toc(t)?⌄
Yes. Handles are deterministic timestamps, so you can call toc(handle) multiple times or store the handle in structures for later inspection.
Does toc print output?⌄
When you do not capture the result, the interpreter shows the elapsed seconds. Assigning the return value (or ending the statement with a semicolon) suppresses the display, just like in MATLAB.
Is toc affected by GPU execution or fusion?⌄
No. The stopwatch uses the host's monotonic clock. GPU acceleration, fusion, and pipeline residency do not change the measured interval.
How accurate is the reported time?⌄
toc relies on the same monotonic clock (runmat_time::Instant), typically offering microsecond precision on modern platforms. The actual resolution depends on your operating system.
Related Timing functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how toc is executed, line by line, in Rust.
- View the source for toc in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.