Main Content

fetchNext

Retrieve next unread outputs from Future array

    Description

    example

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

    [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