Pass Structure Arguments by Reference or by Value in Standalone Code

Open Live Script

This example shows how to control whether structure arguments to and from generated entry-point functions are passed by reference or by value.

When a function passes an input argument by reference, it uses a pointer to access the argument. If the function changes the value of the input argument, it modifies the variable directly. When a function passes a variable by value, it makes a copy of the input or output structure argument. To reduce memory usage and execution time, use pass by reference.

By default, the code generator passes structure arguments by reference in standalone code. When you generate standalone code, you can instruct the code generator to pass structure arguments by value by using one of these approaches:

In a standalone code configuration object, set the PassStructByReference property to false.
In the Code Generation Settings dialog box, clear the Pass structures by reference to entry-point functions check box.

When a structure argument is both an input and output, the code generator ignores this setting and passes the structure by reference.

Code generation does not support passing MEX function arguments by value. The code generator always passes arguments by reference to and from MEX functions.

Pass Input Structure Argument By Reference

By default, the code generator passes input structure arguments by reference. Examine the MATLAB® function myStruct_input, which has an input argument that is a structure.

type myStruct_input.m

function out = myStruct_input(in_s) %#codegen
out = in_s.field1;
end

To generate code for a C static library, first create a code configuration object and make sure that the PassStructByReference property is set to true.

cfg = coder.config("lib");
cfg.PassStructByReference

ans = logical
   1

Define an example value for the input argument in the MATLAB workspace. Then, generate code by using the codegen command. Use the -config option to specify the code configuration object, and use the -args option to specify that the input argument has the same type as the variable mystruct. Use the -d option to store the generated code in the directory inputByRef.

mystruct = struct("field1",1:4);
codegen -config cfg -d inputByRef myStruct_input -args {mystruct}

Code generation successful.

Examine the declaration of the C function myStruct_input in the file myStruct_input.h. The C function passes the input argument in_s by reference.

file = fullfile("inputByRef","myStruct_input.h");
coder.example.extractLines(file,"/* Function Declarations */","#",0,0)

extern void myStruct_input(const struct0_T *in_s, double out[4]);

Pass Input Structure Argument by Value

To pass the input argument in_s to the generated function by value, set the PassStructByReference property of the code configuration object to false.

cfg.PassStructByReference = false;

Generate code by using the codegen command. Use the -config option to specify the code configuration object, and use the -args option to specify that the input argument has the same type as the variable mystruct. Use the -d option to store the generated code in the directory inputByVal.

codegen -config cfg -d inputByVal myStruct_input -args {mystruct}

Code generation successful.

Examine the declaration of the C function myStruct_input in the file myStruct_input.h. The C function passes the input argument in_s by value.

file = fullfile("inputByVal","myStruct_input.h");
coder.example.extractLines(file,"/* Function Declarations */","#",0,0)

extern void myStruct_input(const struct0_T in_s, double out[4]);

Pass Output Structure Argument by Reference

By default, the code generator passes output structure arguments by reference. Examine the MATLAB function myStruct_output, which has an output argument that is a structure.

type myStruct_output.m

function out_s = myStruct_output(x) %#codegen
out_s.field1 = x;
end

To generate code for a C static library, create a new code configuration object and make sure that the PassStructByReference property is set to true.

cfg = coder.config("lib");
cfg.PassStructByReference

ans = logical
   1

Define an example value for the input argument in the MATLAB workspace. Then, generate code by using the codegen command. Use the -config option to specify the code configuration object, and use the -args option to specify that the input argument has the same type as the variable x. Use the -d option to store the generated code in the directory outputByRef.

x = 1:4;
codegen -config cfg -d outputByRef myStruct_output -args {x}

Code generation successful.

Examine the declaration of the C function myStruct_input in the file myStruct_input.h. The C function passes the output argument out_s by reference.

file = fullfile("outputByRef","myStruct_output.h");
coder.example.extractLines(file,"/* Function Declarations */","#",0,0)

extern void myStruct_output(const double x[4], struct0_T *out_s);

Pass Output Structure Argument by Value

To pass the output argument out_s to the generated function by value, set the PassStructByReference of the code configuration object to false.

cfg.PassStructByReference = false;

Generate code by using the codegen command. Use the -config option to specify the code configuration object, and use the -args option to specify that the input argument has the same type as the variable x. Use the -d option to store the generated code in the directory outputByVal.

codegen -config cfg -d outputByVal myStruct_output -args {x}

Code generation successful.

Examine the declaration of the C function myStruct_output in the file myStruct_output.h. The C function returns the output argument out_s by value.

file = fullfile("outputByVal","myStruct_output.h");
coder.example.extractLines(file,"/* Function Declarations */","#",0,0)

extern struct0_T myStruct_output(const double x[4]);

Pass Input and Output Structure Argument by Reference

When an argument is both an input and an output, the generated code always passes the argument by reference. Examine the MATLAB® function myStruct_inout, which uses the same structure variable as an input and output argument.

type myStruct_inout.m

function inout_s = myStruct_inout(inout_s,x) %#codegen
inout_s.field1 = x;
end

Define the structure variable mystruct in the MATLAB workspace. Use coder.typeof to specify that the field1 field of mystruct is a variable-length row vector of doubles with an upper bound of 10.

mystruct = struct("field1",coder.typeof(0,[1 10],[false true]));
mystruct.field1

ans = 
coder.PrimitiveType
  1×:10 double

    Edit Type Object

To generate code for a C static library, create a new code configuration object. For the purposes of this example, set the PassStructByReference property to false.

cfg = coder.config("lib");
cfg.PassStructByReference = false;

Generate code by using the codegen command. Use the -config option to specify the code configuration object, and use the -args option with to specify that the input argument is a variable-length row vector of doubles with an upper bound of 10. Use the -d option to store the generated code in the directory inoutByRef.

codegen -config cfg  -d inoutByRef myStruct_inout -args {mystruct,coder.typeof(0,[1 10],[false true])}

Code generation successful.

Examine the declaration of the C function myStruct_inout in the file myStruct_inout.h. The C function passes the output argument inout_s by reference, even though the PassStructByReference property is false.

file = fullfile("inoutByRef","myStruct_inout.h");
coder.example.extractLines(file,"/* Function Declarations */","#",0,0)

extern void myStruct_inout(struct0_T *inout_s, const double x_data[],
                           const int x_size[2]);