ishandle — Test whether a value identifies a live graphics-registry handle.
ishandle queries the live RunMat graphics registry and returns a host logical result. Exact graphics receiver objects are authenticated by their retained registry lease, not by their class-name text or a reusable numeric identifier. Numeric aliases use the existing graphics handle encoding; zero denotes the root. Invalid, retired, and non-graphics candidates return false.
Syntax
tf = ishandle(h)Inputs
h- Type
Any- Required
- Yes
- Default
- —
- Description
- Graphics receiver object, numeric handle alias, or another value to test.
Returns
tf- Type
LogicalArray- Description
- Host logical validity mask for numeric handle arrays, or a scalar logical for other candidates.
Errors
RunMat:ishandle:InvalidArgument- When
- The input count is not exactly one.
- Message
ishandle: invalid argument
RunMat:ishandle:TooManyOutputs- When
- More than one output is requested.
- Message
ishandle: too many output arguments
Accepted forms and shapes
ishandle(h) accepts any candidate value. Host real numeric tensors, including native single and all integer storage classes, produce logical arrays with the original full shape, including rank-zero, rank-one and empty dimensions. Numeric scalar carriers return scalar logical.
Other host values, including sparse matrices, logical arrays, complex values, strings, cells and non-graphics objects, produce scalar false rather than an elementwise mask. This is the bounded current RunMat representation, not a claim of complete MATLAB object-array parity.
A valid graphics receiver object returns scalar true while its exact lease is registered; closing, clearing, or replacing its registry owner makes the old object false even if a numeric identifier is reused.
ishandle currently queries the graphics registry only. It is not a generic validity test for arbitrary user handle classes, parallel handles or other non-graphics objects; use the corresponding domain operation for those values.
Integer aliases and compatibility
Interpreting typed integers as encoded graphics aliases is a declared RunMat-only extension. The original native integer value is read without a floating mirror; only nonnegative integers exactly representable in the graphics encoding are candidates. Negative and nonrepresentable integers return false.
With RunMat extensions disabled, integer scalars return scalar false and integer tensors return same-shaped false. No extension exception is raised by this predicate. Floating numeric aliases retain the existing RunMat registry semantics.
Placement, authority and remaining limits
Resident tensors are not graphics objects: only their shape metadata is inspected, with no provider selection, download, kernel, input retirement or replay. The host result is a same-shaped false logical array, except a one-element resident input publishes scalar false. The operation is a fusion boundary, not an accelerated reduction.
The Runtime binding retains the actual selected context and borrowed argument owner, validates output demand before work, and fences cancellation and finite-allocation authority through the existing graphics admission owner. Finite mask, selector and registry snapshot ownership remains incomplete: Managed calls fail closed rather than allocating unowned storage.
The predicate observes mutable graphics state and therefore is not a pure constant-foldable query. It creates no figure or renderer by itself. Portable root/invalid examples need no display; examples that construct real charts require an actual graphics host. NativeAndWasm denotes source/link portability, not fresh browser-cooperation or desktop-presentation qualification.
Examples
Test root and invalid numeric aliases without opening a figure
tf = ishandle([0 NaN -1]);Retain empty dimensions in a numeric candidate array
h = zeros(2,0,3); tf = ishandle(h);Recognize live graphics and reject retired aliases
f = figure(); h = plot(1:3); live = ishandle(h); close(f); retired = ishandle(h); replacement = figure();Read integer aliases exactly under RunMat extension policy
h = int64([0 -1]); tf = ishandle(h);Using ishandle with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how ishandle changes the result.
Run a small ishandle example, explain the result, then change one input and compare the output.
FAQ
Does this predicate create or revive graphics objects?⌄
No. It observes the current registry. An invalid placeholder or retired receiver stays invalid; a newly created object must supply its own live authority.
Are resident numeric values downloaded to inspect potential handles?⌄
No. Resident inputs return a host false mask using only shape metadata; no acceleration provider is invoked.
Related Plotting functions
2D Charts
area · bar · errorbar · heatmap · hist · histogram · loglog · pie · plot · scatter · semilogx · semilogy · stairs · stem
Other
addpoints · ancestor · animatedline · autumn · axes · barh · bone · caxis · cla · clf · clim · colorcube · colororder · cool · copper · copyobj · cylinder · daspect · datacursormode · dataTipTextRow · drawnow · fcontour · figure · fill · fill3 · findobj · fsurf · gobjects · gray · groot · hgload · hgsave · hidden · histogram2 · hold · hot · inferno · isgraphics · jet · line · lines · linkaxes · magma · openfig · opengl · pan · parula · patch · pink · plasma · plotmatrix · plotyy · polarhistogram · polarplot · polarscatter · print · quiver3 · ribbon · saveas · savefig · sphere · spring · stackedplot · subtitle · summer · suptitle · text · textscatter · textscatter3 · triplot · turbo · viridis · waitbar · winter · wordcloud · xlabel · xlim · xline · xscale · xtickangle · xtickformat · xticklabels · xticks · ylabel · ylim · yline · yscale · ytickangle · ytickformat · yticklabels · yticks · zlim · zoom
Source you can read
Every RunMat function's source is public. Read exactly how ishandle is executed, line by line, in Rust.
- View the source for ishandle 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.