Future
Function scheduled to run
Description
A Future object represents a function that you schedule to run in
MATLAB®.
If you use
parfevalorparfevalOnAllto create aFuture, MATLAB runs the function:In the background, if you specify
backgroundPoolwhen creating theFuture.On a parallel pool, if you do not specify
backgroundPoolwhen creating theFuture, have Parallel Computing Toolbox™ and one of the following applies:You have a parallel pool currently open.
You have automatic pool creation enabled.
In serial, otherwise.
If you use
afterEachorafterAllto create aFuture, the function is run by your current MATLAB session. It is not run in the background or on any parallel pool.
Creation
You create a Future object when you do one of the following:
Use
parfevalto schedule a function to run in the background, on a parallel pool, or in serial.Use
parfevalOnAllto schedule a function to run on all workers in a pool, or in serial.Use
afterEachorafterAllto schedule a function to run afterFutureobjects finish.
The available types of future objects follow.
| Future Object | Description |
|---|---|
FevalFuture | Created by parfeval |
FevalOnAllFuture | Created by parfevalOnAll |
AfterEachFuture | Created by afterEach |
AfterAllFuture | Created by afterAll |
Properties
Object Functions
Examples
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);
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
This example shows how to stop a MATLAB function that you are running in the background. When you use parfeval to run a function in the background, MATLAB immediately returns a Future object. Long-running functions can block other functions from running in the background. To stop the function from running, you must use the cancel function instead of selecting Live Editor > Run > Stop.
Use parfeval to run pause(Inf) without retrieving any outputs. 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,@pause,0,Inf);
Check the state of the Future object.
f.State
ans = 'running'
When you run parfeval, you schedule a function to run in the background. When the background pool has insufficient resources to run the function, the Future is in the 'queued' state. When the function is run by the background pool, the Future is in the 'running' state.
To stop the function from running in the background, cancel the Future object.
cancel(f) f.State
ans = 'finished'
The function is now in the 'finished' state.
When you run a function in the background using parfeval, you create a Future object. If you have multiple parfeval computations running in the background, you can keep track of the computations by storing the Future objects in an array.
For efficiency, preallocate an array of Future objects.
N = 100; F(1:N) = parallel.Future;
Run a for-loop with N iterations. In each iteration, use parfeval to compute the rank of magic squares in the background. Store each Future object in the array of Future objects, F.
for idx = 1:N F(idx) = parfeval(backgroundPool,@rank,1,magic(idx)); end
You can retrieve the outputs from the individual Future objects as they become available by using the fetchNext function. Alternatively, use the fetchOutputs function to wait for all the computations to finish before retrieving outputs from all the Future objects.
out = fetchOutputs(F);
disp("Background computations complete.")Background computations complete.
Tips
Futureobjects are local objects and can be accessed only in the MATLAB session that created them.For example, if you use
parfevalto run a function in the background and create aFutureobject, theFutureis not available in the workspace of background workers.
Extended Capabilities
Version History
Introduced in R2013b
See Also
parallel.Pool (Parallel Computing Toolbox) | parfeval (Parallel Computing Toolbox) | parfevalOnAll (Parallel Computing Toolbox) | afterAll | afterEach
