coder.extrinsic

Declare extrinsic functions

collapse all in page

Syntax

coder.extrinsic(function)
coder.extrinsic(function1, ... ,functionN)
coder.extrinsic('-sync:on', function1, ... ,functionN)
coder.extrinsic('-sync:off', function1, ... ,functionN)

Description

example

coder.extrinsic(function) declares 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 during which 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 affects the output of the function in which it is called — for example by returning mxArrays to an output variable. Provided that 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.

coder.extrinsic is ignored outside of code generation.

coder.extrinsic(function1, ... ,functionN) declares function1 through functionN as extrinsic functions.

coder.extrinsic('-sync:on', function1, ... ,functionN) enables synchronization of global data between MATLAB and MEX functions before and after calls to the extrinsic functions 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.

See Generate Code for Global Data (MATLAB Coder).

coder.extrinsic('-sync:off', function1, ... ,functionN) disables synchronization of global data between MATLAB and MEX functions before and after calls to the extrinsic functions 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.

See Generate Code for Global Data (MATLAB Coder).

Examples

collapse all

The MATLAB function patch is not supported for code generation. This example shows how you can still use the functionality of patch in your generated MEX function by declaring patch as extrinsic your MATLAB function.

This MATLAB code declares patch as extrinsic in the local function create_plot. By declaring patch as extrinsic, you instruct the code generator not to produce code for patch. Instead, the code generator dispatches patch to MATLAB for execution.

The code generator automatically treats many common MATLAB visualization functions, such as the function axis as extrinsic.

function c = pythagoras(a,b,color) %#codegen
% Calculate the hypotenuse of a right triangle
% and display the triangle as a patch object. 
c = sqrt(a^2 + b^2);
create_plot(a, b, color);
end

function create_plot(a, b, color)
%Declare patch as extrinsic
coder.extrinsic('patch'); 
x = [0;a;a];
y = [0;0;b];
patch(x,y,color);
axis('equal');
end

Generate a MEX function for pythagoras. Also, generate the code generation report.

codegen -report pythagoras -args {1, 1, [.3 .3 .3]}

In the report, view the MATLAB code for create_plot.

The report highlights the patch and axis functions to indicate that they are treated as extrinsic functions.

Run the MEX function.

pythagoras_mex(3, 4, [1.0 0.0 0.0]);

MATLAB displays the plot of the right triangle as a red patch object.

Input Arguments

collapse all

Name of the MATLAB function that is declared as extrinsic.

Example: coder.extrinsic('patch')

Data Types: char

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, and figure, as extrinsic. You do not have to explicitly declare them as extrinsic functions by using coder.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.

See Also

|

Topics

Introduced in R2011a

Simulink Documentation

Support