Connect C++ to Running MATLAB Session

You can connect a C++ engine to shared out-of-process MATLAB^® sessions that are running on the local machine.

To connect to a shared MATLAB session:

Start MATLAB as a shared session, or make a running MATLAB process shared using the MATLAB matlab.engine.shareEngine function. Your MATLAB session must be in out-of-process mode.
Find the names of the MATLAB shared sessions using matlab::engine::findMATLAB or matlab::engine::findMATLABAsync.
Pass a matlab::engine::String containing the name of the shared MATLAB session to the matlab::engine::connectMATLAB or matlab::engine::connectMATLABAsync member function. These functions connect the C++ engine to the shared session.

If you do not specify a session name, the engine connects to the first shared MATLAB session available. If none are available, it creates and connects to a new session.

For setup and build instructions, see Requirements to Build C++ Engine Applications.

Connect to Shared MATLAB

This example connects to the first shared MATLAB session found.

#include "MatlabEngine.hpp"

void syncConnect() {
    using namespace matlab::engine;

    // Connect to shared MATLAB session
    std::unique_ptr<MATLABEngine> matlabPtr = connectMATLAB();
}

Connect to Shared MATLAB Asynchronously

This example connects to the first shared MATLAB session asynchronously.

#include "MatlabEngine.hpp"

void asyncConnect() {
    using namespace matlab::engine;

    // Find and connect to shared MATLAB session
    FutureResult<std::unique_ptr<MATLABEngine>> futureMATLAB = connectMATLABAsync();
    std::unique_ptr<MATLABEngine> matlabPtr = futureMATLAB.get();
}

Specify Name of Shared Session

This example shows how to specify the name of the shared MATLAB session when starting MATLAB. Doing so eliminates the need to call matlab::engine::findMATLAB or matlab::engine::findMATLABAsync.

Start MATLAB with a named shared session.

matlab -r "matlab.engine.shareEngine('myMatlabEngine')"

Connect to the named session from C++.

Note

Start the named MATLAB session before connecting from the C++ code.

#include "MatlabEngine.hpp"

void connectToML() {
    using namespace matlab::engine;

    // Connect to named shared MATLAB session started as:
    // matlab -r "matlab.engine.shareEngine('myMatlabEngine')"
    std::unique_ptr<MATLABEngine> matlabPtr = connectMATLAB(u"myMatlabEngine");
}

Find and Connect to Named Shared Session

To connect to a named MATLAB shared session, use matlab::engine::findMATLAB or matlab::engine::findMATLABAsync to find the names of all available named MATLAB shared sessions.

This example finds a MATLAB shared session myMatlabEngine and connects to it if found.

void findNConnect() {
    using namespace matlab::engine;

    // Find and connect to shared MATLAB session
    std::unique_ptr<MATLABEngine> matlabPtr;
    std::vector<String> names = findMATLAB();
    std::vector<String>::iterator it;
    it = std::find(names.begin(), names.end(), u"myMatlabEngine");
    if (it != names.end()) {
        matlabPtr = connectMATLAB(*it);
    }

    // Determine if engine connected
    if (matlabPtr){
        matlab::data::ArrayFactory factory;
        matlab::data::CharArray arg = factory.createCharArray("-release");
        matlab::data::CharArray version = matlabPtr->feval(u"version", arg);
        std::cout << "Connected to: " << version.toAscii() << std::endl;
    }
    else {
        std::cout << "myMatlabEngine not found" << std::endl;
    }
}

Connect in Multiple-Thread Environments

You can connect to shared MATLAB sessions in multiple-thread environments.

Connect to different shared MATLAB sessions from separate threads of a C++ application.
Connect to a single MATLAB session from multiple engine applications.