gather — Copy provider-resident data back to host memory.
gather reconstructs host values from gpuArray storage while preserving class and shape. Host values pass through unchanged, and RunMat mode can gather gpuArray values nested in containers.
Syntax
X = gather(X)
[X1, X2, ...] = gather(X1, X2, ...)Inputs
X- Type
Any- Required
- Yes
- Description
- Input value to gather from GPU to host.
X1- Type
Any- Required
- Yes
- Description
- First input value.
Xn- Type
Any- Required
- Variadic
- Description
- Additional input values.
Returns
X- Type
Any- Description
- Host-resident value gathered from input.
X- Type
Any- Description
- Host-resident outputs matching each input.
Returned values from gather depend on how many outputs the caller requests.
Errors
RunMat:gather:NotEnoughInputs- When
- No input arguments were provided.
- Message
gather: not enough input arguments
RunMat:gather:TooManyOutputs- When
- Requested outputs exceed one for single-input gather.
- Message
gather: too many output arguments
RunMat:gather:OutputCountMismatch- When
- Requested output count does not match number of inputs.
- Message
gather: number of outputs must match number of inputs
RunMat:gather:InternalError- When
- Internal output construction failed.
- Message
gather: internal error
Behavior
X = gather(A) copies a provider-resident value to host memory. The result retains the source class, shape, and supported real or complex layout. Host-resident input passes through unchanged.
[X1, X2, ...] = gather(A1, A2, ...) gathers each input in call order. The number of requested outputs must match the number of inputs. RunMat mode also descends through cells, structs, and supported object values and replaces nested gpuArray handles with host values.
Gathering does not consume the source handle. It remains valid and resident until the program releases it. Provider download errors remain visible to the caller rather than changing the value's class or precision.
GPU execution
gather is an explicit device-to-host boundary and a fusion sink. Each gpuArray is resolved through its owning provider, so a later provider registration cannot redirect an existing handle to a different backend.
Transfers carry the physical element type and layout. Single and fixed-width integer values are reconstructed from native storage instead of passing through double precision.
Examples
Copy a gpuArray matrix to host memory
G = gpuArray([1 2 3; 4 5 6]);
H = gather(G)Expected output:
H = [1 2 3; 4 5 6]Pass through data already in host memory
x = uint16([10 20 30]);
y = gather(x)Expected output:
y = uint16([10 20 30])Preserve logical class and shape
mask = gpuArray(logical([1 0 1 0]));
hostMask = gather(mask)Expected output:
hostMask = logical([1 0 1 0])Gather gpuArray values inside a cell array
C = {gpuArray([1 2]), uint8(42)};
hostC = gather(C)Expected output:
hostC contains host values [1 2] and uint8(42)Gather gpuArray values in struct fields
S = struct("data", gpuArray([8 1 6; 3 5 7; 4 9 2]), "label", "gpu result");
S_host = gather(S)Expected output:
S_host.data is a host matrix and S_host.label is unchangedGather multiple inputs into matching outputs
A = gpuArray(eye(3));
B = gpuArray(ones(2, 2));
[hostA, hostB] = gather(A, B)Expected output:
hostA is eye(3); hostB is ones(2, 2)Gather at the end of a GPU pipeline
A = gpuArray([0 pi/6 pi/2]);
B = sin(A) .* 5;
result = gather(B)Expected output:
result = [0 2.5 5]Using gather with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how gather changes the result.
Run a small gather example, explain the result, then change one input and compare the output.
FAQ
Does gather modify the original gpuArray?⌄
No. It returns a host value and leaves the source handle valid and resident.
What happens to input that is already on the host?⌄
It passes through unchanged, including its class and shape.
Are logical and integer classes preserved?⌄
Yes. Native download metadata reconstructs logical, single, double, and all eight fixed-width integer classes without widening through double.
Does gather recurse into containers?⌄
In RunMat compatibility mode, it gathers nested gpuArray values in cells, structs, and supported objects. This recursive container behavior is a RunMat extension.
How do multiple inputs work?⌄
Request one output for each input: [X1, X2] = gather(A1, A2). The input and output counts must match.
What happens if no provider owns a gpuArray handle?⌄
The call returns a provider error. Host-only inputs do not require an acceleration provider.
Does gather free device memory?⌄
No. Clear or release the source gpuArray when it is no longer needed.
Related Acceleration functions
Source you can read
Every RunMat function's source is public. Read exactly how gather is executed, line by line, in Rust.
- View the source for gather 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.