timeit — Measure function-handle execution time by repeated evaluation.
t = timeit(f) repeatedly evaluates zero-argument function handle f and returns the median execution time in seconds. The optional output count controls how many outputs are requested from each invocation.
Syntax
t = timeit(f)
t = timeit(f, numOutputs)Inputs
f- Type
Any- Required
- Yes
- Description
- Zero-input function handle to benchmark.
numOutputs- Type
IntegerScalar- Required
- No
- Default
1- Description
- Requested output count for invoking the benchmarked handle.
Returns
t- Type
NumericScalar- Description
- Median execution time per invocation in seconds.
Errors
RunMat:timeit:ContextUnavailable- When
- No invocation timing context is installed.
- Message
timeit: runtime context is unavailable
RunMat:timeit:TooManyInputs- When
- More than two input arguments are supplied.
- Message
timeit: too many input arguments
RunMat:timeit:NumOutputsScalar- When
- numOutputs is not a scalar numeric/integer value.
- Message
timeit: numOutputs must be a scalar numeric value
Behavior
The callback is warmed once, then evaluated in calibrated batches. At least seven batches contribute per-invocation samples; the median reduces outlier sensitivity.
Callback results are discarded. Validate their contents inside the handle if required.
The invocation's monotonic timing service measures the callback. timeit itself has no GPU kernel or fusion operation; work inside the handle keeps its existing provider and residency behavior. For asynchronous GPU work, synchronize inside the handle when that work must be included.
A callback error propagates immediately. Cancellation abandons the pending callback and does not replay an already completed invocation.
A typed-integer numOutputs and explicitly GPU-resident output count are separately gated RunMat extensions; ordinary nonnegative integer-valued double input is portable.
Examples
Time a simple anonymous function
f = @() sin(rand(1000, 1));
t = timeit(f)Compare two implementations
A = rand(1e5, 1);
slow = @() sum(A .* A);
fast = @() sumsq(A);
slowTime = timeit(slow);
fastTime = timeit(fast)Time a function with no requested outputs
logMessage = @() fprintf('Iteration complete\n');
t = timeit(logMessage, 0)Request multiple callback outputs
svdTime = timeit(@() svd(rand(256)), 3)Measure GPU-bound work
gfun = @() gather(sin(gpuArray.rand(4096, 1)));
tgpu = timeit(gfun)Time a preallocation helper
makeMatrix = @() zeros(2048, 2048);
t = timeit(makeMatrix)Using timeit with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how timeit changes the result.
Run a small timeit example, explain the result, then change one input and compare the output.
FAQ
What does timeit return?⌄
A scalar double containing the median runtime per invocation in seconds.
How many runs does timeit perform?⌄
It selects a loop count so batches last a few milliseconds, then collects at least seven batches.
Does timeit synchronize GPU kernels?⌄
No. Synchronize inside the handle when the timed operation needs it.
Can I time functions that require inputs?⌄
Yes. Capture them in the handle, for example timeit(@() myfun(A, B)).
How do I time multiple outputs?⌄
Pass timeit(@() svd(A), 3). RunMat requests three callback outputs and discards them. Typed-integer counts require RunMat compatibility mode.
Why do successive runs differ?⌄
System jitter, cache effects, and GPU scheduling vary; the median mitigates outliers.
Can timeit time scripts?⌄
Wrap the script body in a zero-argument function handle.
Does timeit participate in fusion or JIT tiers?⌄
It executes the provided handle; tiering or fusion happens inside that function.
What happens if the function errors?⌄
The error propagates immediately and timing stops.
Is there a limit on runs?⌄
Yes. The inner loop is capped at about one million iterations.
Related Timing functions
cputime · pause · set.BusyMode · set.ErrorFcn · set.ExecutionMode · set.Name · set.ObjectVisibility · set.Period · set.StartDelay · set.StartFcn · set.StopFcn · set.Tag · set.TasksToExecute · set.TimerFcn · set.UserData · tic · timer · timerfind · timerfindall · toc
Source you can read
Every RunMat function's source is public. Read exactly how timeit is executed, line by line, in Rust.
- View the source for timeit in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.