RunMat
GitHub

View all functions

CategoryTiming

What does the toc function do in MATLAB / RunMat?

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.

toc Function GPU Execution Behaviour

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.

Examples of using the toc function in MATLAB / RunMat

Measuring elapsed time since the last tic

tic;
pause(0.25);
elapsed = toc;

elapsed contains the seconds since the tic. The matching stopwatch entry is removed automatically.

Using toc with an explicit tic handle

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

Passing the handle makes toc leave the global stopwatch stack untouched, so earlier timers keep running.

Timing nested stages with toc

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

stage2Time measures only the inner section, while totalTime spans the entire outer region.

Printing elapsed time without capturing output

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

When you omit an output argument, RunMat displays the elapsed seconds in the console. Add a semicolon or capture the result to suppress the text, mirroring MATLAB's default command-window behaviour.

Measuring immediately with toc(tic)

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

This idiom is equivalent to separate tic/toc calls, and the stopwatch entry created by the inner tic remains on the stack for later use.

GPU residency in RunMat (Do I need gpuArray?)

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.

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 std::time::Instant, typically offering microsecond precision on modern platforms. The actual resolution depends on your operating system.

See Also

tic

Source & Feedback