Future
Function scheduled to run
Description
A Future
object represents a function that you schedule to run in
MATLAB®.
If you use
parfeval
orparfevalOnAll
to create aFuture
, MATLAB runs the function:In the background, if you specify
backgroundPool
when creating theFuture
.On a parallel pool, if you do not specify
backgroundPool
when 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
afterEach
orafterAll
to 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
parfeval
to schedule a function to run in the background, on a parallel pool, or in serial.Use
parfevalOnAll
to schedule a function to run on all workers in a pool, or in serial.Use
afterEach
orafterAll
to schedule a function to run afterFuture
objects 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
General Options
CreateDateTime
— Date and time when Future
was created
datetime
scalar
This property is read-only.
Date and time when the Future
object was created, specified as a
datetime
scalar.
Error
— Error information
exception
scalar | cell array
This property is read-only.
Error information, specified as an MException
scalar or cell
array of exception
objects.
If you create a
Future
object usingparfeval
orafterAll
, this property is a cell array orexception
scalar. If theFuture
object completes with no error, this property is empty.If you create a
Future
object usingafterEach
, this property is a cell array with one cell for each execution of theFuture
that errored, or a1
-by-1
cell array if theFuture
was canceled. If theFuture
object completes with no error, this property is empty.If you create a
Future
object usingparfevalOnAll
, this property is a cell array with one cell for each worker if any errors occurred on the workers, or a1
-by-1
cell array if theFuture
was canceled. If theFuture
object completes with no error, this property is empty.
For more information about errors encountered when you schedule a function to run
after Future
objects finish, see afterEach
and afterAll
.
FinishDateTime
— Date and time when function finished
datetime
scalar
This property is read-only.
Date and time when the function finished, specified as a datetime
scalar.
The Future
finishes running when MATLAB finishes running the function associated with it.
If the function associated with the Future
object is not finished
running, this property is an empty datetime
array.
Data Types: datetime
Function
— Function associated with Future
function_handle
This property is read-only.
Function associated with the Future
object, specified as a
function handle.
If you create the
Future
usingparfeval
orparfevalOnAll
, MATLAB runs the function in the background, on a parallel pool (if you have Parallel Computing Toolbox), or in serial.If you create the
Future
usingafterEach
orafterAll
, the function is run by your current MATLAB session. It is not run in the background or on any parallel pool.
Example: @magic
Data Types: function_handle
ID
— Identifier
integer scalar
This property is read-only.
Identifier, specified as an integer scalar.
Data Types: double
InputArguments
— Input arguments for function
cell array
This property is read-only.
Input arguments for the function, specified as a cell array.
When the scheduled function fcn
specified by the
Function
property runs, it runs as
fcn(X{:})
, where X
is the cell array of
input arguments specified by this property.
Example: {[1]}
Example: {[1,2], [2,1]}
Data Types: cell
NumOutputArguments
— Number of arguments returned by function
integer scalar
This property is read-only.
Number of arguments returned by the function, specified as an integer scalar.
The function specified by the Function
property must return
at least as many arguments as specified by this property.
Data Types: double
OutputArguments
— Output arguments from running function
cell array
This property is read-only.
Output arguments from running the function, specified as a cell array.
This property is an empty cell array if the Future
object is not
finished running or the Future
object completes with an error.
Example: {[3.14]}
Data Types: cell
RunningDuration
— Current duration of Future
duration
scalar
Current duration of the Future
object, specified as a
duration
scalar.
When the Future
object finishes running, this property becomes
constant.
StartDateTime
— Date and time when Future
started running
datetime
scalar
This property is read-only.
Date and time when the Future
object started running, specified
as a datetime
scalar.
The Future
starts running when MATLAB starts running the function associated with it.
Data Types: datetime
State
— Current state of future
'queued'
| 'running'
| 'finished'
| 'failed'
| 'unavailable'
This property is read-only.
Current state of the future, specified as one of these values:
'queued'
—Future
is queued, and the function associated with it is scheduled to run.'running'
— Function associated with theFuture
is currently running.'finished'
or'failed'
— Function associated with theFuture
is finished running.'unavailable'
—Future
is unable to run. Elements of a preallocatedFuture
array have this state.
FevalFuture
Options
Diary
— text output
character vector
This property is read-only.
Text output, specified as a character vector.
This property is a character vector containing all text that is displayed if you
explicitly run the functions specified by the Function
property
using the input arguments specified by the InputArguments
property.
Parent
— Queue of Future
objects
parallel.FevalQueue
object
This property is read-only.
Queue of Future
objects, specified as a
parallel.FevalQueue
object.
This property is equal to the queue of Future
objects given by
the FevalQueue
of the pool that the future is running on.
This property is not available for Future
objects that run
functions in a thread-based environment.
Read
— Flag indicating if outputs have been read
true
| false
This property is read-only.
Flag indicating if outputs have been read, specified as true
or
false
.
This property is set to true
only if you use
fetchOutputs
or fetchNext
.
Data Types: logical
FevalOnAllFuture
Options
Diary
— Text produced by execution of function
cell array of character vectors
This property is read-only.
Recorded text, specified as a cell array of character vectors.
This property is a cell array containing all text that is displayed if you
explicitly run the functions specified by the Function
property
using the input arguments specified by the InputArguments
property.
The jth element of the array is the text output
captured from the jth worker in the pool that ran the
Future
.
Data Types: cell
Parent
— Queue of Future
objects
parallel.FevalQueue
object
This property is read-only.
Queue of Future
objects, specified as a
parallel.FevalQueue
object.
This property is equal to the queue of Future
objects given by
the FevalQueue
of the pool that the future is running on.
This property is not available for Future
objects that run
functions in a thread-based environment.
Object Functions
General Functions
afterAll | Run function after all functions finish running in the background |
afterEach | Run function after each function finishes running in the background |
cancel | Stop function running in the background |
fetchOutputs | Retrieve results from function running in the background |
wait | Wait for futures to complete |
FevalFuture
Only
fetchNext | Retrieve next unread outputs from Future array |
Examples
Run Callback Function After Function Finishes Running in the Background
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);
Update Wait Bar While Functions Run in the Background
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
Stop Functions Running in Background
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.
Tips
Future
objects are local objects and can be accessed only in the MATLAB session that created them.For example, if you use
parfeval
to run a function in the background and create aFuture
object, theFuture
is not available in the workspace of background workers.
Extended Capabilities
Thread-Based Environment
Run code in the background using MATLAB® backgroundPool
or accelerate code with Parallel Computing Toolbox™ ThreadPool
.
This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.
Version History
Introduced in R2013b
See Also
parallel.Pool
(Parallel Computing Toolbox) | parfeval
(Parallel Computing Toolbox) | parfevalOnAll
(Parallel Computing Toolbox) | afterAll
| afterEach
Commande MATLAB
Vous avez cliqué sur un lien qui correspond à cette commande MATLAB :
Pour exécuter la commande, saisissez-la dans la fenêtre de commande de MATLAB. Les navigateurs web ne supportent pas les commandes MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)