Documentation

coder.rref

Pass argument by reference as read-only input

Syntax

coder.rref(arg)

Description

example

coder.rref(arg) passes arg by reference to an external C/C++ function that you call by using coder.ceval. Use coder.rref inside a coder.ceval call only. The code generator assumes that the variable that you pass in coder.rref is read-only. To avoid unpredictable results, the C/C++ function must not write to this variable.

Use a separate coder.rref construct for each argument that you pass by reference to the function.

Examples

Pass Scalar Variable as a Read-Only Reference

Pass a variable as a read-only reference to a C function that returns the value of the variable plus one.

Consider the C function addone:

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

The C function prototype defines the input as a pointer because it is passed by reference.

Pass a variable by reference to addone.

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

Pass Multiple Arguments as a Read-Only Reference

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

Pass Class Property as a Read-Only Reference

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

Pass Structure as a Read-Only Reference

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

Suppose that you have the C function use_struct.

double use_struct(struct MyStruct *my_struct)
{
  return  my_struct->f1 + my_struct->f2;
  
}

Suppose that a C header file, MyStruct.h, defines a structure type named MyStruct.

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

double use_struct(struct MyStruct *my_struct);

...

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

...
s = struct('f1', 1, 'f2', 2);
coder.cstructname(s, 'MyStruct', 'extern', 'HeaderFile', 'MyStruct.h');
y = 0;
y = coder.ceval('use_struct', coder.rref(s));
...

Pass Structure Field as a Read-Only Reference

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

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

  • 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.rref 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.

Introduced in R2011a

Was this topic helpful?