ClusterPool

Parallel pool of workers on a cluster of machines

Description

Use parpool to create a parallel pool of workers on a cluster of machines. After you create the pool, parallel pool features, such as parfor or parfeval, run on the workers. With the ClusterPool object, you can interact with the parallel pool.

Creation

• Create a parallel pool on a cluster of machines by using the parpool function.

  pool = parpool("myCluster")

  where myCluster is the name of a cluster profile for a cluster of machines.

• Create a pool partition from an existing parallel pool using the partition function. (since R2025a)

Properties

AttachedFiles — Files and folders copied to workers

cell array of character vectors

Files and folders copied to workers, specified as a cell array of character vectors. To attach files and folders to the pool, use addAttachedFiles.

AutoAddClientPath — Indication whether user-added entries on client path are added to worker paths

Read-only: true (default) | false

This property is read-only.

Indication whether user-added entries on client path are added to worker paths, specified as a logical value.

Data Types: logical

Cluster — Cluster on which the parallel pool is running

Read-only: cluster object

This property is read-only.

Cluster on which the parallel pool is running, specified as a parallel.Cluster object.

Connected — Flag that indicates whether the parallel pool is running

Read-only: true | false

This property is read-only.

Flag that indicates whether the parallel pool is running, specified as a logical value.

Data Types: logical

EnvironmentVariables — Environment variables copied to the workers

Read-only: cell array of character vectors

This property is read-only.

Environment variables copied to the workers, specified as a cell array of character vectors.

FevalQueue — Queue of FevalFutures to run on the parallel pool

Read-only: FevalQueue

This property is read-only.

Queue of FevalFutures to run on the parallel pool, returned as an FevalQueue object. You can use this property to check the pending and running future variables of the parallel pool. To create future variables, use parfeval and parfevalOnAll. For more information on future variables, see Future.

Data Types: FevalQueue

FileStore — Store of files accessible to both client and workers

FileStore

Store of files accessible to both client and workers, specified as a FileStore object.

IdleTimeout — Time after which the pool shuts down if idle

nonnegative integer

Time in minutes after which the pool shuts down if idle, specified as an integer greater than zero. A pool is idle if it is not running code on the workers. By default 'IdleTimeout' is the same as the value in your parallel settings. For more information on parallel settings, see Specify Your Parallel Settings.

NumWorkers — Number of workers comprising the parallel pool

Read-only: integer

This property is read-only.

Number of workers comprising the parallel pool, specified as an integer.

ClusterPool objects support pools with up to 2000 workers. (since R2024a)

Busy — Flag that indicates whether the parallel pool is busy

Read-only: true | false

This property is read-only.

Flag that indicates whether the parallel pool is busy, specified as true or false. The pool is busy if there is outstanding work for the pool to complete.

SpmdEnabled — Indication if pool can run spmd code

Read-only: true (default) | false

This property is read-only.

Indication if pool can run spmd code, specified as a logical value.

Data Types: logical

ValueStore — Store of data accessible to both client and workers

ValueStore

Store of data accessible to both client and workers, specified as a ValueStore object.

Workers — Information about workers comprising the parallel pool

Read-only: array of parallel.Worker objects

Since R2025a

This property is read-only.

Information about workers comprising the parallel pool, returned as an array of parallel.Worker objects.

Object Functions

addAttachedFiles	Attach files or folders to parallel pool
Composite	Create and access nondistributed variables on multiple workers from client
delete	Shut down parallel pool
listAutoAttachedFiles	List of files automatically attached to job, task, or parallel pool
parfeval	Run function on parallel pool worker
parfevalOnAll	Run function asynchronously on all workers in parallel pool
parforOptions	Options set for parfor
partition	Partition parallel pool
ticBytes	Start counting bytes transferred within parallel pool
tocBytes	Read how many bytes have been transferred since calling ticBytes
updateAttachedFiles	Update attached files or folders on parallel pool
spmd	Execute code in parallel on workers of parallel pool

Version History

Introduced in R2020a

R2025a: New property to query worker information

To identify the workers in a pool, use the Workers property.

R2024a: Support for pools with up to 2000 workers

Starting in R2024a, ClusterPool objects support pools with up to 2000 workers. Before R2024a, ClusterPool supports pools with up to 1000 workers.