Main Content

fetchNext

Retrieve next unread outputs from Future array

collapse all in page

    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 FevalFuture object in the array F that is finished, and m results from that Future as Y1,...,Ym.

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

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

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

    example

    [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

    collapse all

    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

    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

    collapse all

    Input FevalFuture 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);

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

    Example: timeout = 5;

    Example: timeout = single(3.14);

    Output Arguments

    collapse all

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

    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.

    Version History

    Introduced in R2013b

    See Also

    |