Main Content

spmdReceive

Receive data from another worker in spmd block

Since R2022b

collapse all in page

    Syntax

    B = spmdReceive
    B = spmdReceive(source)
    B = spmdReceive('any')
    B = spmdReceive('any',tag)
    B = spmdReceive(source,tag)
    [B,sourceOut,tagOut] = spmdReceive(___)

    Description

    B = spmdReceive receives data B sent to the current worker from any worker in the current spmd block or communicating job.

    When you offload computations using parfor and parfeval, only one worker at a time runs each computation. These workers are independent and do not communicate with each other. If you apply spmdReceive to these workers, the function has no effect.

    When a worker runs spmdReceive, the function blocks the execution of other commands until the worker receives the data.

    To use spmdReceive, the number of workers running the current spmd block must be greater than 1. To get the number of workers running the current spmd block, use the spmdSize function.

    example

    B = spmdReceive(source) receives data sent from the worker whose index is equal to source. To get the index of a worker, use the spmdIndex function.

    B = spmdReceive('any') receives data from any worker.

    B = spmdReceive('any',tag) receives data sent with the tag tag from any worker.

    example

    B = spmdReceive(source,tag) receives data sent with the tag tag from the worker whose index is equal to source.

    [B,sourceOut,tagOut] = spmdReceive(___) receives data sent from another worker, returns the index sourceOut of the source worker, and returns the tag tagOut with the data.

    Examples

    collapse all

    This example shows how to send data between workers in an spmd block or communicating job.

    Create a parallel pool with four workers.

    parpool(4);

    When you execute an spmd block after creating a parallel pool, by default all available workers in the pool run the code inside the spmd block.

    Create an spmd block. On the worker whose index is equal to 1, create an array. Use spmdSend to send the array to the worker whose index is equal to 2 and use spmdReceive to collect the data.

    spmd
    switch spmdIndex
        case 1
            A = magic(3)
            spmdSend(A,2);
        case 2
            B = spmdReceive
    end
end
    Worker 1: 
  
  A =
  
       8     1     6
       3     5     7
       4     9     2
  
Worker 2: 
  
  B =
  
       8     1     6
       3     5     7
       4     9     2

    This example shows how to tag and send data between workers in an spmd block or communicating job.

    Create a parallel pool with four workers. 

    parpool(4);

    Create an spmd block. On the worker whose index is equal to 1, create two arrays A1 and A2. Before and between creating arrays, pause the execution using the pause function to simulate some work. Then, use spmdSend to send the matrices to the worker whose index is equal to 2.

    Tag each matrix with an integer. On the worker whose index is equal to 2, use spmdReceive to collect the data. 

    tic
spmd
    switch spmdIndex
        case 1
            pause(5);
            A1 = magic(1)
            pause(5);
            A2 = magic(2)
            spmdSend(A1,2,1);
            spmdSend(A2,2,2);
        case 2
            B1 = spmdReceive('any',1)
            B2 = spmdReceive('any',2)
  
    end
end
toc
    Worker 1: 
  
  A1 =
  
       1
  
  
  A2 =
  
       1     3
       4     2
  
Worker 2: 
  
  B1 =
  
       1

  B2 =
  
       1     3
       4     2
  
Elapsed time is 10.061523 seconds.

    In some cases, you can improve the performance of your code by moving some work from one worker to another. Move some work from the worker whose index is equal to 1 to the worker whose index is equal to 2. When you use tags, you can easily move calculations from one worker to another without updating code on the receiving worker.

    tic
spmd
    switch spmdIndex
        case 1
            pause(5);
            A1 = magic(1)
            spmdSend(A1,2,1);
        case 2
            B2 = spmdReceive('any',2)
            B1 = spmdReceive('any',1)
        case 3
            pause(5);
            A2 = magic(2)
            spmdSend(A2,2,2);
    end
end
toc
    Worker 1: 
  
  A1 =
  
       1
  
Worker 2: 
  
  B2 =
  
       1     3
       4     2
  
  
  B1 =
  
       1
  
Worker 3: 
  
  A2 =
  
       1     3
       4     2
  
Elapsed time is 5.117787 seconds.

    Input Arguments

    collapse all

    Index of the worker sending data, specified as a positive integer or 'any'. The value of this input must be less than or equal to the number of workers running the current spmd block or communicating job.

    When you specify this input, spmdReceive returns the data sent from the worker whose index is equal to source.

    When you specify this input as 'any', spmdReceive returns data sent from any worker.

    When you do not specify this input, spmdReceive returns data sent from any worker.

    Example: 1

    Message tag, specified as a nonnegative integer. When you specify this input, spmdReceive returns data that is sent to the current worker using the spmdSend function. The tag argument is equal to the tag sent to the current worker.

    Example: 314159

    Output Arguments

    collapse all

    Data received by the current worker, specified as a scalar, vector, matrix, multidimensional array, table, timetable, or any other MATLAB variable.

    Example: magic(3)

    Index of the worker sending data, returned as a positive integer or 'any'. The value of this input is equal to the index of the worker that sent the received data.

    Message tag of the data that the current worker receives, returned as a nonnegative integer.

    Tips

    Tags have many uses, for example:

    • Use tags to save memory by only loading arrays on workers when you need the data.

    • Use tags to create code that does not depend on the index of the sending worker.

    Extended Capabilities

    Version History

    Introduced in R2022b

    See Also

    | | | |