coder.MexCodeConfig class

Package: coder

codegen configuration object that specifies MEX function generation parameters

Description

A coder.MexCodeConfig object contains the configuration parameters required by the codegen function to generate MEX functions. Use the -config option to pass the object to the codegen function.

Construction

cfg=coder.config creates a coder.MexCodeConfig object for MEX function generation.

cfg=coder.config('mex') creates a coder.MexCodeConfig object for MEX function generation.

Properties

CompileTimeRecursionLimit

For compile-time recursion, control the number of copies of a function that are allowed in the generated code. To disallow recursion in the MATLAB^® code, set CompileTimeRecursionLimit to 0. The default compile-time recursion limit is high enough for most recursive functions that require this type of recursion. If code generation fails because of the compile-time recursion limit, and you want compile-time recursion, try to increase the limit. Alternatively, change your MATLAB code so that the code generator uses run-time recursion. See Compile-Time Recursion Limit Reached.

Default: integer, 50

ConstantFoldingTimeout

Specify, as a positive integer, the maximum number of instructions to be executed by the constant folder.

Default: 10000

ConstantInputs

Specify whether to include constant inputs in the MEX function signature.

By default, ('CheckValues'), the MEX function signature contains the constant inputs. The run-time values of the constant inputs must match their compile-time values. This option allows you to use the same test file to run the original MATLAB algorithm and the MEX function. Selecting this option slows down execution of the MEX function.

If you specify 'IgnoreValues', the MEX function signature contains the constant inputs. The run-time values of the constant inputs are ignored and do not need to match their compile-time values. This option allows you to use the same test file to run the original MATLAB algorithm and the MEX function.

If you specify 'Remove', the MEX function signature does not contain the constant inputs and does not match the MATLAB signature. This option is provided for backwards compatibility.

Default: 'CheckValues'

CustomHeaderCode

Specify code to appear near the top of each C/C++ header file generated from your MATLAB algorithm code. Specify code as a character vector.

Default: ''

CustomInclude

Specify a space-separated list of include folders to add to the include path when compiling the generated code. Specify list of include folders as a character vector.

If your list includes Windows^® paths that contain spaces, enclose each instance in double quotes, for example:

'C:\Project "C:\Custom Files"'

Default: ''

CustomInitializer

Specify code to appear in the initialize function of the generated .c or .cpp file. Specify code as a character vector.

Default: ''

CustomLibrary

Specify a space-separated list of static library files to link with the generated code. Specify list as a character vector.

Default: ''

CustomSource

Specify a space-separated list of source files to compile and link with the generated code. Specify list of source files as a character vector.

Default: ''

CustomSourceCode

Specify code to appear near the top of the generated .c or .cpp file, outside of a function. Specify code as a character vector.

Default: ''

CustomTerminator

Specify code to appear in the terminate function of the generated .c or .cpp file. Specify code as a character vector.

Default: ''

Description

Description of object, ,specified as a character vector.

Default: ''

DynamicMemoryAllocation

Control use of dynamic memory allocation for variable-size data.

By default, dynamic memory allocation is enabled for variable-size arrays whose size (in bytes) is greater than or equal to DynamicMemoryAllocationThreshold and codegen allocates memory for this variable-size data dynamically on the heap.

Set this property to 'Off' to allocate memory statically on the stack. Set it to 'AllVariableSizeArrays' to allocate memory for all arrays dynamically on the heap . You must use dynamic memory allocation for unbounded, variable-size data.

Dependencies:

EnableVariableSizing enables this parameter.
Setting this parameter to 'Threshold' enables the DynamicMemoryAllocationThreshold parameter.

Default: 'Threshold'

DynamicMemoryAllocationThreshold

Specify the size threshold in bytes.codegen allocates memory on the heap for variable-size arrays whose size is greater than or equal to this threshold.

Dependency:

Setting DynamicMemoryAllocation to 'Threshold' enables this parameter.

Default: 65536

EchoExpressions

Specify whether or not actions that do not terminate with a semicolon appear in the MATLAB Command Window.

Default: true

EnableAutoExtrinsicCalls

Specify whether MATLAB Coder™ treats common visualization functions as extrinsic functions. When this option is enabled, MATLAB Coder detects calls to many common visualization functions, such as plot, disp, and figure. For MEX code generation, MATLAB Coder calls out to MATLAB for these functions. For standalone code generation, MATLAB Coder does not generate code for these visualization functions. This capability reduces the amount of time that you spend making your code suitable for code generation. It also removes the requirement to declare these functions extrinsic using the coder.extrinsic function.

Default: true

EnableDebugging

Specify whether to use the debug option for the C compiler. If you enable debug mode, the C compiler does not optimize the code. The compilation is faster, but the execution is slower.

Default: false

EnableJIT

Specify whether to use just-in-time (JIT) compilation for generation of MEX functions. To speed up generation of MEX functions, set EnableJIT to true.

JIT compilation is incompatible with certain code generation features and options, such as custom code or use of the OpenMP library. If you specify JIT compilation and MATLAB Coder is unable to use it, it generates a C/C++ MEX function with a warning. If EnableJIT and EnableOpenMP are true, and your code uses parfor, MATLAB Coder uses JIT compilation and treats the parfor-loops as for-loops.

Default: false

EnableMemcpy

Enable the memcpy optimization. To optimize code that copies consecutive array elements, the memcpy optimization replaces the code with a memcpy call. A memcpy call can be more efficient than code, such as a for-loop or multiple, consecutive element assignments. The code generator invokes the memcpy optimization when the following conditions are true:

EnableMemcpy is true.
The number of bytes to copy is greater than or equal to MemcpyThreshold. The number of bytes to copy is the number of array elements multiplied by the number of bytes required for the C/C++ data type.

See memcpy Optimization.

Default: true

EnableOpenMP

If possible, enable OpenMP. Using the OpenMP library, the MEX function that MATLAB Coder generates for parfor-loops can run on multiple threads. With OpenMP disabled, MATLAB Coder treats parfor-loops as for-loops and generates a MEX function that runs on a single thread.

Use of the OpenMP library is not compatible with just-in-time (JIT) compilation. If EnableJIT and EnableOpenMP are true and your code uses parfor, MATLAB Coder uses JIT compilation and treats the parfor-loops as for-loops.

Default: true

EnableRuntimeRecursion

Allow recursive functions in generated code. If your MATLAB code requires run-time recursion and this parameter is false, code generation fails.

Some coding standards, such as MISRA^®, do not allow recursion. To increase the likelihood of generating code that is compliant with MISRA C^®, set EnableRuntimeRecursion to false.

Default: true

EnableVariableSizing

Enable support for variable-size arrays.

Dependency:

Enables Dynamic memory allocation.

Default: true

ExtrinsicCalls

Allow calls to extrinsic functions.

An extrinsic function is a function on the MATLAB path that MATLAB Coder dispatches to MATLAB software for execution. MATLAB Coder does not compile or generate code for extrinsic functions.

When enabled (true), generates code for the call to a MATLAB function, but does not generate the function's internal code.

When disabled (false), ignores the extrinsic function. Does not generate code for the call to the MATLAB function — as long as the extrinsic function does not affect the output of the MATLAB function. Otherwise, issues a compilation error.

ExtrinsicCalls affects how MEX functions built by MATLAB Coder generate random numbers when using the MATLAB rand, randi, and randn functions. If extrinsic calls are enabled, the generated MEX function uses the MATLAB global random number stream to generate random numbers. If extrinsic calls are not enabled, the MEX function built with MATLAB Coder uses a self-contained random number generator.

If you disable extrinsic calls, the generated MEX function cannot display run-time messages from error or assert statements in your MATLAB code. The MEX function reports that it cannot display the error message. To see the error message, enable extrinsic function calls and generate the MEX function again.

Default: true

FilePartitionMethod

Specify whether to generate one C/C++ file for each MATLAB language file ('MapMFileToCFile') or generate all C/C++ functions into a single file ('SingleFile').

Default: 'MapMFileToCFile'

GenCodeOnly

Control whether to compile the generated MEX function C/C++ code to produce a MEX function.

Default: false

GenerateComments

Place comments in the generated files.

Default: true

GenerateReport

Document generated code in a report.

Default: false

GlobalDataSyncMethod

Controls synchronization of MEX function global data with the MATLAB global workspace. For constant global data, controls verification of consistency between the MEX function constant global data and the MATLAB global workspace.

Value	Description for Global Data	Description for Constant Global Data
`'SyncAlways'` (default)	Synchronizes global data at MEX function entry and exit and for extrinsic calls for maximum consistency between MATLAB and the generated MEX function. To maximize performance, if the extrinsic calls do not change global data, use this option in conjunction with the `coder.extrinsic` `-sync:off` option to turn off synchronization for these calls.	Verifies consistency of constant global data at MEX function entry and after extrinsic calls. The MEX function ends with an error if the global data values in the MATLAB global workspace are inconsistent with the compile-time constant global values in the MEX function. Use the `coder.extrinsic` `-sync:off` option to turn off consistency checks after specific extrinsic calls.
`'SyncAtEntryAndExits'`	Synchronizes global data at MEX function entry and exit only. To maximize performance, if only a few extrinsic calls change global data, use this option in conjunction with the `coder.extrinsic` `-sync:on` option to turn on synchronization for these calls.	Verifies constant global data at MEX function entry only. The MEX function ends with an error if the global data values in the MATLAB global workspace are inconsistent with the compile-time constant global values in the MEX function. Use the `coder.extrinsic` `-sync:on` option to turn on consistency checks after specific extrinsic calls.
`'NoSync'`	Disables synchronization. Before disabling synchronization, verify that your MEX function does not interact with MATLAB globals. Otherwise, inconsistencies between MATLAB and the MEX function can occur.	Disables consistency checks.

Default: 'SyncAlways'

InitFltsAndDblsToZero

Enable the memset optimization for assignment of float or double 0 to consecutive array elements. To optimize code that assigns a constant value to consecutive array elements, the memset optimization replaces the code with a memset call. A memset call can be more efficient than code, such as a for-loop or multiple, consecutive element assignments. To assign float or double 0 to consecutive array elements, the code generator invokes the memset optimization when the following conditions are true:

InitFltsAndDblsToZero is true.
The number of bytes to assign is greater than or equal to MemcpyThreshold. The number of bytes to assign is the number of array elements multiplied by the number of bytes required for the C/C++ data type.

See memset Optimization.

Default: true

InlineStackLimit

Specify the stack size limit on inlined functions. This specification determines the amount of stack space allocated for local variables of the inlined function.

Specifying a limit on the stack space constrains the amount of inlining allowed. For out-of-line functions, stack space for variables local to the function is released when the function returns. However, for inlined functions, stack space remains occupied by the local variables even when the function returns.

This feature is especially important for embedded processors, where stack size can be limited.

Default: 4000

InlineThreshold

Specify function size for inline threshold. Unless there are conflicts with other inlining conditions, MATLAB Coder inlines functions that are smaller than this size.

The function size is measured in terms of an abstract number of instructions, not actual MATLAB instructions or instructions in the target processor. You must experiment with this parameter to obtain the inlining behavior that you want. For instance, if the default setting for this parameter is leading to large functions being inlined and in turn generating large C code, you can tune the parameter in steps until you are satisfied with the size of generated code.

Default: 10

InlineThresholdMax

Specify the maximum size of functions after inlining. If the size of the calling function after inlining exceeds InlineThresholdMax, MATLAB Coder does not inline the called function.

Default: 200

IntegrityChecks

Detect violations of memory integrity in code generated for MATLAB functions and stops execution with a diagnostic message.

Setting IntegrityChecks to false also disables the run-time stack.

Default: true

LaunchReport

Specify whether to automatically display HTML reports after code generation is complete or an error occurs.

Default: true

MATLABSourceComments

Include MATLAB source code as comments in the generated code.

Dependencies:

GenerateComments enables this parameter.

Default: false

MemcpyThreshold

Specify the minimum number of bytes for the code generator to invoke the memcpy optimization or the memset optimization. To optimize generated code that copies consecutive array elements, the code generator tries to replace the code with a memcpy call. To optimize generated code that assigns a literal constant to consecutive array elements, the code generator tries to replace the code with a memset call. A memcpy or memset call can be more efficient than code, such as a for-loop or multiple, consecutive element assignments.

The number of bytes is the number of array elements to copy or assign multiplied by the number of bytes required for the C/C++ data type.

See memcpy Optimization and memset Optimization.

Default: 64

Name

Name of code generation configuration object, specified as a character vector.

Default: 'MexCodeConfig'

PostCodeGenCommand

Specify command to customize build processing after MEX function generation using codegen. Specify command as a character vector.

Default: ''

PreserveVariableNames

Specify which variable names the code generator must preserve in the generated code.

Value Description

'None'

The code generator does not have to preserve any variable names. It can reuse any variables that meet the requirements for variable reuse.

If your code uses large structures or arrays, setting PreserveVariableNames to 'None' can reduce memory usage or improve execution speed.

'UserNames'

The code generator preserves names that correspond to variables that you define in the MATLAB code. It does not replace your variable name with another name and does not use your name for another variable. To improve readability, set PreserveVariableNames to 'UserNames'. Then, you can more easily trace the variables in the generated code back to the variables in your MATLAB code.

Setting PreserveVariableNames to 'UserNames' does not prevent an optimization from removing your variables from the generated code or prevent the C/C++ compiler from reusing the variables in the generated binary code.

'All'

Preserve all variable names. This parameter value disables variable reuse. Use it only for testing or debugging, not for production code.

Default: 'None'

ReservedNameArray

Enter a list of names that MATLAB Coder is not to use for naming functions or variables. Specify list as a character vector.

Default: ''

ResponsivenessChecks

Enable responsiveness checks in code generated for MATLAB functions.

These checks enable periodic checks for Ctrl+C breaks in the generated code. Enabling responsiveness checks also enables graphics refreshing.

Caution These checks are enabled by default for safety. Without these checks, the only way to end a long-running execution might be to terminate MATLAB.

Default: true

SaturateOnIntegerOverflow

Overflows saturate to either the minimum or maximum value that the data type can represent. Otherwise, the overflow behavior depends on your target C compiler. Most C compilers wrap on overflow.

This parameter applies only to MATLAB built-in integer types. It does not apply to doubles, singles, or fixed-point data types.

Default: true

StackUsageMax

Specify the maximum stack usage per application in bytes. Set a limit that is lower than the available stack size. Otherwise, a runtime stack overflow might occur. Overflows are detected and reported by the C compiler, not by codegen.

Default: 200000

TargetLang

Specify the target language. Set to 'C' to generate C code. Set to C++ to generate C++ code. If you specify C++, MATLAB Coder wraps the C code into .cpp files so that you can use a C++ compiler and interface with external C++ applications. It does not generate C++ classes.

Default: 'C'

Copy Semantics

Handle. To learn how handle classes affect copy operations, see Copying Objects in the MATLAB documentation.

Examples

Generate a MEX function from a MATLAB function that is suitable for code generation and enable a code generation report.

Write a MATLAB function, coderand, that generates a random scalar value from the standard uniform distribution on the open interval (0,1).
```
function r = coderand() %#codegen
% The directive %#codegen declares that the function
% is intended for code generation
r = rand();
```
Create a code generation configuration object to generate a MEX function.
```
cfg = coder.config('mex')
```
Enable the code generation report.
```
cfg.GenerateReport = true;
```
Generate a MEX function in the current folder specifying the configuration object using the -config option.
```
% Generate a MEX function and code generation report
codegen -config cfg coderand
```

Alternatives

Use the coder function to create a MATLAB Coder project. The project provides a user interface that facilitates adding MATLAB files, defining input parameters, and specifying build parameters.

Documentation

coder.MexCodeConfig class

Description

Construction

Properties

Copy Semantics

Examples

Alternatives

See Also

MATLAB Coder Documentation

Other Documentation

Support