`timer` — Create a MATLAB-compatible timer handle object.

timer creates a handle object with MATLAB timer properties and method dispatch for start, startat, stop, wait, and delete. RunMat stores timers in a per-thread registry so timerfind and timerfindall can retrieve them while valid.

Syntax

t = timer
t = timer(Name, Value, ...)

Inputs

Name	Type	Required	Default	Description
`Name,Value`	`Any`	Variadic	—	Timer properties such as TimerFcn, StartDelay, Period, ExecutionMode, Name, Tag, and UserData.

Returns

Name	Type	Description
`t`	`Any`	Timer handle object.

Errors

Identifier	When	Message
`RunMat:timer:InvalidInput`	A timer argument, property, or callback value has an unsupported type.	`timer: invalid input`
`RunMat:timer:InvalidProperty`	A timer property name is unknown, read-only, or has an invalid value.	`timer: invalid property`
`RunMat:timer:InvalidHandle`	A lifecycle method receives a non-timer or invalid timer handle.	`timer: invalid timer handle`
`RunMat:timer:CallbackFailed`	A timer callback fails.	`timer: callback failed`
`RunMat:timer:GcFailure`	A timer object cannot be allocated, rooted, read, or mutated.	`timer: object storage failed`

How `timer` works

t = timer creates a valid timer handle with defaults: ExecutionMode='singleShot', Period=1, StartDelay=0, TasksToExecute=1, BusyMode='drop', ObjectVisibility='on', Running='off', TasksExecuted=0, Type='timer', and a generated Name.
t = timer(Name, Value, ...) accepts common callback, timing, labeling, and user-data properties: TimerFcn, StartFcn, StopFcn, ErrorFcn, Period, StartDelay, TasksToExecute, BusyMode, ExecutionMode, Name, Tag, ObjectVisibility, and UserData.
Callback properties accept strings, character rows, function handles, closures, or callback cell arrays for property compatibility. This slice executes function-handle, closure, and callback-cell callbacks; non-empty text callbacks are rejected at execution time because they require dynamic-eval callback infrastructure.
start(t) validates TimerFcn, marks Running='on', executes StartFcn, executes TimerFcn once for singleShot or TasksToExecute times for fixed execution modes, updates TasksExecuted, InstantPeriod, and AveragePeriod, then executes StopFcn and marks Running='off'.
startat(t, delaySeconds) is supported for numeric positive relative delays. MATLAB date/time and date-string start times are not yet implemented.
stop(t) marks the timer stopped and runs StopFcn if the timer was running. wait(t) returns after the timer is stopped. delete(t) invalidates the handle, removes it from timer discovery, and releases its GC root.
RunMat executes timer callbacks synchronously on the current VM path rather than on a background event queue. Long delays therefore block the caller on native hosts. This preserves deterministic behavior across native and wasm hosts, but it is not full MATLAB asynchronous scheduling.
Multiple timers are represented as a cell row because RunMat does not yet have first-class MATLAB object arrays.

Does RunMat run `timer` on the GPU?

timer is a control-flow and callback object. It gathers no tensors, allocates no GPU buffers, and does not participate in fusion.

Examples

Create and start a one-shot timer

t = timer('TimerFcn', @(src, evt)disp("tick"));
start(t)

Find a timer by tag

t = timer('Tag', 'batch', 'TimerFcn', @tick);
found = timerfind('Tag', 'batch')

Using `timer` with coding agents

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

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

FAQ

Does RunMat run timers in the background?⌄

No. Timer callbacks run synchronously when start drives the timer. Background scheduling and a MATLAB-compatible timer event queue require additional runtime infrastructure.

Can timer callbacks use GPU arrays?⌄

Yes, when the callback body calls GPU-capable builtins. The timer object itself is host-side control flow and has no GPU kernel.

cputime · pause · tic · timeit · timerfind · timerfindall · toc

Open-source implementation

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

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

timer — Create a MATLAB-compatible timer handle object.