Main Content

poll

Retrieve data from PollableDataQueue

    Description

    data = poll(q) retrieves one item of data from the PollableDataQueue object q. Send data from the background using send.

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

    example

    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, waits up to MATLAB® for timeout seconds. If data is received in the queue 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(___,timeout) tries to retrieve data from a queue and returns a flag tf. If poll was able to return 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) tries to retrieve data from the queue q for five seconds.

    Examples

    collapse all

    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 parallel.pool.PollableDataQueue object.

    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.

    Introduced in R2017a