addlistener — Register a callback on a handle-object event.
listener = addlistener(target,event_name,callback) registers a callback with the current runtime event registry and returns a listener value. Registration occurs even when the result is discarded.
Syntax
listener = addlistener(target, event_name, callback)
addlistener(target, event_name, callback)Inputs
target- Type
Any- Required
- Yes
- Default
- —
- Description
- Live handle-object event source.
event_name- Type
StringScalar- Required
- Yes
- Default
- —
- Description
- Case-sensitive event name.
callback- Type
Any- Required
- Yes
- Default
- —
- Description
- Function handle or textual callback reference.
Returns
listener- Type
Any- Description
- Registered listener value.
Errors
RunMat:AddListenerTargetInvalid- When
- Target is not a live handle object.
- Message
addlistener: target must be a valid handle object
RunMat:addlistener:TooManyOutputs- When
- More than one output is explicitly requested.
- Message
addlistener: expected at most one output
RunMat:AddListenerAllocationFailed- When
- GC rooting or listener allocation fails before registration.
- Message
addlistener: failed to retain listener target or callback
Receiver and callback
The receiver must be a live handle object. Event names are case-sensitive text. The callback may be a bound function handle, closure, supported named handle, or textual function reference. Text references are resolved through the current semantic function catalog when possible; callback invocation occurs later in notify.
The event registry retains explicit GC roots for target and callback until registration invalidation. The current implementation does not verify that the class declared the event or that the callback signature matches at registration time.
Numeric or GPU-resident values are not direct target, event-name, or callback controls. Values captured by a callback remain under that callback's ordinary ownership rules and are not gathered by addlistener.
Execution and output
Native and browser hosts use the context-owned event registry. Registration is a host mutation and a fusion boundary, not a GPU kernel or automatically replayable operation. A worker's independent object registry does not inherit the originating listener.
At most one output is available; a zero-output statement still registers the listener. Current listener invalidation and target lifetime are managed by the runtime's listener/GC services.
Example
Register an event callback
h = new_handle_object('EventTarget'); listener = addlistener(h, 'Changed', @disp);Using addlistener with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how addlistener changes the result.
Run a small addlistener example, explain the result, then change one input and compare the output.
FAQ
Does registration invoke the callback?⌄
No. notify invokes enabled, valid listeners in registry order; registration only retains the target and callback.
Related Introspection functions
addParameter · addprop · assignin · builtin · cancel · class · clear · clearAllMemoizedCaches · clearCache · clearvars · dbclear · dbstack · dbstatus · dbtype · eval · evalc · evalin · feval · findprop · func2str · functions · get.p · getcallinfo · getmethod · inputname · inputParser · isa · ischar · isdeployed · iskeyword · ismethod · isobject · isstring · isUnderlyingType · isvalid · keyboard · loadobj · localfunctions · matlab.metadata.DynamicProperty.delete · memoize · metaclass · mfilename · mislocked · mlock · munlock · namelengthmax · narginchk · nargoutchk · new_object · notify · numArgumentsFromSubscript · onCleanup · parse · saveobj · set.p · stats · str2func · subsasgn · subsref · superclasses · underlyingType · verLessThan · version · which · who · whos
Source you can read
Every RunMat function's source is public. Read exactly how addlistener is executed, line by line, in Rust.
- View the source for addlistener 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.