C++ Shared Library Example :: Libraries (MATLAB Compiler)

MATLAB Compiler

C++ Shared Library Example

This example rewrites the previous C shared library example using C++. The procedure for creating a C++ shared library from M-files is identical to the procedure for creating a C shared library, except you use the cpplib wrapper.

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

The -W cpplib:<libname> option tells the MATLAB Compiler 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 Compiler puts the shared library because you will need it later on.

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.

This example uses a C++ version of the matrixdriver application, matrixdriver.cpp.

/*==============================================================
 *
 * MATRIXDRIVER.CPP
 * Sample driver code that calls a C++ shared library created using
 * the MATLAB Compiler. Refer to the MATLAB Compiler documentation
 * for more information on this
 *
 * This is the wrapper CPP code to call a shared library created 
 * using the MATLAB Compiler.
 *
 * Copyright 1984-2005 The MathWorks, Inc.
 *
 *============================================================*/

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

int main(){
    

    // Call application and library initialization. Perform this 
    // initialization before calling any API functions or
    // Compiler-generated libraries.
    if (!mclInitializeApplication(NULL,0) || 
        !libmatrixInitialize())
    {
        std::cerr << "could not initialize the library properly"
                   << std::endl;
        return -1;
    }
    
    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 value of added matrix is:" << std::endl;
        std::cout << out << std::endl;

        multiplymatrix(1, out, in1, in2);
        std::cout << "The value of the multiplied matrix is:" 
                   << std::endl;
        std::cout << out << std::endl;

        eigmatrix(1, out, in1);
        std::cout << "The eigenvalues of the first matrix are:"
                   << std::endl;
        std::cout << out << std::endl;
    }
    catch (const mwException& e)
    {
        std::cerr << e.what() << std::endl;
        return -1;
    }
    catch (...)
    {
        std::cerr << "Unexpected error thrown" << std::endl;
        return -1;
    }
     
    // Call the application and library termination routine
    libmatrixTerminate();
    mclTerminateApplication();

    return 0;
}

Compiling the Driver Application

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

mbuild matrixdriver.cpp libmatrix.lib            (Windows)
mbuild matrixdriver.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 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.

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.

Incorporating a C++ Shared Library Into an Application

To incorporate a C++ shared library into your application, you will, in general, follow the steps listed in Steps to Use a Shared Library. 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 M-function. The first set of exported interfaces is identical to the mlx signatures that are generated in C shared libraries. The second set of interfaces is the C++ function interfaces. The generic signature of the exported C++ functions is

M-functions with no return values.

void <function-name>(<list_of_input_variables>);

M-functions with at least one return value.

void <function-name>(int number_of_return_values,
     <list_of_return_variables>, <list_of_input_variables>);

In this case, <list_of_input_variables> represents a comma-separated list of type const mwArray& and <list_of_return_variables> represents a comma-separated list of type mwArray&. For example, in the libmatrix library, the C++ interfaces to the addmatrix M-function is generated as

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

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 matrixdriver.cpp application illustrates the typical way to handle errors when calling the C++ interface functions.

C++ Shared Library Target MATLAB Compiler-Generated Interface Functions