Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

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 incr_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 setter or getter method, you cannot pass the property by reference because you cannot access the address of the property. Only the getter or setter method can directly read from or write to this property.

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?