coder.rref

Indicate read-only data to pass by reference

collapse all in page

Syntax

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

Description

coder.rref(arg) indicates that arg is a read-only expression or variable to pass by reference to an external C/C++ function. Use coder.rref only inside a coder.ceval call.

The coder.rref function can enable the code generator to optimize the generated code. Because the external function is assumed to not write to coder.rref(arg), the code generator can perform optimizations such as expression folding on assignments to arg that occur before and after the coder.ceval call. Expression folding is the combining of multiple operations into one statement to avoid the use of temporary variables and improve code performance.

Note

The code generator assumes that the memory that you pass with coder.rref(arg) is read-only. To avoid unpredictable results, the C/C++ function must not write to this variable.

See also coder.ref and coder.wref.

example

coder.rref(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 as a Read-Only Reference

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

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

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

Pass the input by reference to addone:

...
y = 0;
u = 42;
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. This function reads from the input argument but does not write to it.

#include "MyStruct.h"

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

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

#ifndef MYSTRUCT
#define MYSTRUCT

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

double use_struct(const struct MyStruct *my_struct);

#endif

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 the C header file MyStruct.h, use coder.cstructname.

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

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

To generate standalone library code, enter:

codegen -config:lib foo -report

Pass Structure Field as a Read-Only Reference

...
s = struct('s1', struct('a', [0 1]));
y = coder.ceval('foo', coder.rref(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.rref(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.rref(arg) provides the address of the first element of the array. The coder.rref(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.rref(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.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.

Extended Capabilities

expand all

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