Main Content

Pass Structure Arguments by Reference or by Value in Generated Code

Open Live Script

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

Passing by reference uses a pointer to access the structure arguments. If the function writes to an element of the input structure, it overwrites the input value. Passing by value makes a copy of the input or output structure argument. To reduce memory usage and execution time, use pass by reference.

If a structure argument is both an input and output, the generated entry-point function passes the argument by reference. Generated MEX functions pass structure arguments by reference. For MEX function output, you cannot specify that you want to pass structure arguments by value.

Specify Pass by Reference or by Value Using the MATLAB® Coder App

To open the Generate dialog box, on the Generate Code page, click the Generate arrow.

Set the Build type to one of the following:

  • Source Code

  • Static Library

  • Dynamic Library

  • Executable

Click More Settings.

On the All Settings tab, set the Pass structures by reference to entry-point functions option to:

  • Yes, for pass by reference (default)

  • No, for pass by value

Specify Pass by Reference or by Value Using the Command-Line Interface

Create a code configuration object for a static library, a dynamic library, or an executable program. For example, create a code configuration object for a static library.

cfg = coder.config('lib');

Set the PassStructByReference property to:

  • true, for pass by reference (default)

  • false, for pass by value

For example:

cfg.PassStructByReference = true;

Pass Input Structure Argument by Reference

Write the MATLAB function my_struct_in that has an input structure argument.

type my_struct_in.m
function y = my_struct_in(s)
%#codegen

y = s.f;

Define a structure variable mystruct in the MATLAB® workspace.

mystruct = struct('f', 1:4);

Create a code generation configuration object for a C static library.

cfg = coder.config('lib');

Specify that you want to pass structure arguments by reference.

cfg.PassStructByReference = true;

Generate code. Specify that the input argument has the type of the variable mystruct.

codegen -config cfg -args {mystruct} my_struct_in
Code generation successful.

View the generated C code.

type codegen/lib/my_struct_in/my_struct_in.c
/*
 * File: my_struct_in.c
 *
 * MATLAB Coder version            : 24.2
 * C/C++ source code generated on  : 05-Sep-2024 13:50:22
 */

/* Include Files */
#include "my_struct_in.h"
#include "my_struct_in_types.h"

/* Function Definitions */
/*
 * Arguments    : const struct0_T *s
 *                double y[4]
 * Return Type  : void
 */
void my_struct_in(const struct0_T *s, double y[4])
{
  y[0] = s->f[0];
  y[1] = s->f[1];
  y[2] = s->f[2];
  y[3] = s->f[3];
}

/*
 * File trailer for my_struct_in.c
 *
 * [EOF]
 */

The generated function signature for my_struct_in is

void my_struct_in(const struct0_T *s, double y[4])

my_struct_in passes the input structure s by reference.

Pass Input Structure Argument by Value

Specify that you want to pass structure arguments by value.

cfg.PassStructByReference = false;

Generate code. Specify that the input argument has the type of the variable mystruct.

codegen -config cfg -args {mystruct} my_struct_in
Code generation successful.

View the generated C code.

type codegen/lib/my_struct_in/my_struct_in.c
/*
 * File: my_struct_in.c
 *
 * MATLAB Coder version            : 24.2
 * C/C++ source code generated on  : 05-Sep-2024 13:50:24
 */

/* Include Files */
#include "my_struct_in.h"
#include "my_struct_in_types.h"

/* Function Definitions */
/*
 * Arguments    : const struct0_T s
 *                double y[4]
 * Return Type  : void
 */
void my_struct_in(const struct0_T s, double y[4])
{
  y[0] = s.f[0];
  y[1] = s.f[1];
  y[2] = s.f[2];
  y[3] = s.f[3];
}

/*
 * File trailer for my_struct_in.c
 *
 * [EOF]
 */

The generated function signature for my_struct_in is

void my_struct_in(const struct0_T s, double y[4]

my_struct_in passes the input structure s by value.

Pass Output Structure Argument by Reference

Write the MATLAB function my_struct_out that has an output structure argument.

type my_struct_out.m
function s = my_struct_out(x)
%#codegen

s.f = x;

Define a variable a in the MATLAB® workspace.

a = 1:4;

Create a code generation configuration object for a C static library.

cfg = coder.config('lib');

Specify that you want to pass structure arguments by reference.

cfg.PassStructByReference = true;

Generate code. Specify that the input argument has the type of the variable a.

codegen -config cfg -args {a} my_struct_out
Code generation successful.

View the generated C code.

type codegen/lib/my_struct_out/my_struct_out.c
/*
 * File: my_struct_out.c
 *
 * MATLAB Coder version            : 24.2
 * C/C++ source code generated on  : 05-Sep-2024 13:50:30
 */

/* Include Files */
#include "my_struct_out.h"
#include "my_struct_out_types.h"

/* Function Definitions */
/*
 * Arguments    : const double x[4]
 *                struct0_T *s
 * Return Type  : void
 */
void my_struct_out(const double x[4], struct0_T *s)
{
  s->f[0] = x[0];
  s->f[1] = x[1];
  s->f[2] = x[2];
  s->f[3] = x[3];
}

/*
 * File trailer for my_struct_out.c
 *
 * [EOF]
 */

The generated function signature for my_struct_out is

void my_struct_out(const double x[4], struct0_T *s)

my_struct_out passes the output structure s by reference.

Pass Output Structure Argument by Value

Specify that you want to pass structure arguments by value.

cfg.PassStructByReference = false;

Generate code. Specify that the input argument has the type of the variable a.

codegen -config cfg -args {a} my_struct_out
Code generation successful.

View the generated C code.

type codegen/lib/my_struct_out/my_struct_out.c
/*
 * File: my_struct_out.c
 *
 * MATLAB Coder version            : 24.2
 * C/C++ source code generated on  : 05-Sep-2024 13:50:32
 */

/* Include Files */
#include "my_struct_out.h"
#include "my_struct_out_types.h"

/* Function Definitions */
/*
 * Arguments    : const double x[4]
 * Return Type  : struct0_T
 */
struct0_T my_struct_out(const double x[4])
{
  struct0_T s;
  s.f[0] = x[0];
  s.f[1] = x[1];
  s.f[2] = x[2];
  s.f[3] = x[3];
  return s;
}

/*
 * File trailer for my_struct_out.c
 *
 * [EOF]
 */

The generated function signature for my_struct_out is

struct0_T my_struct_out(const double x[4])

my_struct_out returns an output structure.

Pass Input and Output Structure Argument by Reference

When an argument is both an input and an output, the generated C function passes the argument by reference even when PassStructByReference is false.

Write the MATLAB function my_struct_inout that has a structure argument that is both an input argument and an output argument.

type my_struct_inout.m
function [y,s] = my_struct_inout(x,s)
%#codegen

y = x + sum(s.f);

Define the variable a and structure variable mystruct in the MATLAB® workspace.

a = 1:4;
mystruct = struct('f',a);

Create a code generation configuration object for a C static library.

cfg = coder.config('lib');

Specify that you want to pass structure arguments by value.

cfg.PassStructByReference = false;

Generate code. Specify that the first input has the type of a and the second input has the type of mystruct.

codegen -config cfg -args {a, mystruct} my_struct_inout
Code generation successful.

View the generated C code.

type codegen/lib/my_struct_inout/my_struct_inout.c
/*
 * File: my_struct_inout.c
 *
 * MATLAB Coder version            : 24.2
 * C/C++ source code generated on  : 05-Sep-2024 13:50:36
 */

/* Include Files */
#include "my_struct_inout.h"
#include "my_struct_inout_types.h"
#include <emmintrin.h>

/* Function Definitions */
/*
 * Arguments    : const double x[4]
 *                const struct0_T *s
 *                double y[4]
 * Return Type  : void
 */
void my_struct_inout(const double x[4], const struct0_T *s, double y[4])
{
  __m128d r;
  r = _mm_set1_pd(((s->f[0] + s->f[1]) + s->f[2]) + s->f[3]);
  _mm_storeu_pd(&y[0], _mm_add_pd(_mm_loadu_pd(&x[0]), r));
  _mm_storeu_pd(&y[2], _mm_add_pd(_mm_loadu_pd(&x[2]), r));
}

/*
 * File trailer for my_struct_inout.c
 *
 * [EOF]
 */

The generated function signature for my_struct_inout is

void my_struct_inout(const double x[4], const struct0_T *s, double y[4])

my_struct_inout passes the structure s by reference even though PassStructByReference is false.

Related Topics