Composite

Create and access nondistributed variables on multiple workers from client

Description

Composite objects contain references to variables stored on parallel workers running an spmd statement. A Composite object resembles a cell array with one element for each worker and can contain different values for each worker. You can retrieve values using cell-array indexing and define values for the entries using indexing or an spmd block. The actual data on the workers remains available for subsequent spmd execution, while the Composite exists on the client and the parallel pool remains open.

Creation

spmd statements automatically create composite variables on the client when the body of an spmd statement returns values. Therefore, you rarely need to create Composite objects directly.

You can also create Composite objects explicitly with the Composite function.

Syntax

c = Composite

c = Composite(nworkers)

c = Composite(pool,___)

Description

c = Composite creates a Composite object on the client using workers from the current parallel pool.

The actual number of workers that the object references depends on the size of the pool and any existing Composite objects. If a parallel pool is not open, the Composite function starts a parallel pool of workers using the default profile.

To create a Composite object manually, you must do so outside any spmd statements. Initially, each entry of the manually created Composite object contains no data. Define values for the entries by using indexing or an spmd block.

c = Composite(nworkers) specifies the number of workers to use to create a Composite object. The actual number of workers is the maximum number of workers compatible with the size of the current parallel pool and with any other existing Composite objects. The software returns an error if it cannot meet the constraints on the number of workers.

c = Composite(pool,___) creates a Composite object using workers from the parallel pool specified by the parallel.Pool object pool. Use this syntax when you want to create Composite objects on a pool other than the pool the gcp function returns. (since R2025a)

Input Arguments

nworkers — Number of workers creating Composite object

number of workers in parallel pool (default) | positive integer | inf | two-element vector of positive integers or inf values

Number of workers creating the Composite object, specified as a positive integer, Inf, or a two-element vector containing positive integers or Inf values. If nworkers is a scalar, it specifies the exact number of workers to use. If nworkers is a two-element vector, its first and second elements specify the minimum and maximum number of workers to use, respectively.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

pool — Pool creating Composite object

parallel.Pool object

Since R2025a

Pool creating Composite object, specified as a parallel.Pool object.

• To create a parallel pool, use parpool.

• To use a subset of the current pool, use partition.

Output Arguments

c — Composite array

Composite object

Composite array on the client using workers from the parallel pool, returned as a Composite object.

Object Functions

exist	Check whether Composite is defined on workers
gather	Transfer distributed array, Composite object, or gpuArray object to local workspace
subsasgn	Subscripted assignment for Composite
subsref	Subscripted reference for Composite

Other object functions of a Composite object behave similarly to these MATLAB^® array functions:

disp	Display value of variable
end	Terminate block of code or indicate last array index
isempty	Determine whether array is empty
length	Length of largest array dimension
ndims	Number of array dimensions
numel	Number of array elements
size	Array size

Examples

Create Composite Object with No Defined Elements

This example shows how to create a Composite object with no defined elements, and then assign values using a for-loop on the client.

Start a parallel pool with four workers and create a Composite object with an element for each worker.

p = parpool("Processes",4);

Starting parallel pool (parpool) using the 'Processes' profile ...
Connected to parallel pool with 4 workers.

c = Composite

 
c =
 
   Worker 1: No data
   Worker 2: No data
   Worker 3: No data
   Worker 4: No data
 

Use a for-loop on the client to define values for the elements of the Composite object. The value that you assign to each element is stored on the workers. Display the Composite object.

for w = 1:length(c)
    c{w} = rand;
end
c{:}

ans = 0.8147

ans = 0.9058

ans = 0.1270

ans = 0.9134

Define Number of Elements in Composite Objects

This example shows how to specify the number of workers and consequently the number of elements in a Composite object.

Start a parallel pool of 10 workers using a profile called my_Profile.

parpool("my_Profile",10);

Starting parallel pool (parpool) using the 'my_Profile' profile ...
Connected to parallel pool with 10 workers.

Create a Composite object with only four workers from the current parallel pool and assign values to the Composite elements in an spmd block. Display the Composite object.

c = Composite(4);
spmd
    c = spmdIndex;
end
c{:}

ans = 1

ans = 2

ans = 3

ans = 4

Use Distributed Array to Set Values of Composite Object

This example shows how to use an spmd block and a distributed array to create Composite objects on the client.

Start a parallel pool with four workers and distribute an array of four integers to the workers. Each worker gets one integer.

p = parpool("Processes",4);
d = distributed([3 1 4 2]);

Use the parts of the distributed array on each worker to set the values of the Composite object c.

spmd
c = getLocalPart(d);
end

Display and view information about c.

c{:}

ans = 3

ans = 1

ans = 4

ans = 2

whos c

  Name      Size            Bytes  Class        Attributes

  c         1x4               489  Composite              

Create Composite on Specified Parallel Pool

Start a parallel pool using the remote cluster profile myMJSCluster.

myClusterPool = parpool(myMJSCluster,15);

Starting parallel pool (parpool) using the 'myMJSCluster' profile ...
Connected to parallel pool with 15 workers.

Partition the myClusterPool to prepare for running an spmd statement. Use the partition function to create a new pool, spmdPool, where each host is limited to a maximum of one worker. This setup helps distribute tasks evenly across hosts.

[spmdPool,otherPool] = partition(myClusterPool,"MaxNumWorkersPerHost",1);

Create a Composite object with an element for each worker in spmdPool.

j = Composite(spmdPool);

Use a for-loop on the client to define values for the elements of the Composite object.

m = 1000000;
for w = 1:length(j)
    j{w} = rand(m,2);
end

Perform a Monte Carlo approximation of pi using the Composite object.

spmd
   for p = drange(1:spmdSize)
      z = j(:,1) + 1i*j(:,2);
      c = sum(abs(z) < 1); 
   end
   k = spmdPlus(c);
   p = 4*k/(m*spmdSize);
end
approxPi = p{1}

approxPi = 
3.1418

Tips

• The Composite function creates a Composite object on the workers of the existing parallel pool. If no pool exists, the Composite function starts a new parallel pool unless automatically starting pools is disabled in your parallel settings. If no parallel pool exists and Composite cannot start one, the result is a 1-by-1 Composite object in the client workspace.

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2008a

R2025a: Specify pool argument to Composite

You can now specify a parallel pool to use to create Composite objects. Use this syntax to create Composite on a pool other than the pool the gcp function returns.