Main Content

parallel.pool.PollableDataQueue

Send and poll data between client and workers

expand all in page

    Description

    PollableDataQueue enables synchronous sending and polling for data or messages between workers and client in a parallel pool while a computation is being carried out. You can get intermediate values and progress of the computation.

    To send data from a parallel pool worker back to the client, first construct a PollableDataQueue in the client. Pass this PollableDataQueue into a parfor-loop or other parallel language construct, such as parfeval. From the workers, call send to send data back to the client. At the client, use poll to retrieve the result of a message or data sent from a worker.

    • You can call send from the worker or client that created the PollableDataQueue, if required.

    • You can construct the queue on the workers and send it back to the client to enable communication in the reverse direction. However, you cannot send a queue from one worker to another. Use spmd, spmdSend, or spmdReceive instead.

    • Unlike all other handle objects, PollableDataQueue and DataQueue instances do remain connected when they are sent to workers.

    Creation

    Syntax

    p = parallel.pool.PollableDataQueue

    Description

    example

    p = parallel.pool.PollableDataQueue creates an object that can be used to send and poll for messages (or data) from different workers. Create the PollableDataQueue on the worker or client where you want to receive the data.

    Properties

    expand all

    This property is read-only.

    The number of items of data waiting to be removed from the queue, specified as a zero or positive integer. The value is 0 or a positive integer on the worker or client that creates the PollableDataQueue instance. If the client creates the PollableDataQueue instance, the value is 0 on all workers. If a worker creates the PollableDataQueue, the value is 0 on the client and all other workers.

    Object Functions

    poll Retrieve data sent from a worker
    sendSend data from worker to client using a data queue

    Examples

    collapse all

    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 polling for data using a PollableDataQueue, see poll.

    Open Live Script

    When you send a message to a PollableDataQueue object, the message waits in the queue. Each message adds 1 to the queue length. When you use poll, one message is collected from the queue. In this example, you use the QueueLength property to find the length of a PollableDataQueue object.

    When a client or worker creates a PollableDataQueue object, any messages that are sent to the queue are held in the memory of that client or worker. If the client creates a DataQueue object, the QueueLength property on all workers is 0. In this example, you create a PollableDataQueue object on the client, and send data from a worker.

    First, create a parallel pool with one worker.

    parpool(1);
    Starting parallel pool (parpool) using the 'local' profile ...
Connected to the parallel pool (number of workers: 1).

    Create a PollableDataQueue.

    pdq = parallel.pool.PollableDataQueue
    pdq = 
  PollableDataQueue with properties:

    QueueLength: 0

    A newly created PollableDataQueue has an empty queue. You can use parfor to find pdq.QueueLength on the worker. Find the queue length on the client, and the queue length on the worker.

    fprintf('On the client: %i\n', pdq.QueueLength)
    On the client: 0

    parfor i = 1
    fprintf('On the worker: %i\n', pdq.QueueLength)
end
    On the worker: 0

    As the queue is empty, the QueueLength is 0 for both the client and the worker. Next, send a message to the queue. Then, use the QueueLength property to find the length of the queue.

    % Send a message first
parfor i = 1
    send(pdq, 'A message');
end

% Find the length
fprintf('On the client: %i\n', pdq.QueueLength)
    On the client: 1

    parfor i = 1
    fprintf('On the worker: %i\n', pdq.QueueLength)
end
    On the worker: 0

    The QueueLength property is 1 on the client, and 0 on the worker. Use poll to retrieve the message from the queue.

    msg = poll(pdq);
disp(msg)
    A message

    Use the QueueLength property to find the length of the queue.

    fprintf('On the client: %i\n', pdq.QueueLength)
    On the client: 0

    QueueLength is 0 because the queue processing is complete.

    Version History

    Introduced in R2017a

    See Also

    | | | | | | | |

    Topics