poll

Retrieve data from PollableDataQueue

Syntax

data = poll(q)

data = poll(q,timeout)

[data,tf] = poll(___)

Description

data = poll(q) 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.

data = poll(q,timeout) waits timeout seconds to retrieve an item of data from the PollableDataQueue object q.

• If data is in the queue, poll returns the oldest item of data in the queue.

• If no data is in the queue, poll waits up to timeout seconds. If the queue receives data before timeout seconds elapse, poll returns that item. If no data is received in the queue before timeout seconds elapse, poll returns [].

[data,tf] = poll(___) tries to retrieve data from a queue and returns a flag tf. If poll returns data, tf is true. Otherwise, tf is false.

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

Manually Retrieve Data Sent from the Background

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.

fetchOutputs(f)

ans = 3×3

     8     1     6
     3     5     7
     4     9     2

Use the poll function to collect data from the queue.

poll(q)

ans = 45

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

q — Queue

parallel.pool.PollableDataQueue object

Queue, specified as a parallel.pool.PollableDataQueue object.

timeout — Seconds to wait for

real numeric scalar

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

Example: timeout = 5;

Example: timeout = single(3.14);

Output Arguments

data — Data sent to queue

scalar | vector | matrix | multidimensional array

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

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | struct | table | cell | function_handle | categorical | datetime | duration | calendarDuration

tf — Flag to specify if data has been returned

true | false

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

Extended Capabilities

Thread-Based Environment

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

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

Version History

Introduced in R2017a