fetchOutputs — Wait for futures and return their requested outputs.
fetchOutputs returns one task's outputs directly or assembles multiple task results by vertical concatenation or as cells.
Syntax
[outputs...] = fetchOutputs(future)
[outputs...] = fetchOutputs(futures, "UniformOutput", tf)Inputs
future- Type
Any- Required
- Yes
- Default
- —
- Description
- Future whose outputs are requested.
future- Type
Any- Required
- Yes
- Default
- —
- Description
- Future array whose outputs are requested.
UniformOutput- Type
StringScalar- Required
- Yes
- Default
"UniformOutput"- Description
- Select cell output for arrays of futures.
tf- Type
Any- Required
- Yes
- Default
- —
- Description
- True to concatenate outputs; false to return cell arrays.
Returns
outputs- Type
Any- Description
- Outputs produced by the scheduled function.
Returned values from fetchOutputs depend on how many outputs the caller requests.
Errors
InvalidFuture- When
- The first argument is not a parallel future scalar or array.
- Message
fetchOutputs expects a parallel future scalar or array
OutputCountMismatch- When
- A future provides fewer outputs than the caller requested.
- Message
each future must provide at least the requested number of outputs
InvalidOption- When
- A name-value option is unknown or its value is invalid.
- Message
fetchOutputs option is invalid
Behavior
Fetching waits through the session's async execution service. A single future returns the scheduled callable's requested outputs and structured errors; fetching several worker results assembles each output by vertical concatenation by default.
Future arrays retain one-based source indices. fetchNext marks one completed result as read; a timeout can return [] in every requested output slot. fetchOutputs(..., "UniformOutput", false) returns cell arrays instead of concatenating multiple results.
Execution placement
Fetch operations cross the worker-to-client result boundary. Numeric placement after transfer follows the scheduled callable and result-assembly contract rather than a provider rule owned by the fetch builtin.
Examples
Retrieve multiple requested outputs
pool = parpool(2);
future = parfeval(pool, @min, 2, [4 9 2]);
[value, index] = fetchOutputs(future)Expected output:
value = 2; index = 3Return future-array results as cells
first = parfeval(@(x) x + 1, 1, 4);
second = parfeval(@(x) x + 2, 1, 8);
futures = first; futures(2) = second;
answers = fetchOutputs(futures, "UniformOutput", false)Expected output:
answers = {5; 10}Using fetchOutputs with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how fetchOutputs changes the result.
Run a small fetchOutputs example, explain the result, then change one input and compare the output.
FAQ
Does fetching change output classes?⌄
A single future returns its callable's output. Fetching multiple results concatenates them by default; UniformOutput, false instead returns cells.
Can fetching suspend?⌄
Yes. It waits through the session async runtime until a matching result, timeout, cancellation, or failure is available.
What does UniformOutput control?⌄
For future arrays, false preserves each result in a cell instead of concatenating compatible values.
Can the same result be returned twice by fetchNext?⌄
No. A selected future is marked read before the next completion-order selection.
Related Parallel functions
codistributed · codistributed.build · codistributor · codistributor1d · codistributor2dbc · distributed · fetchNext · gcat · gcp · getCodistributor · getCurrentJob · getCurrentTask · getCurrentWorker · getLocalPart · globalIndices · gop · gplus · iscodistributed · isComplete · labBarrier · labBroadcast · labindex · labProbe · labReceive · labSend · labSendReceive · numlabs · parfeval · parfevalOnAll · parpool · redistribute · spmdBarrier · spmdBroadcast · spmdCat · spmdIndex · spmdPlus · spmdProbe · spmdReceive · spmdReduce · spmdSend · spmdSendReceive · spmdSize
Related guides
Source you can read
Every RunMat function's source is public. Read exactly how fetchOutputs is executed, line by line, in Rust.
- View the source for fetchOutputs 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.