fetchNext - Retrieve next unread outputs from Future array - MATLAB (original) (raw)

Retrieve next unread outputs from Future array

Syntax

Description

[[idx](#mw%5F11b31329-3bd1-4b42-99d7-5f43a165fba0),[Y1,...,Ym](#mw%5F587e412d-1986-4346-9693-e571fffc1571)] = fetchNext([F](#mw%5F433a215c-b0ef-48f6-835a-efd4eb510be1)) retrieves the linear index idx of the next unreadFevalFuture object in the array F that is finished, and m results from that Future asY1,...,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 thatFevalFuture to true.

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

example

[[idx](#mw%5F11b31329-3bd1-4b42-99d7-5f43a165fba0),[Y1,...,Ym](#mw%5F587e412d-1986-4346-9693-e571fffc1571)] = fetchNext([F](#mw%5F433a215c-b0ef-48f6-835a-efd4eb510be1),[timeout](#mw%5Fe774c3b2-830a-4501-936f-0a7079d119d2)) waits for a maximum of timeout seconds for a result inF 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 canceled 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, cancel any remaining futures cancel(F) break; end end

% Display results 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 aparallel.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 indexidx.

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

Version History

Introduced in R2013b