codistributed — Create a codistributed array from driver or worker-scoped data.
codistributed creates a compatible distributed value from a complete client value, replicated worker value, or designated worker value.
Syntax
D = codistributed(value, codistributor_or_worker, codistributor)Inputs
value- Type
Any- Required
- Yes
- Default
- —
- Description
- Value operated on by the parallel runtime.
codistributor_or_worker- Type
Any- Required
- No
- Default
- —
- Description
- Optional codistributor or one-based designated worker.
codistributor- Type
Any- Required
- No
- Default
- —
- Description
- Codistributor used with a designated worker.
Returns
result- Type
Any- Description
- Result produced by the parallel operation.
Errors
RunMat:parallel:LoweringRequired- When
- The operation is invoked without an active compiler-owned SPMD or distributed execution context.
- Message
parallel operation requires executor-aware lowering
Behavior
A distributed value stores partition payloads in the execution service. The language value is a typed handle containing its global shape, value class, distribution scheme, owning pool, and generation. Exact integer classes, shapes, and supported complex or sparse representations are retained across partition and materialization boundaries.
Driver construction partitions one complete input. Cooperative construction inside spmd can replicate one value, select a designated worker's value, or build from every worker's local contribution. The default build form validates class, rank, shape, layout, and codistributor agreement across the gang; "noCommunication" skips cross-worker validation only when the caller already guarantees consistency.
Distributed values belong to one pool generation. Closing or resizing that pool retires local-part access, materialization, redistribution, and distributed builtin placement for the stale handle.
Execution placement
Construction, redistribution, and materialization may cross the driver-worker boundary. getLocalPart reads only the selected worker partition, globalIndices computes ownership from the authoritative layout, and getCodistributor projects the resolved description without reading payloads.
Examples
Create a codistributed value from driver data
source = uint16([1 2 3 4]);
value = codistributed(source);
result = gather(value)Expected output:
result = uint16([1 2 3 4])Use an explicit partition description
pool = parpool(2);
source = uint16([1 2 3 4]);
codist = codistributor1d(uint32(2), uint64([2 2]), uint64([1 4]));
value = codistributed(source, codist);
result = gather(value)Expected output:
result = uint16([1 2 3 4])Using codistributed with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how codistributed changes the result.
Run a small codistributed example, explain the result, then change one input and compare the output.
FAQ
Does the language value contain every partition?⌄
No. It is a typed, generation-fenced handle; the execution service owns partition payloads.
Are integer classes preserved?⌄
Yes. Supported values retain their exact class, shape, and payload through partition, redistribution, local access, and gather.
What happens after the pool is closed or resized?⌄
The old generation is retired and distributed operations reject its stale handles.
Does inspection gather the full value?⌄
No. Codistributor and index inspection use handle metadata; local-part access reads only the selected partition.
Where can I omit a lab argument?⌄
Inside spmd, the active rank selects the local partition. Driver code supplies an explicit lab where the form requires one.
Related Parallel functions
codistributed.build · codistributor · codistributor1d · codistributor2dbc · distributed · fetchNext · fetchOutputs · 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 codistributed is executed, line by line, in Rust.
- View the source for codistributed 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.