coder.extrinsic

R2026b

Declare extrinsic function

collapse all in page

Syntax

coder.extrinsic(function)
coder.extrinsic(function1,...,functionN)
coder.extrinsic(syn,function1,...,functionN)

Description

coder.extrinsic(function) declares that function is extrinsic. The code generator does not produce code for extrinsic functions. During MEX generation and MATLAB Function (Simulink) block simulation, the code generator executes extrinsic function calls in MATLAB®. Because the code generator elides extrinsic function calls during standalone code generation, code generation fails if the generated code depends on the output of the extrinsic function. The run-time output of an extrinsic function is an mxArray. To learn more about extrinsic functions, see Using Extrinsic Functions.

example

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

coder.extrinsic(syn,function1,...,functionN) specifies whether to synchronize 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 learn how to change this default behavior, see Generate Code for Global Variables.

Examples

collapse all

If your goal is MEX generation or MATLAB Function block simulation, you can use coder.extrinsic to instruct the code generator to ignore calls to functions that are not supported for code generation.

For example, consider this function, which calls the MATLAB function str2num. Because code generation does not support str2num, declare this function as extrinsic by using coder.extrinsic.

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

MEX generation for this function succeeds. However, because the output of the extrinsic function affects the output of the calling function, standalone code generation fails. You must use an alternative MATLAB function or manually implement the str2num function in your MATLAB or C/C++ code. See Resolve Error: Function Is Not Supported for Code Generation.

The run-time output of an extrinsic function is an mxArray. The only valid operations for an mxArray are storing it in a variable, passing it to another extrinsic function, and 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 mxArray Outputs in Generated Code.

For example, consider this function, which returns arrays of different sizes based on the output of the extrinsic function str2num. Code generation does not support using an mxArray in an expression like if numel(num) > 5. You must first convert the variable num to a known type that matches the type of the mxArray output. Specify that num is a variable-size array of doubles by assigning num to an empty array of doubles and then using coder.varsize.

function num = useStringToNumberVarSize(c) %#codegen
    coder.extrinsic("str2num");
    num = [];
    coder.varsize("num");
    num = str2num(c);
    if numel(num) > 5
        num = num(1:5);
    end
end

MEX generation for this function succeeds. However, because the output of the extrinsic function affects the output of the calling function, standalone code generation fails. You must use an alternative MATLAB function or manually implement the str2num function in your MATLAB or C/C++ code. See Resolve Error: Function Is Not Supported for Code Generation.

If you call an extrinsic function that returns a constant value, you can instruct the code generator to evaluate the extrinsic function during code generation by using coder.const. The code generator uses the constant value in the generated code. You can use this coding pattern to generate standalone code that uses the output of extrinsic functions. In addition, if you generate code for computationally intensive functions that return constant values, using this coding pattern can improve the speed of code generation. See Reduce Code Generation Time.

For example, consider this function, which uses coder.extrinsic to force the code generator to execute a computationally expensive call to besselj extrinsically at code generation time. The function also uses coder.extrinsic to call readmatrix, which is not supported for code generation. During code generation, the code generator reads the file mytable.txt and calculates the Bessel function. The code generator includes zTable and jTable in the generated code as constants.

function out = forceConstFold(in) %#codegen
coder.extrinsic("besselj","readmatrix");
zTable = coder.const(readmatrix("mytable.txt"));
jTable = coder.const(besselj(3,zTable));
out = interp1(zTable,jTable,in);
end

Because the function uses coder.const to force the code generator to call both readmatrix and besselj at code generation time, both MEX generation and standalone code generation for this function succeed. In addition, because the extrinsic calls occur at code generation time, not run time, neither zTable nor jTable are an mxArray. However, because the code generator includes these variables in the generated code as constants, changes to the mytable.txt file after code generation are not reflected in the generated code.

Input Arguments

collapse all

MATLAB function to be called extrinsically, specified as a string or 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.

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

Limitations

  • You cannot use coder.ceval to call an extrinsic function.

  • You cannot call local or nested functions extrinsically.

  • You cannot call MATLAB functions that inspect the caller or that read or write to the caller workspace extrinsically, including:

  • MATLAB Function block simulation or MEX function execution can produce unpredictable results if an extrinsic function:

    • Changes the working folder

    • Changes the MATLAB path

    • Deletes or adds MATLAB files

    • Changes warning states

    • Changes MATLAB preferences

    • Changes Simulink® parameters

  • You cannot pass values into or out of an extrinsic function that are or contain:

    • Handle classes

    • Function handles

    • Variables declared by using coder.opaque

  • You can call extrinsic functions with up to 64 inputs and 64 outputs.

  • When you simulate a MATLAB Function block in rapid accelerator mode, the code generator omits extrinsic calls. If an extrinsic call affects block outputs, the rapid accelerator simulation fails.

Tips

  • When you declare a function extrinsic by using coder.extrinsic, the code generator treats all calls to that function within the current function scope as extrinsic. To specify that a single function call is extrinsic, use feval.

Extended Capabilities

expand all

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Version History

Introduced in R2011a

See Also

| |

Topics