`tic` — Start a high-resolution stopwatch timer and optionally return a handle for paired `toc` reads.

tic starts a high-resolution stopwatch used by toc to report elapsed wall-clock seconds. Captured handles from t = tic can be passed to toc(t) for independent timing scopes, matching MATLAB semantics.

Syntax

timerVal = tic()

Returns

Name	Type	Description
`timerVal`	`NumericScalar`	Timer handle used by toc.

Errors

Identifier	When	Message
`RunMat:tic:StateLockFailed`	Internal stopwatch state cannot be acquired.	`tic: failed to acquire stopwatch state`

How `tic` works

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 RunMat:toc:NoMatchingTic.

Examples

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

Using `tic` with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how tic changes the result.

Run a small tic example, explain the result, then change one input and compare the output.

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.

pause · timeit · toc

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how tic is executed, line by line, in Rust.

View the source for tic 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

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