RunMat
GitHub

View all functions

CategoryTiming

tic — Start a high-resolution stopwatch and optionally return a handle for toc.

tic starts a high-resolution stopwatch. Calls to toc report the elapsed time in seconds. When you assign the return value (for example, t = tic;), the resulting handle can be passed to toc(t) to measure a different code region while keeping the global stopwatch untouched.

How does the tic function behave in MATLAB / RunMat?

  • Uses the host's monotonic clock for nanosecond-resolution timing.
  • Supports nested timers: each call pushes a new start time on an internal stack. toc without inputs always reads the most recent tic and removes it, leaving earlier timers intact so outer scopes continue measuring.
  • Returns an opaque scalar handle (a double) that encodes the monotonic timestamp. The handle can be stored or passed explicitly to toc.
  • Executes entirely on the CPU. There are no GPU variants because tic interacts with wall-clock state.
  • Calling toc before tic raises the MATLAB-compatible error MATLAB:toc:NoMatchingTic.

Examples of using tic in MATLAB / RunMat

Measuring a simple loop

tic;
for k = 1:1e5
    sqrt(k);
end
elapsed = toc

Capturing and reusing the tic handle

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

Nesting timers for staged profiling

tic;              % Outer stopwatch
stage1();         % Work you want to measure once
inner = tic;      % Nested stopwatch
stage2();
innerT = toc(inner);  % Elapsed time for stage2 only
outerT = toc;         % Elapsed time for everything since the first tic

Measuring asynchronous work

token = tic;
future = backgroundTask();
wait(future);
elapsed = toc(token)

Resetting the stopwatch after a measurement

elapsed1 = toc(tic);  % Equivalent to separate tic/toc calls
pause(0.1);
elapsed2 = toc(tic);  % Starts a new timer immediately

FAQ

Does tic print anything when called without a semicolon?

No. tic is marked as a sink builtin, so scripts do not display the returned handle unless you assign it or explicitly request output.

Is the returned handle portable across sessions?

No. The handle encodes a monotonic timestamp that is only meaningful within the current RunMat process. Passing it to another session or saving it to disk is undefined behaviour, matching MATLAB.

Can I run tic on a worker thread?

Yes. Each thread shares the same stopwatch stack. Nested tic/toc pairs remain well-defined, but you should serialise access at the script level to avoid interleaving unrelated timings.

How accurate is the measurement?

tic relies on a monotonic clock (via runmat_time::Instant), typically providing microsecond or better precision. The actual resolution depends on your operating system. There is no artificial jitter or throttling introduced by RunMat.

Does tic participate in GPU fusion?

No. Timer builtins are tagged as CPU-only. Expressions containing tic are always executed on the host, and any GPU-resident tensors are gathered automatically by surrounding code when necessary.

See also

toc, timeit

Source & Feedback