parpool — Create or return the execution pool for the current session.
parpool admits a host-supported worker pool and returns its generation-fenced session handle.
Syntax
pool = parpool(___)Inputs
options- Type
Any- Required
- Variadic
- Default
- —
- Description
- Optional pool kind and worker count.
Returns
pool- Type
Any- Description
- Execution pool owned by the current RunMat session.
Errors
RunMat:parpool:InvalidInput- When
- The requested pool kind, worker count, or option is invalid for the active host.
- Message
parpool: invalid pool request
Behavior
parpool() returns the compatible execution pool owned by the current session or creates one using the host's automatic worker count. A numeric argument requests a worker count; a pool-kind string can select a supported host backend.
Native CLI and Desktop hosts use isolated worker processes. Browser hosts use browser workers when available, and remote execution can install a cluster-backed pool. A host rejects pool kinds or worker counts it cannot provide.
Calling delete(pool) closes that pool generation and cancels unfinished child work. A later pool has a new generation; futures, distributed values, and other execution handles from the retired generation cannot be reused.
Execution placement
The pool owns worker admission and transport, not language semantics. Workers consume versioned executable regions and typed values produced by the compiler; they do not reparse source or resolve functions from an ambient path.
Examples
Create a two-worker process pool
pool = parpool(2);
workers = pool.NumWorkersExpected output:
workers = 2Reuse the session's compatible pool
first = parpool(2);
second = parpool(2)Expected output:
first and second identify the same pool generationUsing parpool with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how parpool changes the result.
Run a small parpool example, explain the result, then change one input and compare the output.
FAQ
What worker count does parpool() use?⌄
It asks the active host for its automatic worker count and admission policy.
Does a repeated call create another pool?⌄
A compatible request returns the session's existing pool. An incompatible size request replaces it with a new generation.
What happens when a pool is deleted?⌄
The generation closes, unfinished work is cancelled, and handles owned by that generation become stale.
Does the web runtime support pools?⌄
Yes when the browser host provides worker support. The same typed execution contracts are used across native and browser hosts.
Related Parallel functions
codistributed · 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 · 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 parpool is executed, line by line, in Rust.
- View the source for parpool 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.