poll

Retrieve data sent to a 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 specified by pollablequeue. You can send data from the client or any worker but you must call poll on the client or worker in which you created the pollable data queue.

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

• If 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.

• 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 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 a Message in a parfor-loop, and Poll for the Result

Construct a PollableDataQueue.

p = parallel.pool.PollableDataQueue;

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

parfor i = 1
    send(p,i); 
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

parallel.pool.PollableDataQueue

Pollable data queue, specified as a parallel.pool.PollableDataQueue object.

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, specified 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 true or false.

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

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