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
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
f | Any | Yes | — | Zero-input function handle to benchmark. |
numOutputs | IntegerScalar | No | 1 | Requested output count for invoking the benchmarked handle. |
Returns
| Name | Type | Description |
|---|---|---|
t | NumericScalar | Median execution time per invocation in seconds. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:timeit:TooManyInputs | More than two input arguments are supplied. | timeit: too many input arguments |
RunMat:timeit:NumOutputsScalar | numOutputs is not a scalar numeric/integer value. | timeit: numOutputs must be a scalar numeric value |
RunMat:timeit:NumOutputsFinite | numOutputs is NaN or infinite. | timeit: numOutputs must be finite |
RunMat:timeit:NumOutputsNonnegative | numOutputs is negative. | timeit: numOutputs must be a nonnegative integer |
RunMat:timeit:NumOutputsInteger | numOutputs has a non-integer numeric value. | timeit: numOutputs must be an integer value |
RunMat:timeit:EmptyFunctionHandle | A function-handle string or payload is empty after trimming. | timeit: empty function handle string |
RunMat:timeit:ExpectedAtHandleString | A string/char function handle does not begin with '@'. | timeit: expected a function handle string beginning with '@' |
RunMat:timeit:HandleKind | Function handle argument is not a scalar string/char or callable handle value. | timeit: function handle must be a string scalar or function handle |
RunMat:timeit:FirstArgKind | First argument is not a function handle value. | timeit: first argument must be a function handle |
How timeit works
- Executes
frepeatedly, 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. - Leaves GPU residency untouched—if
flaunches GPU kernels, they execute on the active provider. Insertwait(gpuDevice)inside the handle if you need explicit synchronisation.
Examples
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)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 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). The runtime requests three outputs from the handle and discards the returned values. Native integer output counts are available in runmat compatibility mode.
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 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.
Is there a limit on runs?⌄
Yes. timeit caps the inner loop at about one million iterations to avoid runaway measurements.
Related Timing functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. 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 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.