RunMat
GitHub

View all functions

CategoryTiming

toc — Read the elapsed time since the most recent tic or an explicit handle.

toc returns the elapsed wall-clock time in seconds since the last matching tic, or since the tic handle you pass as an argument. It mirrors the stopwatch utilities that MATLAB users rely on for ad-hoc profiling and benchmarking.

How does the toc function behave in MATLAB / RunMat?

  • 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 MATLAB:toc:NoMatchingTic.
  • Passing anything other than a finite, non-negative scalar handle raises MATLAB:toc:InvalidTimerHandle.
  • The stopwatch uses a monotonic host clock, so measurements are immune to wall-clock adjustments.

GPU behavior

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 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 of using toc in MATLAB / RunMat

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

FAQ

What happens if I call toc before tic?

The builtin raises MATLAB: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.

See also

tic

Source & Feedback