fetchNext

Retrieve next unread outputs from Future array

Syntax

[idx,Y1,...,Ym] = fetchNext(F)

[idx,Y1,...,Ym] = fetchNext(F,timeout)

Description

[idx,Y1,...,Ym] = fetchNext(F) retrieves the linear index idx of the next unread Future object in the array F that is finished, and m results from that Future as Y1,...,Ym.

You can only use fetchNext with Future objects you create using parfeval.

• A Future is unread if its Read property is false. If F has no unread elements, MATLAB^® throws an error.

• A Future is finished if its State property is 'finished'. If no unread elements are in the 'finished' state, MATLAB first waits for an element of F to finish.

fetchNext reads elements from F in order of completion. After fetchNext retrieves the outputs from the next unread Future object in the array F, MATLAB sets the Read property of that Future to true.

If fetchNext reads an element from F that encounters an error, the function first sets the Read property of the Future element to true. Then, fetchNext throws an error.

[idx,Y1,...,Ym] = fetchNext(F,timeout) waits for a maximum of timeout seconds for a result in F to become available.

If no element of the Future array F is unread after timeout seconds elapse, idx and all other output arguments are empty.

Examples

Cancel Array of Futures

Run a function several times until a satisfactory result is found. In this case, the array of futures f is cancelled when a result is greater than 0.95.

N = 100;
for idx = N:-1:1
    F(idx) = parfeval(backgroundPool,@rand,1); % Create a random scalar
end
result = NaN; % No result yet
for idx = 1:N
    [~, thisResult] = fetchNext(F);
    if thisResult > 0.95
        result = thisResult;
        % Have all the results needed, so break
        break;
    end
end
% With required result, cancel any remaining futures
cancel(F)
result

Update Progress Bar Using fetchNext

Request several function evaluations, and update a progress bar while waiting for completion.

N = 100;
for idx = N:-1:1
    % Compute the rank of N magic squares
    F(idx) = parfeval(backgroundPool,@rank,1,magic(idx));
end % Build a waitbar to track progress
h = waitbar(0,'Waiting for FevalFutures to complete...');
results = zeros(1,N);
for idx = 1:N
    [completedIdx,thisResult] = fetchNext(F);
    % Store the result
    results(completedIdx) = thisResult;
    % Update waitbar
    waitbar(idx/N,h,sprintf('Latest result: %d',thisResult));
end
delete(h)

Input Arguments

F — Input Future

parallel.FevalFuture scalar | parallel.FevalFuture array

Input Future object, specified as a parallel.FevalFuture scalar or array.

You can only use fetchNext with Future objects you create using parfeval.

Example: F = parfeval(backgroundPool,@magic,1,3);

timeout — Seconds to wait for

real numeric scalar

Seconds to wait for, specified as a real numeric scalar.

Example: timeout = 5;

Example: timeout = single(3.14);

Output Arguments

idx — Index

integer scalar

Index of the Future array, returned as an integer scalar.

Y1,...,Ym — Output arguments from future

depends on function

Output arguments from future. The type of the outputs depends on the function associated with the element of F with index idx.

The element of F with index idx must return m output arguments. To check how many output arguments a Future has, use the NumOutputArguments property.