Main Content

coder.wref

Indicate write-only data to pass by reference

collapse all in page

Syntax

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

Description

coder.wref(arg) indicates that arg is a write-only expression or variable to pass by reference to an external C/C++ function. Use coder.wref only inside a coder.ceval call. This function enables the code generator to optimize the generated code by ignoring prior assignments to arg in your MATLAB® code, because the external function is assumed to not read from the data. Write to all the elements of arg in your external code to fully initialize the memory.

Note

The C/C++ function must fully initialize the memory referenced by coder.wref(arg). Initialize the memory by assigning values to every element of arg in your C/C++ code. If the generated code tries to read from uninitialized memory, it can cause undefined run-time behavior.

See also coder.ref and coder.rref.

example

coder.wref(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 Array by Reference as Write-Only

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 defines the input variable array as a pointer to a double.

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. This function writes to the input argument but does not read from it.

#include "MyStruct.h"

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

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

#ifndef MYSTRUCT
#define MYSTRUCT

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

void init_struct(struct MyStruct *my_struct);

#endif

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

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

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

To generate standalone library code, enter:

codegen -config:lib foo -report

Pass Structure Field as a Write-Only Reference

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

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

Version History

Introduced in R2011a

See Also

| | | |

Topics