Generate Code for Global Variables

You can generate C/C++ code and MEX functions for MATLAB® functions that use global variables. When you run a MEX function for MATLAB code that uses a global variable, the generated function and MATLAB each have their own copy of the variable. You must decide how you want to synchronize data between these copies. In addition, certain limitations apply when you use global data in MATLAB code for code generation.

Generate Code for a MATLAB Function That Uses Global Data

When you generate code for a MATLAB function that uses global variables, you must define and initialize the variables before you generate code or at the time of code generation. If you do not define global variables at the time of code generation, the code generator looks for the global variable in the MATLAB global workspace. If the global variable does not exist, code generation fails.

To generate code for a MATLAB function that uses global variables, use one of these approaches:

  • Define and initialize the global variables in the MATLAB global workspace before you generate code by using the MATLAB Coder™ app or the codegen command.

  • In the MATLAB Coder app, define and initialize the global variables on the Entry Points pane before you generate code.

  • At the command line, define and initialize global variables by using the codegen command with the -globals option.

Define and Initialize Global Variables in the Global Workspace

To define and initialize the global variables in the MATLAB global workspace before code generation, use the global function at the command line. For example:

global A B;
A = ones(4);
B = [1 2 3];

Then, generate code by using the MATLAB Coder app or the codegen command. You do not have to further specify the global variables.

Define and Initialize Global Variables in the MATLAB Coder App

To define and initialize global variables in the MATLAB Coder app, click New entry point > New global. Specify the name, type, and initial value of each global variable. See Define Global Variables in the MATLAB Coder App. Then, generate code by using the app.

Define and Initialize Global Variables in the codegen command

You can define and initialize global variables at the time of code generation when you generate code at the command line by using the codegen command. Use the -globals option to pass a cell array of global variable names and initial values to the codegen command. This cell array has the format {global1,value1,global2,value2,...}. For example:

codegen use_globals -globals {"A",ones(4),"B",[1 2 3]} -args {0}

Alternatively, you can specify global variable types by using the coder.typeof function. In this case, the cell array you pass to the -globals option has the format {global1,{type1,value1},global2,{type2,value2},...}. For example:

codegen use_globals -globals {"A",{coder.typeof(0,[4 4]),ones(4)},"B",{coder.typeof(0,[1 3]),[1 2 3]}} -args {0}

If the global variable is a cell array, you must use coder.typeof. See Specify Global Cell Arrays at the Command Line.

Define Constant Global Data

If you know that the value of a global variable does not change at run time, you can reduce overhead in the generated code by specifying that the global variable has a constant value. You cannot write to a constant global variable. You also cannot synchronize the value of a constant global variable with MATLAB.

To define a constant global variable, use on of these approaches:

  • At the command line, use the coder.Constant class in the cell array that you pass to the -globals option of the codegen command. For example:

    codegen use_globals -globals {"A",ones(4),"B",coder.Constant([1 2 3])} -args {0}

  • In the MATLAB Coder app, in the Globals section of the Entry Points pane, point to a variable and then click the Modes and Actions button . In the Modes section, select Use Constant.

Synchronizing Global Data Between Generated MEX Function and MATLAB

When you generate and run a MEX function, the generated function and MATLAB each have copies of the global data. To make these copies consistent, you must synchronize global data when the MEX function and MATLAB interact. If you do not synchronize the data, their global variables might differ. The degree to which the generated function modifies global data determines how frequently to synchronize global data.

When you define a global variable as a constant, you cannot synchronize the global data used by the generated function with MATLAB. Instead, the MEX function generates an error if the value of a constant global variable in the generated function code differs from the value of the variable in the MATLAB global workspace.

When to Synchronize Global Data

By default, synchronization of global data occurs at when MEX function execution begins, when MEX function execution ends, and after each extrinsic function call. This behavior results in maximum consistency between the generated function and MATLAB, but can decrease the performance of the generated code function.

You can control the synchronization of global data between the generated function and MATLAB by using the configuration parameter Global data synchronization mode. For individual extrinsic functions, you can control global data synchronization by using the "-sync" argument to the coder.extrinsic function.

This table summarizes how to set these parameters for different goals when you generate a MEX function.

GoalSetting of the parameter Global data synchronization modeFunction calls that use coder.extrinsicGenerated Code Behavior

Maximum consistency.

At MEX-function entry, exit and extrinsic callsUnused

  • Enforce consistency between MEX function and MATLAB when MEX function execution begins and ends.

  • Enforce consistency after extrinsic function calls.

This behavior is the default.

Optimize synchronization behavior when most extrinsic function calls modify global data, but certain extrinsic functions do not.At MEX-function entry, exit and extrinsic callsDisable synchronization and constant value checking for certain extrinsic functions by using the argument "-sync:off"

  • Enforce consistency between MEX function and MATLAB when MEX function execution begins and ends.

  • Enforce consistency after extrinsic function calls, unless the extrinsic call includes the "-sync:off" argument.

Optimize synchronization behavior when only a few extrinsic function calls modify global data.At MEX-function entry and exitEnable synchronization and constant value checking for certain extrinsic functions by using the argument "-sync:on"

  • Enforce consistency between MEX function and MATLAB when MEX function execution begins and ends.

  • Enforce consistency after extrinsic function calls only when the extrinsic call includes the "-sync:on" argument.

Optimize synchronization behavior when extrinsic calls do not modify global data.At MEX-function entry and exitUnused

  • Enforce consistency between MEX function and MATLAB when MEX function execution begins and ends.

  • Do not enforce consistency after extrinsic function calls.

Potentially optimize performance by disabling synchronization. Do not use this mode unless your code does not modify global data.DisabledNot available

  • Do not enforce consistency between MEX function and MATLAB.

  • Do not enforce consistency after extrinsic function calls. When global data synchronization is disabled, you cannot use the "-sync:on" argument to enable synchronization for extrinsic functions.

Clear Global Data

Because MEX functions and MATLAB each have their own copy of global data, you must clear both copies to ensure that consecutive MEX runs produce the same results.

To clear the copy of the global data in the MATLAB workspace, use this command:

clear global

To clear the copy of the global data in the MEX workspace, use this command:

clear MEX

Alternatively, use this command to remove both copies of the global data:

clear all

Global Data Limitations for Generated Code

  • Global structure variables cannot contain handle objects or sparse arrays.

  • You cannot apply coder.cstructname directly to a global variable. To name the structure type to use with a global variable, use coder.cstructname to create a type object that names the structure type. Then, when you run codegen, specify that the global variable has that type. See Name C Structure Type to Use with Global Structure Variable.

  • Global variables do not synchronize when there is a run-time error during SIL or PIL execution. Consider the function SILtest, which increments global variable g and then produces a run-time error.

    function SILtest
global g;
g = g + 1;
error('MyError');
end
    In MATLAB and MEX execution, SILtest increments and synchronizes global variable g in the workspace. However, in SIL execution, the global variable g does not increment in the workspace due to the run-time error. For more information on using SIL and PIL execution with global variables, see Speed Up SIL/PIL Execution by Disabling Constant Input Checking and Global Data Synchronization (Embedded Coder).

See Also

| |

Topics