`toc` — Return elapsed wall-clock time since the latest `tic` call or a specific `tic` handle.

toc reads elapsed wall-clock seconds since the most recent global tic or since an explicit tic handle argument. It follows MATLAB-compatible stopwatch timing workflows.

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

toc without inputs pops the most recent tic from the stopwatch stack and returns the elapsed seconds.
toc(t) accepts a handle previously produced by tic and measures the time since that handle without altering the stack.
Calling toc before tic raises the MATLAB-compatible error identifier RunMat:toc:NoMatchingTic.
Passing anything other than a finite, non-negative scalar handle raises RunMat:toc:InvalidTimerHandle.
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 = toc

Using toc with an explicit tic handle

token = tic;
heavyComputation();
elapsed = toc(token)

Timing nested stages with toc

tic;          % Outer stopwatch
stage1();
inner = tic;  % Nested stopwatch
stage2();
stage2Time = toc(inner);
totalTime = toc

Printing elapsed time without capturing output

tic;
longRunningTask();
toc;   % Displays the elapsed seconds because the result is not assigned

Measuring immediately with toc(tic)

elapsed = toc(tic);  % Starts a timer and reads it right away

Using `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?⌄

Yes when called without arguments. The most-recent stopwatch entry is popped so nested timers unwind in order. When you pass a handle (toc(t)), the stack remains unchanged and you may reuse the handle multiple times.

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.

pause · tic · timeit

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.

Getting started · Benchmarks · Pricing

toc — Return elapsed wall-clock time since the latest tic call or a specific tic handle.