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 beforetimeout
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](#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
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
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 setDestination
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
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
Flag to specify if data has been returned, returned as true
orfalse
.
Extended Capabilities
Version History
Introduced in R2017a