poll - Retrieve data from PollableDataQueue - MATLAB (original) (raw)

Retrieve data from PollableDataQueue

Syntax

Description

[data](#mw%5F05dee558-ad5c-4689-904b-0fe9147da410) = poll([q](#mw%5Fdda4dbb3-95f2-451a-b43b-af3118672d3a)) retrieves one item of data from the PollableDataQueue object q. Send data from the background or your current MATLAB® session using send.

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

If no data is in the queue, poll returns[].
If data is in the queue, poll returns the oldest item of data in the queue, even if the queue is closed.
If the queue is closed and no data is in the queue, poll returns [].

[data](#mw%5F05dee558-ad5c-4689-904b-0fe9147da410) = poll([q](#mw%5Fdda4dbb3-95f2-451a-b43b-af3118672d3a),[timeout](#mw%5F8fc9b947-4cc4-4422-8894-73c4c27d693e)) waits timeout seconds to retrieve an item of data from thePollableDataQueue object q.

If data is in the queue, poll returns the oldest item of data in the queue, even if the queue is closed.
If no data is in the queue, poll waits up totimeout seconds. If the queue receives data beforetimeout seconds elapse, poll returns that item. If no data is received in the queue before timeout seconds elapse, poll returns [].
If the queue is closed or is closed during timeout and no data is in the queue,poll does not wait and returns [].

example

[[data](#mw%5F05dee558-ad5c-4689-904b-0fe9147da410),[tf](#mw%5F84199d1c-f3dc-4347-8407-3040b686be7d)] = poll(___) tries to retrieve data from a queue and returns a flagtf. If poll returns data,tf is true. Otherwise, tf isfalse.

You can use this syntax with any of the input argument combinations in the previous syntaxes. For example, [data,tf] = poll(q,5) waits to retrieve data from the queue q for five seconds.

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

Input Arguments

collapse all

Queue, specified as a PollableDataQueue object.

The destination behavior of the queue, set using the Destination argument of the parallel.pool.PollableDataQueue function, determines where you can poll for data:

If you create a PollableDataQueue object without setting theDestination argument, or set Destination to "creator", only the client session or background worker that creates the queue can poll it to receive data.
If you set Destination to "any", the client session or background worker can poll the queue to receive data. The data waits in the queue and is sent to either the client session or background worker that polls the queue.

Before R2025a: You must callpoll on the client session or background worker in which you created the pollable data queue.

If you close aPollableDataQueue using the close function, you can no longer send data to the queue but you can continue poll for data in the queue. (since R2025a)

Seconds to wait for, specified as a real numeric scalar.

Example: timeout = 5;

Example: timeout = single(3.14);

Output Arguments

collapse all

Data sent to the queue, specified as scalar, vector, matrix, or multidimensional array.

Flag to specify if data has been returned, returned as true orfalse.

Extended Capabilities

Version History

Introduced in R2017a