Main Content

fetchOutputs

Retrieve results from function running in the background

    Description

    example

    [Y1,...,Ym] = fetchOutputs(F) retrieves m results from a Future array F.

    Each element in F must return at least m output arguments. To check how many output arguments a Future object has, use the NumOutputArguments property.

    MATLAB® waits for the function associated with each element in F to finish before retrieving results from that element. The State property of a Future object is 'finished' when the associated function is finished. When you use fetchOutputs, MATLAB sets the Read property of each element in F to true.

    You create a Future object when you use parfeval, parfevalOnAll, afterEach, or afterAll to:

    • Run a function in the background using backgroundPool.

    • Run a function on a parallel pool worker when you use Parallel Computing Toolbox™.

    If F is an array of Future objects, the jth output from each element in F is concatenated to form the output Yj. Use this syntax only if the jth output from each element can be concatenated along the first dimension.

    [Y1,...,Ym] = fetchOutputs(F,UniformOutput=false) retrieves m results as cell arrays from a Future array F.

    If F is an array of Future objects, the jth output from each element in F is concatenated in a cell array to form the output Yj. Use this syntax if you for any output Yj, you are unable to concatenate the output from each element along the first dimension.

    Examples

    collapse all

    This example shows how to run a function in the background using parfeval and backgroundPool. When you run a function in the background, you can run other MATLAB code at the same time.

    Use parfeval to run the function magic(3) and retrieve one output. Specify backgroundPool as the first argument to run the function in the background. When you use parfeval, you create a Future object.

    f = parfeval(backgroundPool,@magic,1,3);

    To retrieve the output from the background, use fetchOutputs. MATLAB returns the output once the execution of magic is complete.

    fetchOutputs(f)
    ans = 3×3
    
         8     1     6
         3     5     7
         4     9     2
    
    

    Input Arguments

    collapse all

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

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

    Output Arguments

    collapse all

    Output arguments from futures. The type of the outputs depends on the Future scalar or array f, and the functions each Future is associated with.

    • If UniformOutput is specified as false, the jth output argument is a cell array containing n elements, where n is the number of elements in F.

    • Otherwise, the jth output argument is an array of type returned by the jth output of each element in F.

    Each element in F must return at least m output arguments. To check how many output arguments a Future has, use the NumOutputArguments property.