Main Content

afterEach

Run function after each function finishes running in the background

collapse all in page

    Syntax

    B = afterEach(A,fcn,n)
    B = afterEach(A,fcn,n,PassFuture=true)

    Description

    example

    B = afterEach(A,fcn,n) runs the function fcn automatically after each element in the Future array A finishes and returns a Future object B.

    MATLAB® runs the function fcn using the outputs from each element in A. If the Future array A has M elements, MATLAB runs the function M times. When the scheduled function fcn finishes for the Mth time, the Future object B finishes.

    For more information about using afterEach to run functions after they finish running on a parallel pool, see Use afterEach and afterAll to Run Callback Functions (Parallel Computing Toolbox).

    If any of the elements in A encounters an error, the Error property of B is a cell array with the same number of elements as A.

    B = afterEach(A,fcn,n,PassFuture=true) runs fcn using each element in A instead of the outputs of each element in A.

    The Error property of B is an empty cell array, even if one or more elements in A encounter an error.

    Examples

    collapse all

    Open Live Script

    This example shows how to use afterEach to schedule a callback function to run after a function finishes running in the background.

    Use parfeval to run the function rand(1) and retrieve one output. Specify backgroundPool as the first argument to run the function in the background. Repeat 10 times to create 10 Future objects.

    for i = 1:10
    f(i) = parfeval(backgroundPool,@rand, 1, 1);
end

    After each Future finishes, display the value using the disp function. The input arguments for disp are the output arguments from each Future. Specify the third argument to the afterEach function as 0 to return no outputs from the callback.

    afterEach(f,@disp,0);
    Open Live Script

    This example shows how to use afterEach to update a wait bar with the progress of functions running in the background.

    Create a wait bar, w.

    w = waitbar(0,'Please wait ...');

    Set the number of iterations for your for-loop, N. Store the current number of completed iterations, 0, and the total number of iterations, N, in the UserData property of the wait bar.

    N = 20;
w.UserData = [0 N];

    Run a for-loop with N iterations. In each iteration, use parfeval and backgroundPool to run pause in the background for a random number of seconds. Store each Future object in an array.

    for i = 1:N
    delay = rand;
    f(i) = parfeval(backgroundPool,@pause,0,delay);
end

    Use the helper function updateWaitbar to update the waitbar after each Future finishes.

    afterEach(f,@(~)updateWaitbar(w),0);

    Use delete to close the wait bar after all the Future objects finish.

    afterAll(f,@(~)delete(w),0);

    Define Helper Function

    Define the helper function updateWaitbar. The function increments the first element of the UserData property, then uses the vector to calculate the progress.

    function updateWaitbar(w)
    % Update a waitbar using the UserData property.

    % Check if the waitbar is a reference to a deleted object
    if isvalid(w)
        % Increment the number of completed iterations 
        w.UserData(1) = w.UserData(1) + 1;

        % Calculate the progress
        progress = w.UserData(1) / w.UserData(2);

        % Update the waitbar
        waitbar(progress,w);
    end
end

    Input Arguments

    collapse all

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

    MATLAB runs the function fcn after each element in A finishes. If any of the elements in A encounters an error and you specify PassFuture as true, afterEach still runs fcn using that element.

    • If you specify PassFuture as true, MATLAB runs fcn(Aj) after each Future element Aj in A finishes.

      The Error property of B is an empty cell array, even if one or more elements in A encounter an error.

    • Otherwise, MATLAB runs fcn(X1,...,Xm) using the outputs X1,...,Xm from each Future element in A as the elements finish.

      If any of the elements in A encounters an error and you specify PassFuture as true, the Error property of B is a cell array with the same number of elements as A.

    If the Future array has M elements, MATLAB runs the function M times. When the scheduled function fcn finishes, the Future object B finishes.

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

    Callback function to run, specified as a function handle.

    Example: fcn = @magic

    Number of output arguments, specified as a nonnegative integer scalar.

    • If you specify PassFuture as true, n is the number of output arguments requested from running fcn(A(j)) using each element A(j) in the Future array A.

    • Otherwise, n is the number of output arguments requested from running fcn(Y1,...,Ym) using the outputs Y1,...,Ym from each element Aj in the Future array A.

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

    Output Arguments

    collapse all

    Output Future object, returned as a parallel.Future object.

    • Use fetchOutputs to retrieve results from B.

    • Use afterEach or afterAll to run a function when B completes.

    When you set PassFuture, you change the Error property of B:

    • If PassFuture is true, the Error property of B is an empty cell array, even if one or more elements in A encounter an error.

    • Otherwise, if any of the elements in A encounters an error, the Error property of B is a cell array with the same number of elements as A.

    Version History

    Introduced in R2018a

    See Also

    | |