Documentation

coder.extrinsic

Package: coder

Declare extrinsic function or functions

Syntax

coder.extrinsic('function_name');

coder.extrinsic('function_name_1', ... , 'function_name_n');

coder.extrinsic('-sync:on', 'function_name');

coder.extrinsic('-sync:on', 'function_name_1', ... , 'function_name_n');

coder.extrinsic('-sync:off','function_name');

coder.extrinsic('-sync:off', 'function_name_1', ... , 'function_name_n');

Arguments

function_name
function_name_1, ... , function_name_n

Declares function_name or function_name_1 through function_name_n as extrinsic functions.

–sync:on

function_name or function_name_1 through function_name_n.

Enables synchronization of global data between MATLAB® and MEX functions before and after calls to the extrinsic functions, function_name or function_name_1 through function_name_n. If only a few extrinsic calls 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.

–sync:off

Disables synchronization of global data between MATLAB and MEX functions before and after calls to the extrinsic functions, function_name or function_name_1 through function_name_n. If most extrinsic calls modify global data, but a few do not, you can use the –sync:off option to turn off synchronization for the extrinsic calls that do not modify global data.

Description

coder.extrinsic declares extrinsic functions. During simulation, the code generation software generates code for the call to an extrinsic function, but does not generate the function's internal code. Therefore, simulation can run only on platforms where MATLAB software is installed. During standalone code generation, MATLAB attempts to determine whether the 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, MATLAB proceeds with code generation, but excludes the extrinsic function from the generated code. Otherwise, compilation errors occur.

You cannot use coder.ceval on functions that you declare extrinsic by using coder.extrinsic.

coder.extrinsic is ignored outside of code generation.

Tips

  • The code generation software detects calls to many common visualization functions, such as plot, disp, and figure. The software treats these functions like extrinsic functions, but you do not have to declare them extrinsic using the coder.extrinsic function.

  • Use the coder.screener function to detect which functions you must declare extrinsic. This function opens the code generations readiness tool that detects code generation issues in your MATLAB code.

    During code generation, MATLAB attempts to determine whether the 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, MATLAB proceeds with code generation, but excludes the extrinsic function from the generated code. Otherwise, a MATLAB issues a compiler error.

Examples

The following code declares the MATLAB functions patch and axis extrinsic in the MATLAB local function create_plot:

function c = pythagoras(a,b,color) %#codegen
% Calculates the hypotenuse of a right triangle
%  and displays the triangle as a patch object. 

c = sqrt(a^2 + b^2);

create_plot(a, b, color);

function create_plot(a, b, color)
%Declare patch and axis as extrinsic

coder.extrinsic('patch', 'axis'); 

x = [0;a;a];
y = [0;0;b];
patch(x, y, color);
axis('equal');

By declaring these functions extrinsic, you instruct the software not to compile or generate code for patch and axis. Instead it dispatches these functions to MATLAB for execution.

Was this topic helpful?