Define Class Properties for Code Generation

For code generation, you must be aware of certain restrictions and guidelines when you define the properties of value and handle classes. By default, MATLAB® classes are value classes. To create a handle class, you must derive the class from the handle superclass.

When you generate code for a MATLAB function that uses a class, certain additional considerations and limitations apply to the class as a whole. See Class Limitations for Code Generation.

Property Validation

To test property validation in the code generated for a MATLAB class, it is a best practice to generate a MEX function and run it over the full range of input values. MEX functions report errors that result from property validation. Standalone C and C++ code reports these errors only if you enable run-time error reporting. See Generate Standalone C/C++ Code That Detects and Reports Run-Time Errors.

Similarly, it is a best practice to test property validation in a MATLAB Function block by running a simulation over the full range of input values. C and C++ code generated by using Simulink® Coder™ does not detect or report property validation errors.

Limitations for Class Property Definitions

Because C and C++ are statically typed languages, the code generator must determine the class and size of all variables in the generated code during code generation. Therefore, you must explicitly define the class and size of each property before you use it. See Best Practices for Defining Variables for C/C++ Code Generation.

For code generation, certain restrictions apply when you define a property.

General Limitations

  • Code generation supports unbounded variable-size properties for both value and handle classes. However, you cannot use coder.varsize to declare that a property is variable size. See Resolve Error: coder.varsize Not Supported for Class Properties.

  • Certain types of properties cannot be passed by reference to an external function. See Resolve Error: Passing by Reference Not Supported for Some Properties.

  • When a class property has a default or initial value, the code generator uses the value that MATLAB computes when it loads the class. If the property definition uses a function call to compute the initial value, the code generator does not execute this function. Therefore, if the function performs other actions, such as modifying a global variable or a persistent variable, the generated code can produce different results than MATLAB.

  • Because MATLAB computes default and initial property values when it constructs the class, you cannot use coder.target to parameterize a property value inside a MATLAB class. For example, if the initial value of a property is coder.target("MATLAB"), the initial value of the property is true in both MATLAB and the generated code.

  • Code generation does not support mixing abstract and concrete definitions for properties with the same name across superclasses. That is, if a subclass inherits from multiple superclasses, and one or more of the superclasses define a property with the same name, then all or none of those properties must be defined as Abstract.

  • A class property cannot be or contain an mxArray. To use an mxArray in a class property, convert it to a known type. See Working with mxArrays.

Property Initial Values

  • The initial value of a property cannot be or contain any of these data types:

  • If you do not define an explicit initial value for a class property in the properties block, the code generator implicitly uses an empty matrix (a 0-by-0 double) as the initial value.

  • If you assign a value to a property before you use it, the code generator ignores the explicit or implicit initial value.

  • If the code generator cannot determine that you assign a value for a property before you use it, it tries to infer the type of the property.

    • If the code generator successfully infers the property type and the property type is compatible with the type of the initial value, the code generator assigns the explicit or implicit initial value to the property in the class constructor. If the inferred type is not compatible with the type of the initial value, code generation fails.

    • If the code generator cannot infer the property type, it assigns the explicit or implicit initial vale to the property in the class constructor.

Properties Defined as Constant in MATLAB

You can define a MATLAB class with a Constant property. See Define Class Properties with Constant Values. Properties that are defined as Constant in the MATLAB class definition have a fixed initial value and are read-only in MATLAB and in code generation.

Properties Specified as Constant for Code Generation

When you generate code for a function that takes a class as an input argument, you can specify that one or more properties of that class are constant by using coder.Constant. These limitations apply to properties specified by using coder.Constant:

  • Once you use a coder.Constant property in your MATLAB code, such as by passing it to another function, you cannot change the value of the property.

  • You cannot specify dependent properties by using coder.Constant.

  • A class that has a coder.Constant property cannot be returned by an extrinsic function.

  • If you define a property by using coder.Constant, the property cannot be or contain any of these data types:

    • Function handle

    • Non-ASCII characters

    • Opaque value (see coder.opaque)

  • A coder.Constant property can be or contain a handle class or System object only under specific circumstances. For example, assume class MyClass has a coder.Constant property prop_outer that is a handle object with property prop_inner.

    • If prop_inner is or contains a function handle, non-ASCII character, or opaque value, you cannot access prop_inner by any means.

    • Otherwise, you can access prop_inner, but you must access it directly by using the syntax MyClass.outer_prop.inner_prop. Code generation does not support the syntaxes MyClass.outer_prop or MyClass.outer_prop.getInnerProp().

  • When you assign a value to a nontunable property, the code generator treats the property as a constant and hard codes the value of the property in the generated code. For example, suppose a System object MySystemObject that has a nontunable property MyNonTunableProperty. Consider this code snippets:

    x = MySystemObject;
x.MyNonTunableProperty = eig(magic(5));

    Because the property MyNonTunableProperty is nontunable, the code generator calculates the value of eig(magic(5)) and replaces instances of x.nonTunableProp with this value in the generated code. The property nonTunableProp does not appear in the generated code.

Nontunable Properties

You can generate code for a System object that has one or more Nontunable properties. Limitations that apply to coder.Constant properties also apply to Nontunable properties of System objects. In addition:

For more information about generating code for System objects, see System Objects in MATLAB Code Generation.

See Also

| | |

Topics