Main Content

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.

    Description

    example

    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.

    example

    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.

    Input Arguments

    expand all

    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

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

    Object Functions

    existCheck whether Composite is defined on workers
    gatherTransfer distributed array, Composite object, or gpuArray object to local workspace
    subsasgnSubscripted assignment for Composite
    subsrefSubscripted reference for Composite

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

    dispDisplay value of variable
    endTerminate block of code or indicate last array index
    isemptyDetermine whether array is empty
    lengthLength of largest array dimension
    ndimsNumber of array dimensions
    numelNumber of array elements
    sizeArray size

    Examples

    collapse all

    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
    

    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
    

    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              
    

    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 preferences. 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

    Version History

    Introduced in R2008a