C and C++ Libraries and MEX

Since R2026b the recommended programmatic workflow is two objects. A clibgen.api.InterfaceConfiguration says what to include and where to find it (header files, include path, name standardization, build options). A clibgen.api.InterfaceDefinition is created from it, parses the headers, and lets you inspect (findClass, findFunction, findMethod), complete (define) and build the interface. Both objects can be saved and loaded again, and the script is meant to be kept in version control and re-run whenever the library changes, including from CI. The alternative is clibPublishInterfaceWorkflow (since R2023a), which opens a live script that walks through generate, define, build and test with a Live Editor task. Before R2026b the two options were that live script or a definition file made with clibgen.generateLibraryDefinition (next section).

For heatflow, a small header-only library with two functions that a program outside MATLAB might also use. The pointer function is the typical "incomplete" case.

The publishing script follows the structure of the documentation’s programmatic example (matrixOperations): configure, create the definition, find the incomplete function and define the size of the pointer argument by naming the length argument, build, add the interface folder to the path. Not run here (it needs a supported C++ compiler and MATLAB R2026b).

Calling the library is ordinary MATLAB. The interface name becomes part of the full name: clib.heatflowstats. Not run here.

The values in the comments are what the formula gives. They were computed by compiling the same arithmetic as a plain C function in a small C program and running it here (it printed 25 305); the MATLAB calls themselves were not run.

During development, run the interface library out of process so that rebuilding does not require restarting MATLAB, and so that a crash in the library does not take MATLAB down with it. Call clibConfiguration before the first use of the library. Not run here.

In-process execution is the default and the one to use when performance matters. Out-of-process execution also helps when the library needs a different version of a third-party library than the one MATLAB itself ships, and Ctrl+C can interrupt a call (since R2025a). When the library functions use MATLAB arrays, the MATLAB root folder has to be on the system path (see "Set Run-Time Library Path for C/C++ Interface" in the documentation).

Source: MATLAB documentation: Publish MATLAB Interface to C++ Library Programmatically

Before R2026b the programmatic route generated a definition file. clibgen.generateLibraryDefinition(InterfaceGenerationFiles,Name=Value) writes define<libname>.m (file name define<libname>.m since R2022b; earlier releases wrote a Live Script .mlx), where <libname> is the name of the first file unless you pass InterfaceName (called PackageName before R2024a). Constructs it can fully define are written as code; incomplete ones are written as commented-out, partly filled code that you uncomment and complete by hand. Then build on the definition file creates the interface.

Two details of this form: the argument can be a header file (.h, .hpp, .hxx) or source file (.c, .cpp, .cxx); a library that is completely defined in the headers needs no Libraries argument; IncludePath names the folders of headers included by the main header; and with CLinkage=true a .h file is treated as C++-compatible C code. R2024a added RootPaths so that definition files can use paths relative to an absolute base and be shared (for example on GitHub) between publishers with the same library layout. clibgen.buildInterface creates an interface without a definition file and is also "not recommended" in R2026b. There are no plans to remove either function, and existing definition files still build; for new work, use the objects.

Source: MATLAB documentation: clibgen.generateLibraryDefinition

The conversion between MATLAB and C or C++ types is automatic and goes from the closest match to the least close one: a MATLAB double array is passed to a double buffer, std::vector<double> or fixed-size array; a MATLAB int32 array to an int32_t one, and so on. The documentation has a full table ("MATLAB Type to C++ Type Mapping"), and separate topics for structures, const and non-const parameters, passing by reference, function pointers, templates, std::vector, opaque objects, and the clib.array objects that wrap native C++ arrays. Not every C++ feature is supported ("Limitations to C/C++ Support" lists them, with workaround examples), and the lifetime rules for C++ objects created from MATLAB have their own topic. A finished interface is distributed as a package file (.mltbx; since R2026b the name for what used to be called a toolbox file), with the run-time libraries copied next to it. Packages are the subject of the page on packages and the MATLAB Package Manager.

Source: MATLAB documentation: Call C/C++ from MATLAB

A C++ MEX function is a class named MexFunction that derives from matlab::mex::Function and overrides the function call operator, operator(), so that its instances are function objects. MATLAB passes the arguments as two matlab::mex::ArgumentList containers: inputs, with one matlab::data::Array per input argument, and outputs, in which the function stores the results. inputs.size() is the number of arguments in the call and outputs.size() the number of requested outputs; ArgumentList supports [], size, empty and iterators, so range-based for loops work. The three namespaces are matlab::mex (the MEX interface), matlab::data (the Data API: arrays) and matlab::engine (the C++ Engine API, to call MATLAB from the function).

Things worth knowing about the lifecycle: MATLAB creates one instance of the class the first time the MEX function is called, and it lives until you run clear mex (or clear the function), so members can hold state, and a constructor and destructor can open and close external resources. The base class provides getEngine() (a std::shared_ptr<matlab::engine::MATLABEngine>), mexLock and mexUnlock (prevent or allow clearing of the MEX file from memory) and getFunctionName. Engine methods such as feval, eval, getVariable, setVariable, getProperty and setProperty must be called on the same thread as the Function object.

The two APIs cannot be mixed in one MEX file. Use matlab::data types or mxArray functions, never both. The -R2017b and -R2018a options of mex are for the C Matrix API and are not used for C++ code written with the Data API.

Everything is a matlab::data::Array; more specific classes give more functionality: TypedArray<T> (numeric, logical, char16_t, complex std::complex<T>, MATLABString for string arrays, and others; it supports iterators and indexing), CharArray (converters for ASCII and UTF-16), CellArray, StructArray, and plain Array for MATLAB objects. You create arrays with a matlab::data::ArrayFactory:

Source: MATLAB documentation: matlab::data::ArrayFactory

The last line shows the trap from the earlier section: an initializer list is read in the order of the memory layout, column by column, so [1 2; 3 4] is written 1, 3, 2, 4. (The documentation notes the row-major against column-major difference for exactly this reason.) The Data API can also describe a different memory layout with getMemoryLayout (COLUMN_MAJOR or ROW_MAJOR), which makes it easier to adapt row-major C++ data, and createArrayFromBuffer takes the layout as its last argument.

Shared copies and copy-on-write. The Data API follows the same copy-on-write rules as MATLAB code. An input array is a shared copy of the MATLAB variable, and a copy of the data is made only when the function modifies the array. Two idioms keep the copies away:

The documentation’s example of the second case is called as arry = removeNegativeNumbers(arry), reassigning the result to the variable that was passed, so that no second copy of the large array stays alive.

No raw pointers. The Data API deliberately hides the data pointer. For TypedArray<T> you get iterators and a zero-based, linear operator[]; release() hands over the buffer as a std::unique_ptr and (since R2024b) first unshares the array, copying the data if it is shared. getReadOnlyElements and getWritableElements return ranges for iteration. To feed a pointer-based kernel such as the stencil above, the choices are to copy the input into a std::vector<double> (one pass over the data, what the listing below does), or to work through iterators. On the output side there is a copy-free way: createBuffer<T>(n) allocates an uninitialized buffer, the kernel writes into it, and createArrayFromBuffer<T>(dims,std::move(buffer)) turns it into an array that MATLAB owns.

Source: MATLAB documentation: Structure of C++ MEX Function, Write C++ Functions Callable from MATLAB (MEX Files) and Avoid Copies of Arrays in MEX Functions

The wrapper validates the arguments, adapts the data to the kernel and builds the output. The kernel is the header from the beginning of this page, with no MATLAB dependency, so it compiles into the MEX file unchanged. Errors are raised by calling the MATLAB error function through feval, with a message identifier (here heatflow:laplacianMex:..., names chosen for this page) and a message; the first argument of feval is the function name as a UTF-16 string, then the number of outputs (zero), then a std::vector<matlab::data::Array> of arguments. Not run here.

Points to read in the listing. ArrayType::DOUBLE is the real double type; a complex array reports COMPLEX_DOUBLE, so one comparison rejects both integers and complex data. Each fail call ends in a MATLAB error, which leaves the function, so the code after a failed check does not run (the checks are ordered so that later ones can rely on earlier ones: inputs[1] is only touched when two inputs exist). The class has no constructor and no state, which is the right shape for a pure function; factory is a member only because several methods use it. The kernel gets in.data() and the buffer’s pointer, never a MATLAB object. And the output has the right shape because createArrayFromBuffer reads its buffer column-major by default, the same layout the kernel writes.

Build and test from MATLAB. A test that compares with the indexed MATLAB version from the vectorization page is the most useful one, and the five lines are written so that they could go into a function-based test (see Unit Testing with matlab.unittest) in the project. Not run here: the expected result is the shape and values shown for the plain C++ program and for the Octave reference above.

Because every error comes from the source above, the identifier shown in the last comment is the one written there; MATLAB’s own messages for other mistakes (for example calling with the wrong number of output arguments) were not captured.

The performance of the compiled version against the vectorized one has not been measured on this page, and no number is claimed. The stencil is a memory-bound kernel that vectorized MATLAB code already runs in optimized loops, so a MEX version is worth building only if timeit on your own data says it is. The one thing a MEX version can do that vectorized code cannot is to compute in place, without the temporary arrays that the four shifted slices create.

Source: MATLAB documentation: Create a C++ MEX Source File, Handle Inputs and Outputs and matlab::data::ArrayFactory

C++ MEX functions can run in a separate process with no code change. mh = mexhost creates a MEX host process (a matlab.mex.MexHost object) and feval(mh,"laplacianMex",T,dx) runs the function in it. That isolates a crash in the MEX function from the MATLAB process, lets you use a third-party library that conflicts with MATLAB’s own, lets you attach a debugger to the host, and lets Ctrl+C interrupt the call. Data passed between the processes is limited to 2 GB, and the function runs in the MATLAB current folder. Not run here.

The remaining topics of the C++ MEX documentation, each on its own page, are calling MATLAB functions from the MEX function (feval, eval), getting and setting variables of the base and global workspaces, MATLAB objects and properties, MEX functions as class methods, calling MATLAB from user-created threads with the asynchronous Engine API, and catching exceptions. The MEX API is not thread safe ("MEX API Is Not Thread Safe" in the documentation), and a thread that you create yourself may call MATLAB only through the asynchronous methods of the Engine API.

Source: MATLAB documentation: Out-of-Process Execution of C++ MEX Functions and mexhost