spmdReceive

Receive data from another worker in spmd block

Since R2022b

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.

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.

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

Send Data Between Workers in spmd Block

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
  

Tag and Send Data Between Workers in spmd Block

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

source — Index of worker sending data

positive integer | 'any'

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

tag — Message tag

nonnegative integer

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

B — Data received by current worker

MATLAB variable | ...

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

Example: magic(3)

sourceOut — Index of worker sending data

positive integer | 'any'

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.

tagOut — Message tag

nonnegative integer

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.

• A worker that receives data using spmdReceive might finish execution after other workers in the spmd block. When you need synchronized workers in an spmd block or communicating job, such as when you close a shared resource, use spmdBarrier after calling spmdSend and spmdReceive.

• When using spmdSend and spmdReceive, data transfer between workers is non-overtaking. This means that if a worker sends multiple data to the same destination, and the receiving worker uses spmdReceive without specifying tags, MATLAB^® delivers the data in the order you send them.

Extended Capabilities

Thread-Based Environment

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

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

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The spmdReceive function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray. For more information, see Run MATLAB Functions on a GPU.

If data is a gpuArray, data transfer between multiple GPUs in a parallel pool uses fast peer-to-peer communication, including NVLink, if available.

Version History

Introduced in R2022b