coder.extrinsic
Declare a function as extrinsic and execute it in MATLAB
Syntax
Description
coder.extrinsic(
declares
function
)function
as an extrinsic function. The code generator does not
produce code for the body of the extrinsic function and instead uses the MATLAB® engine to execute the call. This functionality is available only when the
MATLAB engine is available during execution. Examples of situations where the
MATLAB engine is available include execution of MEX functions, Simulink® simulations, or function calls at the time of code generation (also known as
compile time).
During standalone code generation, the code generator attempts to determine whether an extrinsic function only has a side effect (for example, by displaying a plot) or whether it affects the output of the function in which it is called (for example, by returning a value to an output variable). If there is no change to the output, the code generator proceeds with code generation, but excludes the extrinsic function from the generated code. Otherwise, the code generator produces a compilation error.
You cannot use coder.ceval
on functions that you declare as
extrinsic by using coder.extrinsic
. Also, the
coder.extrinsic
directive is ignored outside of code
generation.
See Use MATLAB Engine to Execute a Function Call in Generated Code.
Note
The code generator automatically treats many common MATLAB visualization functions, such as plot
,
disp
, and figure
, as extrinsic. You do not
have to explicitly declare them as extrinsic functions by using
coder.extrinsic
.
coder.extrinsic(function1, ... ,functionN)
declares
function1
through functionN
as extrinsic
functions.
coder.extrinsic(
enables synchronization of global data between MATLAB execution and generated code execution or Simulink simulation before and after calls to the extrinsic functions
'-sync:on'
, function1, ... ,functionN)function1
through functionN
. If only a few
extrinsic calls use or modify global data, turn off synchronization before and after
all extrinsic function calls by setting the global
synchronization mode to At MEX-function entry and exit
. Use the
'-sync:on'
option to turn on synchronization for only the extrinsic
calls that do modify global data.
If you use MATLAB
Coder™ to generate a MEX function, the '-sync:on'
option
enables verification of consistency of constant global data between MATLAB and MEX functions after calls to the extrinsic functions.
coder.extrinsic(
disables synchronization of global data between MATLAB execution and generated code execution before and after calls to the
extrinsic functions '-sync:off'
, function1, ... ,functionN)function1
through functionN
. If
most extrinsic calls use or modify global data, but a few do not, use the
'-sync:off'
option to turn off synchronization for the extrinsic
calls that do not modify global data.
If you use MATLAB
Coder to generate a MEX function, the '-sync:off'
option
disables verification of consistency of constant global data between MATLAB and MEX functions after calls to the extrinsic functions.
Examples
Input Arguments
Limitations
Extrinsic function calls have some overhead that can affect performance. Input data that is passed in an extrinsic function call must be provided to MATLAB, which requires making a copy of the data. If the function has any output data, this data must be transferred back into the MEX function environment, which also requires a copy.
The code generator does not support the use of
coder.extrinsic
to call functions that are located in a private folder.The code generator does not support the use of
coder.extrinsic
to call local functions.
Tips
The code generator automatically treats many common MATLAB visualization functions, such as
plot
,disp
, andfigure
, as extrinsic. You do not have to explicitly declare them as extrinsic functions by usingcoder.extrinsic
.Use the
coder.screener
function to detect which functions you must declare as extrinsic. This function runs the Code Generation Readiness Tool that screens the MATLAB code for features and functions that are not supported for code generation.
Extended Capabilities
Version History
Introduced in R2011a