poll

Retrieve data from PollableDataQueue

collapse all in page

    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, even if the queue is closed.

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

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

    example

    [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

    collapse all

    Open Live Script

    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

    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 the Destination 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 call poll on the client session or background 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)

    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.

    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 or false.

    Extended Capabilities

    expand all

    Version History

    Introduced in R2017a

    See Also

    | | | | |