RunMat
GitHub

View all functions

CategoryIntrospection

What does the whos function do in MATLAB / RunMat?

whos reports a MATLAB-style table describing each variable in the current workspace (or in a MAT-file when you pass -file). The result is a struct array with the traditional name, size, bytes, class, global, sparse, complex, nesting, and persistent fields.

How does the whos function behave in MATLAB / RunMat?

  • whos with no arguments lists every variable in the active workspace, using MATLAB's default alphabetical ordering.
  • whos pattern1 pattern2 ... accepts character vectors or string scalars containing wildcard expressions (*, ?, [abc]). Any variable whose name matches at least one pattern is reported.
  • whos('-regexp', expr1, expr2, ...) keeps variables whose names match any of the supplied regular expressions.
  • whos global lists only the variables that are marked as global within the active workspace.
  • whos('-file', filename, ...) inspects a MAT-file without loading it. You can combine -file with explicit names or -regexp selectors, mirroring MATLAB.
  • The returned struct array uses string scalars for textual fields (name, class, nesting) and MATLAB-style numeric row vectors for the size field.
  • bytes reports the amount of memory consumed by the value using RunMat's host representation. GPU arrays stay on the device; RunMat estimates bytes from the device-resident shape and provider precision.

whos Function GPU Execution Behaviour

whos is an introspection builtin that runs entirely on the CPU. When a variable is a gpuArray, RunMat leaves it on the device and derives metadata (element count, precision, and total bytes) from the handle and active provider. No kernels are launched and no device buffers are gathered. Auto-offload heuristics remain untouched.

GPU residency in RunMat (Do I need gpuArray?)

You do not need to move data to or from the GPU to call whos. The builtin gathers scalar arguments if they happen to live on the device, but the workspace variables themselves remain where they are. Use gather separately if you need host copies of the data for further processing.

Examples of using the whos function in MATLAB / RunMat

List All Workspace Variables

a = 42;
b = rand(3, 2);
info = whos;
{info.name}

Expected output (example):

    {"a"}    {"b"}

Filter Variables With Wildcards

alpha = 1;
beta = 2;
results = whos("a*");
{results.name}

Expected output:

    {"alpha"}

Use Regular Expressions To Match Names

x1 = rand;
x2 = rand;
matches = whos('-regexp', '^x\\d$');
cellstr({matches.name})

Expected output:

    {'x1'}
    {'x2'}

Inspect Variables Stored In A MAT-File

save('snapshot.mat', 'alpha', 'beta')
file_info = whos('-file', 'snapshot.mat');
{file_info.name}

Expected output:

    {"alpha"}    {"beta"}

Check GPU Arrays Without Gathering

G = gpuArray(rand(1024));
meta = whos('G');
meta.bytes    % estimated bytes on device

Expected output (example):

meta.bytes
ans =
    8.3886e+06

FAQ

  • What fields does whos return? Each entry exposes name, size, bytes, class, global, sparse, complex, nesting, and persistent, matching MATLAB semantics.
  • Does whos mutate the workspace? No. It is a pure query that never creates, deletes, or modifies variables.
  • Are bytes identical to MATLAB? RunMat reports the size of its own representations. Numeric and logical arrays match MATLAB's byte counts; other types (such as structs or objects) may differ slightly because RunMat records their data differently.
  • How are global variables handled? Variables declared with global are marked with global = true. Use whos global to list only globals.
  • Can I combine wildcard filters and -regexp? Yes. whos('data*', '-regexp', '^(cfg|state)') reports the union of both selections.
  • What happens when no variables match? A 0×1 struct array is returned, just like MATLAB, so idioms such as isempty(whos('foo')) work.
  • Does whos('-file', ...) read the entire MAT-file? It parses only enough metadata to reconstruct variable values. Large arrays are streamed once; no workspace variables are modified.
  • How are persistent variables reported? RunMat currently marks all entries as persistent = false in the base workspace. Future releases will surface persistent metadata from function scopes.
  • Will GPU arrays be gathered? No. whos inspects device handles and leaves residency untouched.

See Also

who, class, size, load, save, gpuArray, gather

Source & Feedback