coder.extrinsic - Declare function as extrinsic and execute it in MATLAB - MATLAB (original) (raw)

Declare function as extrinsic and execute it in MATLAB

Syntax

Description

coder.extrinsic([function](#mw%5F7fd3bed0-bfde-42c2-9075-74d0b2196e20)) declaresfunction 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, and function calls at the time of code generation (also known as compile time).

During the generation of standalone code, the code generator attempts to determine whether the extrinsic function affects the function in which it is called. If the extrinsic function does not affect the calling function (for example, the extrinsic function displays a plot), the code generator proceeds with code generation, but excludes the extrinsic function from the generated code. If the extrinsic function affects the calling function (for example, the extrinsic function returns a value to the calling function), the code generator produces a compilation error.

MATLAB ignores the coder.extrinsic directive outside of code generation.

See Use MATLAB Engine to Execute a Function Call in MATLAB Function Blocks.

Note

The run-time output of an extrinsic function is an mxArray, also known as a MATLAB array. The only valid operations for an mxArray are storing it in a variable, passing it to another extrinsic function, or returning it to MATLAB. To perform any other operation on anmxArray value, such as using it in an expression in your code, you must convert the mxArray to a known type by assigning themxArray to a variable whose type is already defined by a prior assignment. See Working with mxArrays (MATLAB Coder).

example

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

coder.extrinsic([syn](#mw%5Fb14823b7-e836-4958-b4da-84fa0efb946c), function1, ... ,functionN) controls synchronization of global data between your MATLAB code and the generated MEX file before and after the extrinsic function call. By default, the code generator synchronizes global variables before and after extrinsic function calls to maximize consistency between the MATLAB code and the MEX function. To learn how and when to change this default behavior, see Generate Code for Global Variables (MATLAB Coder).

Examples

collapse all

Define the local function convertStringToNumber, which displays the output of the MATLAB function str2num. Because str2num is not supported for code generation, you must declare this function as extrinsic in your MATLAB code. By declaring str2num as extrinsic, you instruct the code generator not to produce code for str2num. Instead, the code generator dispatches str2num to MATLAB for execution. convertStringToNumber displays the value returned by str2num using disp, which the code generator automatically treats as extrinsic.

type("convertStringToNumber.m")

function convertStringToNumber(c) %#codegen coder.extrinsic("str2num"); disp(str2num(c)); end

Generate MEX code for convertStringToNumber. Specify the input to be an unbounded character vector.

codegen convertStringToNumber -args {coder.typeof('c', [1 Inf])} -report

Code generation successful: View report

In the file convertStringToNumber.c, which you can view from the code generation report, you can see that no C code is generated for the MATLAB functions disp and str2num. Instead, the generated code sends these functions to MATLAB for execution using the internal function emlrtCallMATLABR2012b.

Call the generated MEX code for convertStringToNumber using a character vector:

convertStringToNumber_mex('123')

convertStringToNumber_mex('1,2,3')

convertStringToNumber_mex(num2str(1:10))

Define the local function returnStringToNumber, which returns the output of the MATLAB function str2num to MATLAB. Because str2num is not supported for code generation, you must declare this function as extrinsic in your MATLAB code. By declaring str2num as extrinsic, you instruct the code generator not to produce code for str2num. Instead, the code generator dispatches str2num to MATLAB for execution. The value that str2num returns at run time is an mxArray, also known as a MATLAB array. The only valid operations for an mxArray are storing it in a variable, passing it to another extrinsic function, or returning it to MATLAB. See Working with mxArrays (MATLAB Coder).

type returnStringToNumber.m

function num = returnStringToNumber(c) %#codegen coder.extrinsic("str2num"); num = str2num(c); end

Generate MEX code for returnStringToNumber. Specify the input to be an unbounded character vector.

codegen returnStringToNumber -args {coder.typeof('c', [1 Inf])} -report

Code generation successful: View report

In the code generation report, you can see that num is an mxArray.

Call the generated MEX code for returnStringToNumber using a character vector:

a = returnStringToNumber_mex('123')

b = returnStringToNumber_mex('1,2,3')

c = returnStringToNumber_mex(num2str(1:10))

c = 1×10

 1     2     3     4     5     6     7     8     9    10

Even though returnStringToNumber_mex returns an mxArray, MATLAB correctly interprets the output as a numeric vector.

Define the local function useStringToNumber, which displays different messages based on the output of the MATLAB function str2num. Because str2num is not supported for code generation, you must declare this function as extrinsic in your MATLAB code. By declaring str2num as extrinsic, you instruct the code generator not to produce code for str2num. Instead, the code generator dispatches str2num to MATLAB for execution. The value that str2num returns at run time is an mxArray, also known as a MATLAB array.

The only valid operations for an mxArray are storing it in a variable, passing it to another extrinsic function, or returning it to MATLAB. To perform any other operation on an mxArray value, such as using it in an expression in your code, you must convert the mxArray to a known type by assigning the mxArray to a variable whose type is already defined by a prior assignment. See Working with mxArrays (MATLAB Coder).

To use the mxArray that str2num returns in useStringToNumber, initialize num as a double before the extrinsic function call. At compile time, the code generator automatically converts the mxArray returned by str2num to a double, which you can then use in subsequent expressions. If you do not set num to a known type before using it in an expression, code generation fails.

function useStringToNumber(c) %#codegen coder.extrinsic("str2num"); num = 0; % initialize num as a scalar double num = str2num(c(1)); % force str2num to return a scalar double if num == 1 % because num is a known type, it can be used in expressions disp('Starts from one'); else disp('Does not start from one'); end end

Generate MEX code for useStringToNumber. Specify the input to be an unbounded character vector.

codegen useStringToNumber -args {coder.typeof('c', [1 Inf])} -report

Code generation successful: View report

In the code generation report, you can see that the output of str2num is an mxArray and num is a 1 x 1 double.

Call the generated MEX code for useStringToNumber using a character vector:

useStringToNumber_mex('1,2,3')

useStringToNumber_mex('3,2,1')

Define the local function useStringToNumberVarSize, which returns arrays of different sizes based on the output of the MATLAB function str2num. Because str2num is not supported for code generation, you must declare this function as extrinsic in your MATLAB code. By declaring str2num as extrinsic, you instruct the code generator not to produce code for str2num. Instead, the code generator dispatches str2num to MATLAB for execution. The value returned by str2num at run time is an mxArray, also known as a MATLAB array.

The only valid operations for an mxArray are storing it in a variable, passing it to another extrinsic function, or returning it to MATLAB. To perform any other operation on an mxArray value, such as using it in an expression in your code, you must convert the mxArray to a known type by assigning the mxArray to a variable whose type is already defined by a prior assignment. See Working with mxArrays (MATLAB Coder).

Because the size of the mxArray output of str2num is variable at run time, first initialize num as a known type (an empty array of doubles) and then declare num as variable-size using coder.varsize (MATLAB Coder). If you do not set num to a known type before using it, code generation fails. If you do not declare num as variable-size, MEX execution fails for all nonempty arrays. To learn more about handling variable-size data for code generation, see Generate Code for Variable-Size Arrays (MATLAB Coder).

type useStringToNumberVarSize.m

function num = useStringToNumberVarSize(c) %#codegen coder.extrinsic("str2num"); num = []; % initialize num as an empty array of doubles coder.varsize("num"); % declare num as variable-sized num = str2num(c); % because num is known to be variable-sized, the generated code does not error when passed a non-empty vector if numel(num) > 5 % because num is a known type and not an mxArray, it can be used in expressions num = num(1:5); end end

Generate MEX code for useStringToNumberVarSize. Specify the input to be an unbounded character vector.

codegen useStringToNumberVarSize -args {coder.typeof('c', [1 Inf])} -report

Code generation successful: View report

In the code generation report, you can see that the output of str2num is an mxArray and that num is a variable-size (:? x :?) array of doubles.

Call the generated MEX code for useStringToNumberVarSize using a character vector:

a = useStringToNumberVarSize_mex('1,2,3')

b = useStringToNumberVarSize_mex(num2str(1:10))

As expected, useStringToNumberVarSize_mex returns a 5-element numeric vector.

If you call an extrinsic function that returns a constant value, you can instruct the code generator to evaluate the extrinsic function at compile time using coder.const. The code generator will then use this constant in the generated code. You can use this coding pattern to generate standalone code that uses the output of extrinsic functions.

Define the entry-point function rotate_complex, which rotates the complex number in the file complex.xml by the input argument theta. The function rotate_complex invokes another local function, xml2struct, which uses the MATLAB API for XML processing to convert the XML-formatted number in the file complex.xml to a structure. Because code generation does not support the MATLAB API for XML processing, you must declare the xml2struct function as extrinsic in the body of the function rotate_complex. By declaring xml2struct as extrinsic, you instruct the code generator not to produce code for xml2struct. Instead, the code generator dispatches xml2struct to MATLAB for execution. However, because complex.xml does not change between code generation time and run time, you can instruct the code generator to treat the output of the extrinsic function xml2struct as a run-time constant using coder.const. Because the extrinsic function is constant-folded at code generation time, you do not need to explicitly convert the output of xml2struct to a known type.

Inspect the supporting file complex.xml, which contains the real and imaginary parts of a complex number.

Define the function xml2struct, which reads the passed XML file using the MATLAB API for XML processing, stores the XML parameter names and values as structure fields, and returns the structure.

function s = xml2struct(file) s = struct(); import matlab.io.xml.dom.* doc = parseFile(Parser,file); els = doc.getElementsByTagName("params"); for i = 0:els.getLength-1 it = els.item(i); ps = it.getElementsByTagName("param"); for j = 0:ps.getLength-1 param = ps.item(j); paramName = char(param.getAttribute("name")); paramValue = char(param.getAttribute("value")); paramValue = evalin("base", paramValue); s.(paramName) = paramValue; end end

Define the MATLAB entry-point function rotate_complex, which converts complex.xml to a structure using xml2struct. The function rotate_complex then rotates the complex number by an angle that is equal to the input argument theta in degrees and returns the resulting complex number. In this function, you declare the xml2struct function as extrinsic using the coder.extrinsic directive and constant-fold its output using the coder.const directive.

function y = rotate_complex(theta) %#codegen coder.extrinsic("xml2struct"); s = coder.const(xml2struct("complex.xml"));

comp = s.real + 1i * s.imaginary; magnitude = abs(comp); phase = angle(comp) + deg2rad(theta); y = magnitude * cos(phase) + 1i * sin(phase);

end

Generate a static library for rotate_complex by using the codegen (MATLAB Coder) command. Specify the input type to be a scalar double.

codegen -config:lib rotate_complex -args {0} -report

Warning: Code generation is using a coder.EmbeddedCodeConfig object. Because Embedded Coder is not installed, this might cause some Embedded Coder features to fail.

Code generation successful (with warnings): View report

Inspect the generated C++ file rotate_complex.c. Observe that the output of the xml2struct function is hardcoded in the generated code.

type codegen/lib/rotate_complex/rotate_complex.c

/*

/* Include Files */ #include "rotate_complex.h" #include <math.h>

/* Function Definitions / /

/*

Input Arguments

collapse all

MATLAB function to be called extrinsically, specified as a character vector.

Example: coder.extrinsic('patch')

Data Types: char

Global variable synchronization, specified as '-sync:on' or'-sync:off'. By default, the code generator synchronizes global variables before and after each extrinsic function call. To learn how and when to change this default behavior, see Generate Code for Global Variables (MATLAB Coder).

Example: coder.extrinsic('-sync:off','cellfun')

Limitations

Tips

Extended Capabilities

Version History

Introduced in R2011a