poll

Retrieve data sent to pollable data queue

Syntax

data = poll(pollablequeue)

data = poll(pollablequeue,timeout)

[data,tf] = poll(___)

Description

data = poll(pollablequeue) retrieves one item of data from the parallel.pool.PollableDataQueue object specified by pollablequeue.

• 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 returns [].

• If the queue is closed and no data is in the queue, poll returns [].

data = poll(pollablequeue,timeout) waits timeout seconds to retrieve data from the PollableDataQueue object pollablequeue.

• 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 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 [].

• If the queue is closed or is closed during timeout and no data is in the queue, poll does not wait and returns [].

[data,tf] = poll(___) tries to retrieve data from the queue. If poll returns data, tf is true.

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

Examples

Send Message and Poll for Result

Create a PollableDataQueue object.

p = parallel.pool.PollableDataQueue;

Run a parfor-loop, and send a message, such as data with the value 1.

parfor idx = 1
    send(p,idx); 
end

Poll for the result.

poll(p)

1

For more details on sending data using a PollableDataQueue, see send.

Send and Poll for Data While Using parfeval

This example shows how to return intermediate results from a worker to the client and to display the result on the client.

Construct a PollableDataQueue. A PollableDataQueue is most useful for sending and polling for data during asynchronous function evaluations using parfeval or parfevalOnAll.

q = parallel.pool.PollableDataQueue;

Start a timer and send the data queue as input to the function for parfeval execution on the pool. Display the time elapsed and the data returned.

f = parfeval(@workerFcn, 0, q);
msgsReceived = 0;
starttime = tic;
while msgsReceived < 2
    [data, gotMsg] = poll(q, 1);
    if gotMsg
        fprintf('Got message: %s after %.3g seconds\n', ...
            data, toc(starttime));
        msgsReceived = msgsReceived + 1;
    else
        fprintf('No message available at %.3g seconds\n', ...
            toc(starttime));
    end
end

function workerFcn(q)
    send(q,'start');
    pause(3);
    send(q,'stop');
end

Got message: start after 0.39 seconds
No message available at 1.48 seconds
No message available at 2.56 seconds
Got message: stop after 3.35 seconds

The first message is returned in 0.39 s after you have executed parfeval. In that time the data and function for parfeval have been serialized, sent over to the workers, deserialized and set running. When you start the code, the worker sends some data, which is serialized, sent over the network back to the client and put on a data queue. poll notes this operation and returns the value to the client function. Then the time taken since parfeval was called is displayed. Note a delay of 3 s while the worker is computing something (in this case a long pause).

Input Arguments

pollablequeue — Pollable data queue

PollableDataQueue

Pollable data 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 the Destinationargument, or set Destination to "creator", only the client or worker that creates the queue can poll it to receive data.

• If you set Destination to "any", the client or any worker can poll the queue to receive data. The data waits in the queue and is sent to whichever client or worker polls the queue.

Before R2025a: You must call poll on the client or worker in which you created the pollable data queue.

If you close a PollableDataQueue 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)

Example: data = poll(pollablequeue);

timeout — Optional timeout

scalar

Optional timeout interval (in seconds) used to block poll before returning, specified as a scalar.

Example: data = poll(pollablequeue,timeout);

Output Arguments

data — Message or data

scalar | vector | matrix | array | string | character vector

Message or data sent to a data queue, returned as any serializable value.

Example: data = poll(pollablequeue);

tf — Check if data has been returned

true | false

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

Example: [data,tf] = poll(pollablequeue,timeout);

Data Types: logical

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