Integrate C++ Shared Libraries

C++ Shared Library Wrapper

The C++ library wrapper option allows you to create a shared library from an arbitrary set of MATLAB^® files. MATLAB Compiler SDK™ generates a wrapper file and a header file. The header file contains all of the entry points for all of the compiled MATLAB functions.

C++ Shared Library Example

This example rewrites the C shared library example using C++. The procedure for creating a C++ shared library from MATLAB files is identical to the procedure for creating a C shared library, except you use the cpplib wrapper. Enter the following command on a single line:

mcc -W cpplib:libmatrix -T link:lib addmatrix.m multiplymatrix.m eigmatrix.m -v

The -W cpplib:<libname> option tells MATLAB Compiler SDK to generate a function wrapper for a shared library and call it <libname>. The -T link:lib option specifies the target output as a shared library. Note the directory where the product puts the shared library because you will need it later.

Writing the Driver Application

Note

Due to name mangling in C++, you must compile your driver application with the same version of your third-party compiler that you use to compile your C++ shared library.

In the C++ version of the matrix application matrix_mwarray.cpp, arrays are represented by objects of the class mwArray. Every mwArray class object contains a pointer to a MATLAB array structure. For this reason, the attributes of an mwArray object are a superset of the attributes of a MATLAB array. Every MATLAB array contains information about the size and shape of the array (i.e., the number of rows, columns, and pages) and either one or two arrays of data. The first array stores the real part of the array data and the second array stores the imaginary part. For arrays with no imaginary part, the second array is not present. The data in the array is arranged in column-major, rather than row-major, order.

Caution

Avoid issuing cd commands from the driver application prior to calling mclInitializeApplication. Failure to do so can cause a failure in MATLAB Runtime initialization.

For information about how MATLAB Compiler SDK uses a proxy layer for the libraries that an application must link, see Understand the mclmcrrt Proxy Layer.

The matrix_mwarray.cpp driver file is located in matlabroot\extern\examples\compilersdk\c_cpp\matrix.

C++ mwArray API Code to Implement Shared Library

/*==============================================================
 *
 * MATRIX_MWARRAY.CPP
 * Sample driver code that calls a C++ shared library created using
 * the MATLAB Compiler SDK. Refer to the MATLAB Compiler SDK
 * documentation for more information.
 *
 * Copyright 1984-Present The MathWorks, Inc.
 *
 *============================================================*/

// Include the library specific header file as generated by the 
// MATLAB Compiler SDK
#include "libmatrix.h"

int run_main(int argc, const char **argv)
{
    if( !libmatrixInitialize() )
    {
        std::cerr << "Could not initialize the library properly"
                   << std::endl;
        return -1;
    }
    else
    {
        try
        {
            // Create input data
            double data[] = {1,2,3,4,5,6,7,8,9};
            mwArray in1(3, 3, mxDOUBLE_CLASS, mxREAL);
            mwArray in2(3, 3, mxDOUBLE_CLASS, mxREAL);
            in1.SetData(data, 9);
            in2.SetData(data, 9);
            
            // Create output array
            mwArray out;
            
            // Call the library function
            addmatrix(1, out, in1, in2);
            
            // Display the return value of the library function
            std::cout << "The sum of the matrix with itself is:" << std::endl;
            std::cout << out << std::endl;
            
            multiplymatrix(1, out, in1, in2);
            std::cout << "The product of the matrix with itself is:" 
                      << std::endl;
            std::cout << out << std::endl;
            
            eigmatrix(1, out, in1);
            std::cout << "The eigenvalues of the original matrix are:"
                      << std::endl;
            std::cout << out << std::endl;
        }
        catch (const mwException& e)
        {
            std::cerr << e.what() << std::endl;
            return -2;
        }
        catch (...)
        {
            std::cerr << "Unexpected error thrown" << std::endl;
            return -3;
        }     
        // Call the application and library termination routine
        libmatrixTerminate();
    }
    // mclTerminateApplication shuts down the MATLAB Runtime.
    // You cannot restart it by calling mclInitializeApplication.
    // Call mclTerminateApplication once and only once in your application.
    mclTerminateApplication();
    return 0;
}

// The main routine. On the Mac, the main thread runs the system code, and
// user code must be processed by a secondary thread. On other platforms, 
// the main thread runs both the system code and the user code.
int main(int argc, const char **argv)
{
    // Call application and library initialization. Perform this 
    // initialization before calling any API functions or
    // Compiler SDK-generated libraries.
    if (!mclInitializeApplication(nullptr, 0)) 
    {
        std::cerr << "Could not initialize the application properly"
                  << std::endl;
        return -1;
    }

    return mclRunMain(static_cast<mclMainFcnType>(run_main), argc, argv);
}

Compiling the Driver Application

To compile the matrix_mwarray.cpp driver code, you use your C++ compiler. By executing the following mbuild command that corresponds to your development platform, you will use your C++ compiler to compile the code.

mbuild matrix_mwarray.cpp libmatrix.lib            (Windows)
mbuild matrix_mwarray.cpp -L. -lmatrix -I.         (UNIX)

Note

This command assumes that the shared library and the corresponding header file are in the current working directory.

On Windows^®, if this is not the case, specify the full path to libmatrix.lib, and use a -I option to specify the directory containing the header file.

On UNIX^®, if this is not the case, replace the “.” (dot) following the -L and -I options with the name of the directory that contains these files, respectively.

Incorporating a C++ Shared Library into an Application

There are two main differences to note when using a C++ shared library:

Interface functions use the mwArray type to pass arguments, rather than the mxArray type used with C shared libraries.
C++ exceptions are used to report errors to the caller. Therefore, all calls must be wrapped in a try-catch block.

Exported Function Signature

The C++ shared library target generates two sets of interfaces for each MATLAB function. For more information, see Functions Generated from MATLAB Files. The generic signature of the exported C++ functions is as follows:

MATLAB Functions with No Return Values

bool MW_CALL_CONV <function-name>(<const_mwArray_references>);

MATLAB Functions with at Least One Return Value

bool MW_CALL_CONV <function-name>(int <number_of_return_values>,
     <mwArray_references>, <const_mwArray_references>);

In this case, const_mwArray_references represents a comma-separated list of references of type const mwArray& and mwArray_references represents a comma-separated list of references of type mwArray&. For example, in the libmatrix library, the C++ interface to the addmatrix MATLAB function is generated as:

void addmatrix(int nargout, mwArray& a, const mwArray& a1,  
               const mwArray& a2);

where a is an output parameter and a1 and a2 are input parameters.

Input arguments passed to the MATLAB function via varargin must be passed via a single mwArray that is a cell array. Each element in the cell array must constitute an input argument. Output arguments retrieved from the MATLAB function via varargout must be retrieved via a single mwArray that is a cell array. Each element in the cell array will constitute an output argument. The number of elements in the cell array will be equal to number_of_return_values - the number of named output parameters. Also note that,

If the MATLAB function takes a varargin argument, the C++ function must be passed an mwArray corresponding to that varargin, even if the mwArray is empty.
If the MATLAB function takes a varargout argument, the C++ function must be passed an mwArray corresponding to that varargin, even if number_of_return_values is set to the number of named output arguments, which means meaning that varargout will be empty.
The varargout argument needs to follow any named output arguments and precede any input arguments.
The varargin argument needs to be the last argument.

Error Handling

C++ interface functions handle errors during execution by throwing a C++ exception. Use the mwException class for this purpose. Your application can catch mwExceptions and query the what() method to get the error message. To correctly handle errors when calling the C++ interface functions, wrap each call inside a try-catch block.

	try
{
		...
		(call function)
		...
}
catch (const mwException& e)
{
		...
		(handle error)
		...
}

The matrix_mwarray.cpp application illustrates the typical way to handle errors when calling the C++ interface functions.

Working with C++ Shared Libraries and Sparse Arrays

The MATLAB Compiler SDK C/C++ API includes static factory methods for working with sparse arrays.

For a complete list of the methods, see C++ Utility Classes.

Documentation