Main Content

C++ Engine API

The MATLAB® Engine API for C++ comprises functions, classes, and typedefs in matlab::engine namespace. This API supports the MATLAB Data API, which provides a way for applications running outside of MATLAB to work with MATLAB data through a MATLAB-neutral interface. For more information on the MATLAB Data API, see MATLAB Data API.

Utility Functions

FunctionPurpose
matlab::engine::startMATLABStart a MATLAB session
matlab::engine::startMATLABAsyncStart a MATLAB session asynchronously
matlab::engine::connectMATLABConnect to a shared MATLAB session on the local machine using the specified name.
matlab::engine::connectMATLABAsyncConnect to a shared MATLAB session on the local machine using the specified name asynchronously.
matlab::engine::findMATLABFind all shared MATLAB sessions from the local machine.
matlab::engine::findMATLABAsyncFind all shared MATLAB sessions from the local machine asynchronously.
matlab::engine::convertUTF8StringToUTF16StringConvert UTF-8 string to UTF-16 string.
matlab::engine::convertUTF16StringToUTF8StringConvert UTF-16 string to UTF-8 string.
matlab::engine::terminateEngineClientFree engine resources during runtime

Classes

ClassPurpose
matlab::engine::MATLABEngineUse to execute MATLAB functions from C++.
matlab::engine::FutureResultRetrieve results from asynchronous operations.
matlab::engine::WorkspaceTypeEnumeration class defining MATLAB workspace as BASE or GLOBAL

MATLABEngine Member Functions

The matlab::engine::MATLABEngine class defines the following member functions.

Member FunctionPurpose
fevalEvaluate a MATLAB® function with arguments synchronously.
fevalAsyncEvaluate a MATLAB® function with arguments asynchronously.
evalEvaluate a MATLAB® statement synchronously.
evalAsyncEvaluate a MATLAB® statement asynchronously.
getVariableGet a variable from the MATLAB® base or global workspace synchronously.
getVariableAsyncGet a variable from the MATLAB® base or global workspace asynchronously.
setVariablePut a variable into the MATLAB® base or global workspace synchronously.
setVariableAsyncPut a variable into the MATLAB® base or global workspace asynchronously.
getPropertyGet an object property value.
getPropertyAsyncGet an object property value asynchronously.
setPropertySet an object property value.
setPropertyAsyncSet an object property value asynchronously.

Exception Classes

ExceptionCause

matlab::engine::Exception

Base class of all C++ Engine exceptions.

matlab::engine::EngineException

There is a MATLAB runtime error in function or MATLAB fails to start.

matlab::engine::MATLABNotAvailableException

The MATLAB session is not available

matlab::engine::MATLABSyntaxException

There is a syntax error in the MATLAB function.

matlab::engine::MATLABExecutionException

There is a MATLAB runtime error in the MATLAB function or statement.

matlab::engine::CanceledException

Evaluation of the MATLAB function is canceled.

matlab::engine::InterruptedException

Thrown by matlab::engine::FutureResult::get if the evaluation of the MATLAB function or statement is interrupted.

matlab::engine::TypeConversionException

The result of the MATLAB function cannot be converted to the specified type

Data Size Limitations

The size of data arrays passed between C++ and MATLAB is limited to 2 GB. This limit applies to the data plus supporting information passed between the processes.

Using Engine in Multiple-Thread Environment

The MATLAB Engine for C++ is safe to use in a multiple-thread environment. You can make these connections to shared MATLAB sessions:

  • Connect to different shared MATLAB sessions from separate threads of a C++ application.

  • Connect to a single MATLAB session from multiple engine applications.

You cannot use multiple threads of the same process to connect to a single shared MATLAB session.

Related Topics