gpuDevice — Inspect, select, synchronize and reset a session-owned GPUDevice.
device = gpuDevice() returns a parallel.gpu.GPUDevice handle for the current session. It selects an available device without resetting an already selected device. gpuDevice(ind) physically resets this session's device allocations before selecting the indexed owner, including when it was already selected. gpuDevice([]) resets and deselects. This is a typed object with read-only dependent properties, not the former provider metadata struct; use gpuInfo for a summary string.
Syntax
device = gpuDevice()
device = gpuDevice(arg)Inputs
arg- Type
Any- Required
- Yes
- Description
- Exact positive host device index or empty host array for physical reset and deselection.
Returns
device- Type
Any- Description
- Session-owned parallel.gpu.GPUDevice handle, or empty host double result for deselection.
Errors
RunMat:gpuDevice:NoProvider- When
- No acceleration provider is registered.
- Message
gpuDevice: no acceleration provider registered
RunMat:gpuDevice:TooManyInputs- When
- More than one input argument was supplied.
- Message
gpuDevice: too many input arguments
RunMat:gpuDevice:UnsupportedArgument- When
- Argument does not map to a valid device selector/reset operation.
- Message
gpuDevice: unsupported input argument
Behavior and compatibility
A selected RuntimeContext and a registered provider with genuine device-control capability are required. Device indices are positive exact host integers, numbered in registered device-ID order among this invocation's authorized, control-capable providers. Provider-assigned physical IDs are not device indices. Numeric indices are not widened through double; logical selectors remain a separately gated RunMat extension.
Name is a UTF-16 character row; Index is a host double scalar. SupportsDouble reports the actual enabled device capability, not the current execution precision. DeviceAvailable reports backend availability, and DeviceSelected reads the requesting session's current selection. Public properties cannot be assigned; a handle from another session or a replaced class authority is rejected.
TotalMemory and AvailableMemory are queried only from actual backend facts. WGPU does not expose those measurements here and property access reports an explicit unsupported diagnostic. max_buffer_size is an allocation limit, not VRAM; total CUDA memory is not free memory. Missing metrics are never fabricated as zero, an allocation limit, or a successful reset.
wait(device) awaits the real queue-completion owner without retiring allocations. reset(device) and numeric selection await physical completion, fence ordinary session dispatch/publication, and retire this session's allocations through their existing owners. Previously inherited same-session allocations in other control-capable providers are included. Every relevant capability and execution lease is preflighted before the fence.
RunMat's WGPU provider may be shared by sessions. Reset invalidates the requesting session's prior allocation epochs and cached/pool resources without destroying peer-session allocations or clearing the provider registry. An old GPU array from the reset session is no longer usable; a peer's array remains valid. This scoped device lifecycle is not a process-wide adapter reset or a claim that every CUDA-specific GPUDevice property is implemented.
Reset is ordered retirement, not a transactional rollback. A later owner failure can follow earlier completed retirements; the session stays fenced with the retained original failure and epoch unchanged. The existing host task supervisor owns reset independently of its awaiting caller. Caller cancellation does not restore selection or discard GPU-completion claims; host shutdown before terminal disposition records a fenced failure. Native GPU waits run on the existing bounded device-progress worker, not the RuntimeContext/UI poll thread. Retirement yields between bounded batches.
Only providers that expose actual control and allocation ownership participate. Unsupported backends are not silently treated as reset-capable. The catalog remains incomplete while backend/property coverage and native/browser physical qualification remain outstanding.
Examples
Inspect the current device
device = gpuDevice();
disp(device.Name)
Read live device availability
device = gpuDevice();
assert(device.DeviceAvailable);
assert(device.DeviceSelected)
Branch on actual double capability
device = gpuDevice();
if device.SupportsDouble; disp('double supported'); else; disp('double unavailable'); end
Reset and select an indexed device
device = gpuDevice(uint32(1));
assert(device.Index == 1);
wait(device)
Keep the summary interface distinct
device = gpuDevice();
status = gpuInfo();
disp(status)
Residency and diagnostics
The selector and GPUDevice handle remain on the host. Querying properties does not gather array payloads. Selection/reset changes allocation validity only after actual synchronized owner retirement; ordinary array transfer still uses gpuArray and gather.
Invalid, nonpositive, fractional, out-of-range, nonscalar or resident selectors are rejected. An unavailable index, missing control/lease, unsupported measured property, foreign handle, and retained reset failure are explicit errors. Use reset(device), not the unsupported text selector gpuDevice('reset').
Examples
Inspect current device
device = gpuDevice();Read authoritative availability
device = gpuDevice(); disp(device.Name); available = device.DeviceAvailable;Inspect actual double capability
device = gpuDevice(); supports_double = device.SupportsDouble;Reset and select an index
device = gpuDevice(uint32(1)); wait(device); reset(device);Keep summary and object interfaces distinct
device = gpuDevice(); status = gpuInfo(); gpuDevice([]); selected_after = device.DeviceSelected;Using gpuDevice with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how gpuDevice changes the result.
Run a small gpuDevice example, explain the result, then change one input and compare the output.
FAQ
Must I call gpuDevice before GPU builtins?⌄
No. Existing inherited dispatch can use its admitted provider. Calling gpuDevice establishes explicit session selection; a deselected session does not fall back to the process default until it is explicitly selected again.
Why do memory properties report unsupported?⌄
A backend must supply actual measurements. WGPU buffer-size limits are not device memory, and total bytes are not free bytes.
Does reset destroy another session's arrays?⌄
No. WGPU retires the requesting session's prior epochs through their original allocation owners. It synchronizes shared queue work without globally clearing the device registry or invalidating peer scopes.
What happens when reset fails or its caller is cancelled?⌄
The host supervisor retains the reset task through caller cancellation. A physical/retirement failure leaves the session fenced with the original epoch and failure; completed earlier retirements are not rolled back or relabeled transactional.
How do I get a short summary?⌄
gpuInfo remains a separate metadata-summary string interface and does not manufacture a GPUDevice object.
Related Acceleration functions
Source you can read
Every RunMat function's source is public. Read exactly how gpuDevice is executed, line by line, in Rust.
- View the source for gpuDevice 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.