Documentation

coder.wref

Pass argument as write-only reference

Syntax

coder.wref(arg)

Description

example

coder.wref(arg) passes arg by reference to an external C/C++ function that you call by using coder.ceval. Use coder.wref inside a coder.ceval call only. The code generator assumes that the variable that you pass in coder.wref is write-only. The C/C++ function must write to this variable. If the variable is a vector or an array, the C/C++ function must write to every element of the variable. If the MATLAB® code initializes arg before the coder.ceval call, the code generator might remove the initial values. To avoid unpredictable results, the C/C++ function must not read the variable before writing to it.

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

Examples

Pass Array by Reference as Write-Only

Pass a variable by reference to a C function that initializes an array.

Suppose that you have a C function init_array.

void init_array(double* array, int numel) {
  for(int i = 0; i < numel; i++) {
    array[i] = 42;
  }
}

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

Call the C function init_array to initialize all elements of y to 42.

...
Y = zeros(5, 10);
coder.ceval('init_array', coder.wref(Y), int32(numel(Y)));
...

Pass Multiple Arguments as a Write-Only Reference

...
U = zeros(5, 10);
V = zeros(5, 10); 
coder.ceval('my_fcn', coder.wref(U), int32(numel(U)), coder.wref(V), int32(numel(V)));
...

Pass Class Property as a Write-Only Reference

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

Pass Structure as a Write-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 init_struct.

double init_struct(struct MyStruct *my_struct)
{
   my_struct->f1 = 1; 
   my_struct->f2 = 2;
}

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

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

double init_struct(struct MyStruct *my_struct);

...

In your MATLAB function, pass a structure as a write-only reference to init_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');
coder.ceval('init_struct', coder.wref(s));
...

Pass Structure Field by Reference

...
s = struct('s1', struct('a', [0 1]));
coder.ceval('foo', coder.wef(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.wref 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?