fetchNext

Retrieve next unread outputs fromFuturearray

Syntax

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

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

Description

[idx,Y1,...,Ym] = fetchNext(F)retrieves the linear indexidxof the next unreadFutureobject in the arrayFthat is finished, andmresults from thatFutureasY1,...,Ym.

You can only usefetchNextwithFutureobjects you create usingparfeval.

AFutureis unread if itsReadproperty isfalse. IfFhas no unread elements, MATLAB^®throws an error.
AFutureis finished if itsStateproperty is'finished'. If no unread elements are in the'finished'state, MATLAB first waits for an element ofFto finish.

fetchNextreads elements fromFin order of completion. AfterfetchNextretrieves the outputs from the next unreadFutureobject in the arrayF, MATLAB sets theReadproperty of thatFuturetotrue.

IffetchNextreads an element fromFthat encounters an error, the function first sets theReadproperty of theFutureelement to true. Then,fetchNextthrows an error.

[idx,Y1,...,Ym] = fetchNext(F,timeout)waits for a maximum oftimeoutseconds for a result inFto become available.

If no element of theFuturearrayF后未读timeoutseconds elapse,idxand all other output arguments are empty.

Examples

collapse all

Cancel Array of Futures

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

N = 100;foridx = N:-1:1 f(idx) = parfeval(backgroundPool,@rand,1);% Create a random scalarendresult = NaN;% No result yetforidx = 1:N [~, thisResult] = fetchNext(f);ifthisResult > 0.95 result = thisResult;% Have all the results needed, so breakbreak;endend% With required result, cancel any remaining futurescancel(F) result

Update Progress Bar Using`fetchNext`

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

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

Input Arguments

collapse all

`F`—Input`Future`
`parallel.FevalFuture`scalar|`parallel.FevalFuture`array

InputFutureobject, specified as aparallel.FevalFuturescalar or array.

You can only usefetchNextwithFutureobjects you create usingparfeval.

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

`timeout`—瑞士nds to wait for
real numeric scalar

瑞士nds to wait for, specified as a real numeric scalar.

Example:timeout = 5;

Example:timeout = single(3.14);

Output Arguments

collapse all

`idx`— Index
integer scalar

Index of theFuturearray, 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 ofFwith indexidx.

The element ofFwith indexidx必须返回moutput arguments. To check how many output arguments aFuturehas, use theNumOutputArgumentsproperty.

fetchNext

Syntax

Description