Main Content

coder.ref

Indicate data to pass by reference

collapse all in page

Syntax

coder.ref(arg)
coder.ref(arg,'gpu')

Description

coder.ref(arg) indicates that arg is an expression or variable to pass by reference to an external C/C++ function. Use coder.ref inside a coder.ceval call only. The C/C++ function can read from or write to the variable passed by reference. Use a separate coder.ref construct for each argument that you pass by reference to the function.

See also coder.rref and coder.wref.

example

coder.ref(arg,'gpu') indicates that arg is a GPU argument. This option requires a valid GPU Coder™ license. If the coder.ceval calls a CUDA® GPU __device__ function, the code generator ignores the 'gpu' specification.

Examples

Pass Scalar Variable by Reference

Consider the C function addone that returns the value of an input plus one:

double addone(double* p) {
  return *p + 1;
}

The C function defines the input variable p as a pointer to a double.

Pass the input by reference to addone:

...
y = 0;
u = 42;
y = coder.ceval('addone', coder.ref(u));
...

Pass Multiple Arguments by Reference

...
u = 1;
v = 2; 
y = coder.ceval('my_fcn', coder.ref(u), coder.ref(v));
...

Pass Class Property by Reference

...
x = myClass;
x.prop = 1;
coder.ceval('foo', coder.ref(x.prop));
...

Pass a Structure by Reference

To indicate that the structure type is defined in a C header file, use coder.cstructname.

Suppose that you have the C function incr_struct. This function reads from and writes to the input argument.

#include "MyStruct.h"

void incr_struct(struct MyStruct *my_struct)
{
  my_struct->f1 =  my_struct->f1 + 1;
  my_struct->f2 =  my_struct->f2 + 1;
}

The C header file, MyStruct.h, defines a structure type named MyStruct:

#ifndef MYSTRUCT
#define MYSTRUCT

typedef struct MyStruct
{
    double f1;
    double f2;
} MyStruct;

void incr_struct(struct MyStruct *my_struct);

#endif

In your MATLAB® function, pass a structure by reference to incr_struct. To indicate that the structure type for s has the name MyStruct that is defined in the C header file MyStruct.h, use coder.cstructname.

function y = foo
%#codegen
y = 0;
coder.updateBuildInfo('addSourceFiles','incr_struct.c');

s = struct('f1',1,'f2',2);
coder.cstructname(s,'MyStruct','extern','HeaderFile','MyStruct.h');
coder.ceval('incr_struct', coder.ref(s));

To generate standalone library code, enter:

codegen -config:lib foo -report

Pass Structure Field by Reference

...
s = struct('s1', struct('a', [0 1]));
coder.ceval('foo', coder.ref(s.s1.a));
...

You can also pass an element of an array of structures:

...
c = repmat(struct('u',magic(2)),1,10);
b = repmat(struct('c',c),3,6);
a = struct('b',b);
coder.ceval('foo', coder.ref(a.b(3,4).c(2).u));
...

Input Arguments

collapse all

Argument to pass by reference to an external C/C++ function. The argument cannot be a class, a System object™, a cell array, or an index into a cell array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | struct
Complex Number Support: Yes

Limitations

  • You cannot pass these data types by reference:

    • Class or System object

    • Cell array or index into a cell array

  • If a property has a get method, a set method, or validators, or is a System object property with certain attributes, then you cannot pass the property by reference to an external function. See Passing By Reference Not Supported for Some Properties.

Tips

  • If arg is an array, then coder.ref(arg) provides the address of the first element of the array. The coder.ref(arg) function does not contain information about the size of the array. If the C function must know the number of elements of your data, pass that information as a separate argument. For example:

    coder.ceval('myFun',coder.ref(arg),int32(numel(arg));

  • When you pass a structure by reference to an external C/C++ function, use coder.cstructname to provide the name of a C structure type that is defined in a C header file.

  • In MATLAB, coder.ref results in an error. To parameterize your MATLAB code so that it can run in MATLAB and in generated code, use coder.target.

  • You can use coder.opaque to declare variables that you pass to and from an external C/C++ function.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Version History

Introduced in R2011a

See Also

| | | | |

Topics