Create C++ MEX Functions with C Matrix API

Note

MATLAB^® provides an API that uses modern C++ semantics and design patterns, the MATLAB Data API for C++. MathWorks recommends that you create MEX functions with this API. For more information, see Write C++ Functions Callable from MATLAB (MEX Files).

If your MEX functions must run in MATLAB R2017b or earlier, then you must use the C Matrix API functions in your C++ applications. MEX functions built with the C Matrix API support all C++ language standards. This topic discusses specific C++ language issues to consider when creating and using MEX files.

You can use the MATLAB C code examples in C++ applications. For example, see mexcpp.cpp in C++ Class Example, which contains both C and C++ statements.

Creating Your C++ Source File

The MATLAB C++ source code examples use the .cpp file extension. The extension .cpp is unambiguous and recognized by C++ compilers. Other possible extensions include .C, .cc, and .cxx.

Compiling and Linking

To build a C++ MEX file, type:

mex filename.cpp

where filename is the name of the source code file, on your MATLAB path.

You can run a C++ MEX file only on systems with the same version of MATLAB that the file was compiled on.

Memory Considerations for Class Destructors

Do not use the mxFree or mxDestroyArray functions in a C++ destructor of a class used in a MEX-function. If the MEX-function throws an error, MATLAB cleans up MEX-file variables, as described in Automatic Cleanup of Temporary Arrays in MEX Files.

If an error occurs that causes the object to go out of scope, MATLAB calls the C++ destructor. Freeing memory directly in the destructor means both MATLAB and the destructor free the same memory, which can corrupt memory.

Use mexPrintf to Print to MATLAB Command Window

Using cout or the C-language printf function does not work as expected in C++ MEX files. Use the mexPrintf function instead.

C++ Class Example

The MEX file mexcpp.cpp shows how to use C++ code with a C language MEX file. The example uses functions from the C Matrix API. It uses member functions, constructors, destructors, and the iostream include file.

The function defines a class myData with member functions display and set_data, and variables v1 and v2. It constructs an object d of class myData and displays the initialized values of v1 and v2. It then sets v1 and v2 to your input and displays the new values. Finally, the delete operator cleans up the object.

To build this example, copy the file to the MATLAB path and at the command prompt type:

mex mexcpp.cpp

The calling syntax is mexcpp(num1, num2).

C++ File Handling Example

The mexatexit.cpp example shows C++ file handling features. Compare it with the C code example mexatexit.c, which uses the mexAtExit function.

C++ Example

The C++ example uses a fileresource class to handle the file open and close functions. The MEX function calls the destructor for this class, which closes the data file. This example also prints a message on the screen when performing operations on the data file. However, in this case, the only C file operation performed is the write operation, fprintf.

To build the mexatexit.cpp MEX file, copy the file to the MATLAB path and type:

mex mexatexit.cpp

Type:

z = 'for the C++ MEX-file';
mexatexit(x)
mexatexit(z)
clear mexatexit

Writing data to file.
Writing data to file.

Display the contents of matlab.data.

type matlab.data

my input string
for the C++ MEX-file

C Example

The C code example registers the mexAtExit function to perform cleanup tasks (close the data file) when the MEX file clears. This example prints a message on the screen using mexPrintf when performing file operations fopen, fprintf, and fclose.

To build the mexatexit.c MEX file, copy the file to the MATLAB path and type:

mex mexatexit.c

Run the example.

x = 'my input string';
mexatexit(x)

Opening file matlab.data.
Writing data to file.

Clear the MEX file.

clear mexatexit

Closing file matlab.data.

Display the contents of matlab.data.

type matlab.data

my input string