Composite - Create and access nondistributed variables on multiple workers from

  client - MATLAB ([original](https://www.mathworks.com/help/parallel-computing/composite.html)) ([raw](?raw))

Main Content

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 theComposite 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 theComposite function.

Syntax

Description

[c](#mw%5F8b911041-33cd-4d4c-91a0-f45cb00a3389) = Composite creates aComposite 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 anyspmd statements. Initially, each entry of the manually createdComposite object contains no data. Define values for the entries by using indexing or an spmd block.

example

[c](#mw%5F8b911041-33cd-4d4c-91a0-f45cb00a3389) = Composite([nworkers](#mw%5Fce3b703a-fc56-488b-998b-3b8898ad5255)) 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.

example

Input Arguments

expand all

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

Output Arguments

expand all

c — Composite array

Composite object

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

Object Functions

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

Examples

collapse all

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 =

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{:}

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{:}

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.

Name Size Bytes Class Attributes

c 1x4 489 Composite

Tips

• The Composite function creates a Composite object on the workers of the existing parallel pool. If no pool exists, theComposite function starts a new parallel pool unless automatically starting pools is disabled in your parallel preferences. If no parallel pool exists andComposite cannot start one, the result is a 1-by-1Composite 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