coder.rref - Indicate read-only data to pass by reference - MATLAB (original) (raw)

Indicate read-only data to pass by reference

Syntax

Description

coder.rref([arg](#bvms4qb-arg)) indicates thatarg is a read-only expression or variable to pass by reference to an external C/C++ function. Use coder.rref only inside acoder.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 tocoder.rref(arg), the code generator can perform optimizations such as expression folding on assignments to arg that occur before and after thecoder.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 withcoder.rref(arg) is read-only. To avoid unpredictable results, the C/C++ function must not write to this variable.

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 namedMyStruct:

#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 touse_struct. To indicate that the structure type fors has the name MyStruct that is defined in the C header file MyStruct.h, usecoder.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

`arg` — Argument to pass by reference

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.

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. Thecoder.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

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation

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

HDL Code Generation

Generate VHDL, Verilog and SystemVerilog code for FPGA and ASIC designs using HDL Coder™.

The coder.rref function support only MATLAB to High-Level Synthesis (HLS) workflow in HDL Coder™.

Version History

Introduced in R2011a