`timeit` — Measure the execution time of a zero-argument function handle.

t = timeit(f) evaluates the zero-argument function handle f repeatedly and returns the median runtime (in seconds). RunMat accepts the optional numOutputs argument for MATLAB compatibility; today the handle executes with its default output arity (or none when you pass 0) and all returned values are discarded.

Syntax

t = timeit(f)
t = timeit(f, numOutputs)

f is a zero-argument function handle (for example, @() myOp(A)).
numOutputs is an optional nonnegative integer kept for MATLAB compatibility. Passing 0 suppresses outputs entirely; any other value currently executes the handle with its default output arity while discarding the result.

How does the `timeit` function behave in MATLAB / RunMat?

Executes f repeatedly, adjusting the inner loop count until a single batch takes at least a few milliseconds or the function is slow enough.
Collects multiple samples (at least seven batches) and returns the median per-invocation time, which is robust against outliers.
Drops the outputs produced by f; you should perform any validation that depends on those outputs inside the handle. Multi-output dispatch will route through this helper once the runtime exposes multi-return feval.
Leaves GPU residency untouched—if f launches GPU kernels, they execute on the active provider. Insert wait(gpuDevice) inside the handle if you need explicit synchronisation.

Examples of using `timeit` in MATLAB / RunMat

Timing a simple anonymous function

f = @() sin(rand(1000, 1));
t = timeit(f)

Comparing two implementations

A = rand(1e5, 1);
slow = @() sum(A .* A);
fast = @() sumsq(A);

slowTime = timeit(slow);
fastTime = timeit(fast)

Timing a function that returns no outputs

logMessage = @() fprintf("Iteration complete\n");
t = timeit(logMessage, 0)

Timing a multiple-output function

svdTime = timeit(@() svd(rand(256)), 3)

Measuring GPU-bound work

gfun = @() gather(sin(gpuArray.rand(4096, 1)));
tgpu = timeit(gfun)

Timing a preallocation helper

makeMatrix = @() zeros(2048, 2048);
t = timeit(makeMatrix)

FAQ

What does `timeit` return?

— A scalar double containing the median runtime per invocation in seconds.

How many runs does `timeit` perform?

— It automatically selects a loop count so each batch lasts a few milliseconds, collecting at least seven batches.

Does `timeit` synchronise GPU kernels?

— No. Insert wait(gpuDevice) inside the handle when you need explicit synchronisation.

Can I time functions that require inputs?

— Yes. Capture them in the handle, for example timeit(@() myfun(A, B)).

How do I time a function with multiple outputs?

— Pass timeit(@() svd(A), 3) to mirror MATLAB’s call signature. RunMat currently ignores values greater than zero until multi-output dispatch lands, but the handle still executes.

Why do successive runs differ slightly?

— Normal system jitter, cache effects, and GPU scheduling can change runtimes slightly; the median mitigates outliers.

Can `timeit` time scripts?

— Wrap the script body in a function handle so it becomes zero-argument, then call timeit on that handle.

Does `timeit` participate in fusion or JIT tiers?

— It simply executes the provided handle; any tiering or fusion happens inside the timed function.

What happens if the function errors?

— The error is propagated immediately and timing stops, matching MATLAB behaviour.

Is there a limit on runs?

— Yes. timeit caps the inner loop at about one million iterations to avoid runaway measurements.

Source & Feedback

Source code: `crates/runmat-runtime/src/builtins/timing/timeit.rs`
Found a bug? Open an issue with a minimal reproduction.

timeit — Measure the execution time of a zero-argument function handle.