Generate C Code from Code Containing Global Data

Workflow Overview

To generate MEX functions from MATLAB^® code that uses global data:

Declare the variables as global in your code.
Define and initialize the global data before using it.
For more information, see Defining Global Data.
Compile your code using fiaccel.

If you use global data, you must also specify whether you want to synchronize this data between MATLAB and the generated code. If there is no interaction between MATLAB and the generated code, it is safe to disable synchronization. Otherwise, you should enable synchronization. For more information, see Synchronizing Global Data with MATLAB.

Declaring Global Variables

For code generation, you must declare global variables before using them in your MATLAB code. Consider the use_globals function that uses two global variables AR and B.

function y = use_globals()
%#codegen
% Turn off inlining to make 
% generated code easier to read
coder.inline('never');
% Declare AR and B as global variables
global AR;
global B;
AR(1) = B(1);
y = AR * 2;

Defining Global Data

You can define global data either in the MATLAB global workspace or at the command line. If you do not initialize global data at the command line, fiaccel looks for the variable in the MATLAB global workspace. If the variable does not exist, fiaccel generates an error.

Defining Global Data in the MATLAB Global Workspace

To compile the use_globals function described in Declaring Global Variables using fiaccel:

Define the global data in the MATLAB workspace. At the MATLAB prompt, enter:
```
global AR B;
AR = fi(ones(4),1,16,14);
B = fi([1 2 3],1,16,13);
```
Compile the function to generate a MEX file named use_globalsx.
```
fiaccel -o use_globalsx use_globals
```

Defining Global Data at the Command Line

To define global data at the command line, use the fiaccel -global option. For example, to compile the use_globals function described in Declaring Global Variables, specify two global inputs AR and B at the command line.

fiaccel -o use_globalsx ...
   -global {'AR',fi(ones(4)),'B',fi([1 2 3])} use_globals

Alternatively, specify the type and initial value with the -globals flag using the format -globals {'g', {type, initial_value}}.

Defining Variable-Size Global Data. To provide initial values for variable-size global data, specify the type and initial value with the -globals flag using the format -globals {'g', {type, initial_value}}. For example, to specify a global variable g1 that has an initial value [1 1] and upper bound [2 2], enter:

fiaccel foo -globals {'g1',{coder.typeof(0,[2 2],1),[1 1]}}

For a detailed explanation of coder.typeof syntax, see coder.typeof (MATLAB Coder).

Synchronizing Global Data with MATLAB

Why Synchronize Global Data?

The generated code and MATLAB each have their own copies of global data. To ensure consistency, you must synchronize their global data whenever the two interact. If you do not synchronize the data, their global variables might differ. The level of interaction determines when to synchronize global data.

When to Synchronize Global Data

By default, synchronization between global data in MATLAB and generated code occurs at MEX function entry and exit and for all extrinsic calls, which are calls to MATLAB functions on the MATLAB path that fiaccel dispatches to MATLAB for execution. This behavior ensures maximum consistency between generated code and MATLAB.

To improve performance, you can:

Select to synchronize only at MEX function entry and exit points.
Disable synchronization when the global data does not interact.
Choose whether to synchronize before and after each extrinsic call.

The following table summarizes which global data synchronization options to use. To learn how to set these options, see How to Synchronize Global Data.

Global Data Synchronization Options

If you want to...	Set the global data synchronization mode to:	Synchronize before and after extrinsic calls?
Ensure maximum consistency when all extrinsic calls modify global data.	`At MEX-function entry, exit and extrinsic calls` (default)	Yes. Default behavior.
Ensure maximum consistency when most extrinsic calls modify global data, but a few do not.	`At MEX-function entry, exit and extrinsic calls` (default)	Yes. Use the `coder.extrinsic` `-sync:off` option to turn off synchronization for the extrinsic calls that do not affect global data.
Ensure maximum consistency when most extrinsic calls do not modify global data, but a few do.	`At MEX-function entry and exit`	Yes. Use the `coder.extrinsic` `-sync:on` option to synchronize only the calls that modify global data.
Maximize performance when synchronizing global data, and none of your extrinsic calls modify global data.	`At MEX-function entry and exit`	No.
Communicate between generated code files only. No interaction between global data in MATLAB and generated code.	`Disabled`	No.

How to Synchronize Global Data

To control global data synchronization, set the global data synchronization mode and select whether to synchronize extrinsic functions. For guidelines on which options to use, see When to Synchronize Global Data.

You control the synchronization of global data with extrinsic functions using the coder.extrinsic -sync:on and -sync:off options.

Controlling the Global Data Synchronization Mode from the Command Line

Define the compiler options object in the MATLAB workspace by issuing a constructor command:
```
comp_cfg = coder.mexconfig
```
From the command line, set the GlobalDataSyncMethod property to Always, SyncAtEntryAndExits or NoSync, as applicable. For example:
```
comp_cfg.GlobalDataSyncMethod = 'SyncAtEntryAndExits';
```
Use the comp_cfg configuration object when compiling your code by specifying it using the -config compilation option. For example,
```
fiaccel -config comp_cfg myFile
```

Controlling Synchronization for Extrinsic Function Calls. You can control whether synchronization between global data in MATLAB and generated code occurs before and after you call an extrinsic function. To do so, use the coder.extrinsic -sync:on and -sync:off options.

By default, global data is:

Synchronized before and after each extrinsic call if the global data synchronization mode is At MEX-function entry, exit and extrinsic calls. If you are sure that certain extrinsic calls do not affect global data, turn off synchronization for these calls using the -sync:off option. Turning off synchronization improves performance. For example, if functions foo1 and foo2 do not affect global data, turn off synchronization for these functions:
```
coder.extrinsic('-sync:off', 'foo1', 'foo2');
```
Not synchronized if the global data synchronization mode is At MEX-function entry and exit. If the code has a few extrinsic calls that affect global data, turn on synchronization for these calls using the -sync:on option. For example, if functions foo1 and foo2 do affect global data, turn on synchronization for these functions:
```
coder.extrinsic('-sync:on', 'foo1', 'foo2');
```
Not synchronized if the global data synchronization mode is Disabled. When synchronization is disabled, you cannot control the synchronization for specific extrinsic calls. The -sync:on option has no effect.

Clear Global Data

Because MEX functions and MATLAB each have their own copies of global data, you must clear both copies to ensure that consecutive MEX runs produce the same results. The clear global command removes only the copy of the global data in the MATLAB workspace. To remove both copies of the data, use the clear global and clear mex commands together. The clear all command also removes both copies.

Limitations of Using Global Data

You cannot use global data with the coder.varsize function. Instead, use a coder.typeof object to define variable-size global data as described in Defining Variable-Size Global Data.