PollableDataQueue - Send and manually retrieve data - MATLAB (original) (raw)

parallel.pool.PollableDataQueue

Send and manually retrieve data

Description

Use a PollableDataQueue object to send data from a function that you run in the background or in your current MATLAB® session.

You can send data from a function that you run on a parallel pool if you have Parallel Computing Toolbox™. For details, see parallel.pool.PollableDataQueue (Parallel Computing Toolbox).

When you create a PollableDataQueue object, you create a connection to the MATLAB session or BackgroundPool worker that you can use to send and receive messages.

To send data to the MATLAB session or BackgroundPool worker that created thePollableDataQueue, use send.
To manually retrieve data after it is received in the MATLAB session or BackgroundPool worker, use poll.

Creation

Syntax

Description

`q` = parallel.pool.PollableDataQueue creates a PollableDataQueue object that you can use to send and manually retrieve messages. The resultingPollableDataQueue object can be polled only by the client session orBackgroundPool worker that creates it. Create thePollableDataQueue object on the BackgroundPool worker or client session where you want to receive the data.

example

`q` = parallel.pool.PollableDataQueue(Destination=[destination](#mw%5Fa2b1963e-2ce1-4df3-be3c-ceaeaeaa774e)) sets the destination behavior of the PollableDataQueue object. (since R2025a)

If you want the client session and BackgroundPool worker to be able to poll the PollableDataQueue object to receive data, setDestination="any".

example

Input Arguments

expand all

Since R2025a

Destination behavior of the queue, specified as one of these values:

"creator" — Allows only the client session orBackgroundPool worker that creates the queue to poll the queue and receive data. Any data sent to the queue is immediately sent to the client or worker that creates the queue.
"any" — Allows the client session orBackgroundPool worker to poll the queue to receive data. The data waits in the queue and is sent to either the client session orBackgroundPool worker that polls the queue, making that client session or worker the destination for the specific data.

Properties

expand all

Since R2025a

This property is read-only after you use the close object function.

Queue closure state, represented as one of these values:

false — The queue is not closed and you can send data to the queue.
true — The queue is closed and you cannot send data to the queue. Any attempt to send data to the queue results in an error. You can continue to poll the queue for data. You cannot reopen a closed queue.

Data Types: logical

This property is read-only.

Number of items of data waiting to be removed from the queue, specified as a zero or positive integer.

The destination behavior of the queue, set using the Destination (Parallel Computing Toolbox) name-value argument, determines theQueueLength property value:

If you create a PollableDataQueue object without setting theDestination argument, or if you setDestination to "creator", the value is a0 or positive integer in the MATLAB session or BackgroundPool worker that creates thePollableDataQueue object. Everywhere else, the value is0.
For example, if you create a PollableDataQueue object in the current MATLAB session, you can run a function in the background with thatPollableDataQueue object as an input argument. TheQueueLength property of thatPollableDataQueue object is always 0 in the background.
If you set Destination to "any", the value is 0 or a positive integer on the client session and in the background.
For example, if you create a PollableDataQueue object with the Destination to "any" in the current MATLAB session, you can run a function in the background with thatPollableDataQueue object as an input argument. TheQueueLength property of thatPollableDataQueue object is either a 0 or positive integer in the current MATLAB session and in the background.

Before R2025a: The QueueLength property value is 0 or a positive integer on the client session orBackgroundPool worker that creates thePollableDataQueue object. If the client session creates thePollableDataQueue object, the value is 0 on theBackgroundPool worker. If a BackgroundPool worker creates the PollableDataQueue, the value is 0 on the client session.

Object Functions

close	Close pollable data queue
poll	Retrieve data from PollableDataQueue
send	Send data to DataQueue orPollableDataQueue

Examples

collapse all

This example shows how to manually retrieve data in your current MATLAB session that you send from the background.

Create a PollableDataQueue object.

q = parallel.pool.PollableDataQueue;

The helper function magicWithSend defined at the end of this example sends the sum of a magic square to a DataQueue or PollableDataQueue object, then returns that magic square.

Use parfeval and backgroundPool to run the function magicWithSend in the background.

f = parfeval(backgroundPool,@magicWithSend,1,q,3);

To retrieve the output from the background, use fetchOutputs. MATLAB returns the output once the execution of magicWithSend is complete.

ans = 3×3

 8     1     6
 3     5     7
 4     9     2

Use the poll function to collect data from the queue.

Define Helper Function

Define the helper function magicWithSend. The function creates a magic square, then sends the sum of the magic square to a DataQueue or PollableDataQueue object. After the sum is sent, the function returns the magic square.

function X = magicWithSend(q,n) X = magic(n); s = sum(X,'all'); send(q,s); end

This example shows how to use a PollableDataQueue object to send data or instructions to the background during parfeval evaluations.

You can use PollableDataQueue objects to transfer data and messages between the client session and the background. By default, a PollableDataQueue object sends the data only to the client session or background that creates the PollableDataQueue. However, starting in R2025a, you can also create a type of PollableDataQueue that allows the client session or background to poll and receive data.

Define a function to run in the background. The processData function waits for data from the client session, processes it, and sends status updates back to the client. The function stops execution when it receives a "stop" message from the client session.

function out = processData(backgroundToClient,clientToBackground) out = 0; send(backgroundToClient,"Ready to receive data."); while true % Wait for a message from the client session data = poll(clientToBackground,Inf); if strcmp(data,"stop") send(backgroundToClient, ... "Stopped processing data in the background.") return else response = sprintf("Data %d received.",data(1)); send(backgroundToClient,response); out = out+data(2); pause(1); end end end

To simplify the communication between the client session and the background, create two PollableDataQueue objects.

To enable communication from the background to the client session, create a default PollableDataQueue object. Only the client session can receive messages from the default PollableDataQueue object. The backgroundToClient queue sends messages from the background to the client session.

backgroundToClient = parallel.pool.PollableDataQueue;

To enable communication from the client session to the background, create a PollableDataQueue object with the Destination argument set to "any". This type of PollableDataQueue object allows both the client session and the background to send and receive messages. The clientToBackground queue sends messages from the client session to the background.

clientToBackground = parallel.pool.PollableDataQueue(Destination="any");

Use parfeval to execute the processData function in the background and prepare the background to start waiting for data from the client session.

future = parfeval(backgroundPool,@processData,1, ... backgroundToClient,clientToBackground);

Poll the backgroundToClient queue to receive the initial status message from the background.

backgroundStatus = poll(backgroundToClient,inf)

backgroundStatus = "Ready to receive data."

In a loop, send data to the background using the clientToBackground queue and poll the backgroundToClient queue for confirmation before sending the next data point.

for idx = 1:5 send(clientToBackground,[idx rand]); backgroundStatus = poll(backgroundToClient,inf) end

backgroundStatus = "Data 1 received."

backgroundStatus = "Data 2 received."

backgroundStatus = "Data 3 received."

backgroundStatus = "Data 4 received."

backgroundStatus = "Data 5 received."

To stop execution in the background, send a "stop" message to the clientToBackground queue.

send(clientToBackground,"stop");

Poll for the final status message, wait for the parfeval computation to complete, and retrieve the accumulated result using the fetchOutputs function.

backgroundStatus = poll(backgroundToClient,inf)

backgroundStatus = "Stopped processing data in the background."

wait(future) out = fetchOutputs(future)

Extended Capabilities

Version History

Introduced in R2017a

expand all

Use the close object function to close a PollableDataQueue object. When you close aPollableDataQueue, you change the isClosed property to true and you can no longer send data using thePollableDataQueue object.

You can specify the destination behavior of a PollableDataQueue object using the Destination name-value argument. For example, to create a PollableDataQueue object that can send messages or data to the client session or background, set theDestination name-value argument to "any".