parallel.pool.PollableDataQueue

Send and manually retrieve data

expand all in page

    Description

    Use a PollableDataQueue object to send data from a function that you run in the background or in your current MATLAB® session.

    You can send data from a function that you run on a parallel pool if you have Parallel Computing Toolbox™. For details, see parallel.pool.PollableDataQueue (Parallel Computing Toolbox).

    When you create a PollableDataQueue object, you create a connection to the MATLAB session or BackgroundPool worker that you can use to send and receive messages.

    • To send data to the MATLAB session or BackgroundPool worker that created the PollableDataQueue, use send.

    • To manually retrieve data after it is received in the MATLAB session or BackgroundPool worker, use poll.

    Creation

    Syntax

    q = parallel.pool.PollableDataQueue
    q = parallel.pool.PollableDataQueue(Destination=destination)

    Description

    q = parallel.pool.PollableDataQueue creates a PollableDataQueue object that you can use to send and manually retrieve messages. The resulting PollableDataQueue object can be polled only by the client session or BackgroundPool worker that creates it. Create the PollableDataQueue object on the BackgroundPool worker or client session where you want to receive the data.

    example

    q = parallel.pool.PollableDataQueue(Destination=destination) sets the destination behavior of the PollableDataQueue object. (since R2025a)

    If you want the client session and BackgroundPool worker to be able to poll the PollableDataQueue object to receive data, set Destination="any".

    example

    Input Arguments

    expand all

    Since R2025a

    Destination behavior of the queue, specified as one of these values:

    • "creator" — Allows only the client session or BackgroundPool worker that creates the queue to poll the queue and receive data. Any data sent to the queue is immediately sent to the client or worker that creates the queue.

    • "any" — Allows the client session or BackgroundPool worker to poll the queue to receive data. The data waits in the queue and is sent to either the client session or BackgroundPool worker that polls the queue, making that client session or worker the destination for the specific data.

    Properties

    expand all

    Since R2025a

    This property is read-only after you use the close object function.

    Queue closure state, represented as one of these values:

    • false — The queue is not closed and you can send data to the queue.

    • true — The queue is closed and you cannot send data to the queue. Any attempt to send data to the queue results in an error. You can continue to poll the queue for data. You cannot reopen a closed queue.

    Data Types: logical

    This property is read-only.

    Number of items of data waiting to be removed from the queue, specified as a zero or positive integer.

    The destination behavior of the queue, set using the Destination (Parallel Computing Toolbox) name-value argument, determines the QueueLength property value:

    • If you create a PollableDataQueue object without setting the Destination argument, or if you set Destination to "creator", the value is a 0 or positive integer in the MATLAB session or BackgroundPool worker that creates the PollableDataQueue object. Everywhere else, the value is 0.

      For example, if you create a PollableDataQueue object in the current MATLAB session, you can run a function in the background with that PollableDataQueue object as an input argument. The QueueLength property of that PollableDataQueue object is always 0 in the background.

    • If you set Destination to "any", the value is 0 or a positive integer on the client session and in the background.

      For example, if you create a PollableDataQueue object with the Destination to "any" in the current MATLAB session, you can run a function in the background with that PollableDataQueue object as an input argument. The QueueLength property of that PollableDataQueue object is either a 0 or positive integer in the current MATLAB session and in the background.

    Before R2025a: The QueueLength property value is 0 or a positive integer on the client session or BackgroundPool worker that creates the PollableDataQueue object. If the client session creates the PollableDataQueue object, the value is 0 on the BackgroundPool worker. If a BackgroundPool worker creates the PollableDataQueue, the value is 0 on the client session.

    Object Functions

    closeClose pollable data queue
    pollRetrieve data from PollableDataQueue
    sendSend data to DataQueue or PollableDataQueue

    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
    Open Live Script

    This example shows how to use a PollableDataQueue object to send data or instructions to the background during parfeval evaluations.

    You can use PollableDataQueue objects to transfer data and messages between the client session and the background. By default, a PollableDataQueue object sends the data only to the client session or background that creates the PollableDataQueue. However, starting in R2025a, you can also create a type of PollableDataQueue that allows the client session or background to poll and receive data.

    Define a function to run in the background. The processData function waits for data from the client session, processes it, and sends status updates back to the client. The function stops execution when it receives a "stop" message from the client session.

    function out = processData(backgroundToClient,clientToBackground)
out = 0;
send(backgroundToClient,"Ready to receive data.");
while true
    % Wait for a message from the client session
    data = poll(clientToBackground,Inf);
    if strcmp(data,"stop")
        send(backgroundToClient, ...
            "Stopped processing data in the background.")
        return
    else
        response = sprintf("Data %d received.",data(1));
        send(backgroundToClient,response);
        out = out+data(2);
        pause(1);
    end
end
end

    To simplify the communication between the client session and the background, create two PollableDataQueue objects.

    To enable communication from the background to the client session, create a default PollableDataQueue object. Only the client session can receive messages from the default PollableDataQueue object. The backgroundToClient queue sends messages from the background to the client session. 

    backgroundToClient = parallel.pool.PollableDataQueue;

    To enable communication from the client session to the background, create a PollableDataQueue object with the Destination argument set to "any". This type of PollableDataQueue object allows both the client session and the background to send and receive messages. The clientToBackground queue sends messages from the client session to the background.

    clientToBackground = parallel.pool.PollableDataQueue(Destination="any");

    Use parfeval to execute the processData function in the background and prepare the background to start waiting for data from the client session.

    future = parfeval(backgroundPool,@processData,1, ...
    backgroundToClient,clientToBackground);

    Poll the backgroundToClient queue to receive the initial status message from the background.

    backgroundStatus = poll(backgroundToClient,inf)
    backgroundStatus = 
"Ready to receive data."

    In a loop, send data to the background using the clientToBackground queue and poll the backgroundToClient queue for confirmation before sending the next data point.

    for idx = 1:5
    send(clientToBackground,[idx rand]);
    backgroundStatus = poll(backgroundToClient,inf)
end
    backgroundStatus = 
"Data 1 received."

    backgroundStatus = 
"Data 2 received."

    backgroundStatus = 
"Data 3 received."

    backgroundStatus = 
"Data 4 received."

    backgroundStatus = 
"Data 5 received."

    To stop execution in the background, send a "stop" message to the clientToBackground queue.

    send(clientToBackground,"stop");

    Poll for the final status message, wait for the parfeval computation to complete, and retrieve the accumulated result using the fetchOutputs function.

    backgroundStatus = poll(backgroundToClient,inf)
    backgroundStatus = 
"Stopped processing data in the background."

    wait(future)
out = fetchOutputs(future)
    out = 
3.3932

    Extended Capabilities

    expand all

    Version History

    Introduced in R2017a

    expand all

    See Also

    (Parallel Computing Toolbox) | | | | | (Parallel Computing Toolbox) | | (Parallel Computing Toolbox) | | (Parallel Computing Toolbox) | (Parallel Computing Toolbox)