C++ MEX API

Note

The C++ MEX API is not compatible with the C MEX API described in Write C Functions Callable from MATLAB (MEX Files). You cannot mix these APIs in a MEX file.

The C++ MEX API enables you to create applications that take advantage of C++11 features, such as move semantics, exception handling, and memory management.

matlab::mex::Function	Base class for C++ MEX functions
matlab::mex::ArgumentList	Container for inputs and outputs from C++ MEX functions
matlab::engine::MATLABEngine	Class defining engine API

matlab::mex::Function

All MEX file implementations are classes that derive from matlab::mex::Function.

std::shared_ptr<matlab::engine::MatlabEngine> getEngine()	Get pointer to the MATLABEngine object
void mexLock()	Prevent clearing of MEX file from memory
void mexUnLock()	Allow clearing of MEX file from memory
std::u16string getFunctionName()	Get the name of the current MEX function

matlab::mex::ArgumentList

The MEX function arguments passed via the operator() of the MexFunction class are matlab::mex::ArgumentList containers. ArgumentList is a full range to the underlying collection of arrays. The ArgumentList object supports the following functions.

operator[]	Enables [] indexing into the elements of an ArgumentList.
begin()	Begin iterator.
end()	End iterator.
size()	Returns the number of elements in the argument list. Use this function to check the number of inputs and outputs specified at the call site.
empty()	Returns a logical value indicating if the argument list is empty (size() == 0).

C++ Engine API

Access MATLAB^® functions, variables, and objects using the matlab::engine::MATLABEngine API described in the following sections. To call the matlab::engine::MATLABEngine functions, get a shared pointer that is returned by the matlab::mex::Function::getEngine function. For example:

std::shared_ptr<matlab::engine::MATLABEngine> matlabPtr = getEngine();

Use this pointer to call engine functions. For example:

matlabPtr->feval(...);

Call engine functions only on the same thread as the MexFunction class.

matlab::engine::MATLABEngine::feval	Call MATLAB functions with arguments
matlab::engine::MATLABEngine::fevalAsync	Call MATLAB function with arguments and returned values asynchronously.
matlab::engine::MATLABEngine::eval	Evaluate MATLAB statements in the base workspace
matlab::engine::MATLABEngine::evalAsync	Evaluate MATLAB statements in the base workspace asynchronously
matlab::engine::MATLABEngine::getVariable	Get variables from the MATLAB base or global workspace
matlab::engine::MATLABEngine::getVariableAsync	Get variables from the MATLAB base or global workspace asynchronously
matlab::engine::MATLABEngine::setVariable	Put variables in the MATLAB base or global workspace
matlab::engine::MATLABEngine::setVariableAsync	Put variables in the MATLAB base or global workspace asynchronously
matlab::engine::MATLABEngine::getProperty	Get object property
matlab::engine::MATLABEngine::getPropertyAsync	Get object property asynchronously
matlab::engine::MATLABEngine::setProperty	Set object property
matlab::engine::MATLABEngine::setPropertyAsync	Set object property asynchronously

matlab::engine::MATLABEngine::feval

std::vector<matlab::data::Array> feval(const std::u16string &function,
   const size_t numReturned,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer>,
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer>())

matlab::data::Array feval(const std::u16string &function, 
   const std::vector<matlab::data::Array> &args, 
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer>())

matlab::data::Array feval(const std::u16string &function,
   const matlab::data::Array &arg,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer>())

ResultType feval(const std::u16string &function,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output,
   const std::shared_ptr<matlab::engine::StreamBuffer> &error,
   RhsArgs&&... rhsArgs )

ResultType feval(const std::u16string &function,
   RhsArgs&&... rhsArgs)

Description

Call MATLAB functions from MEX functions. Use feval to call MATLAB functions with arguments passed from MEX functions and to return a result from MATLAB to the MEX function.

Inputs and outputs are types defined by the MATLAB Data API for C++. There is also a syntax to support native C++ types.

Parameters

const std::u16string &function	Name of the MATLAB function or script to evaluate. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.
const size_t nlhs	Number of returned values.
const std::vector<matlab::data::Array> &args	Multiple input arguments to pass to the MATLAB function in a std::vector. The vector is converted to a column array in MATLAB.
const matlab::data::Array &arg	Single input argument to pass to the MATLAB function.
const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>()	Stream buffer used to store the standard output from the MATLAB function.
const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>()	Stream buffer used to store the error message from the MATLAB function.
RhsArgs&&... rhsArgs	Native C++ data types used for function inputs. feval accepts scalar inputs of these C++ data types: bool, int8_t, int16_t, int32_t, int64_t, uint8_t, uint16_t, uint32_t, uint64_t, float, double.

Return Value

std::vector<matlab::data::Array>	Outputs returned from MATLAB function.
matlab::data::Array	Single output returned from MATLAB function.
ResultType	Output returned from MATLAB function as a user-specified type. Can be a std::tuple if returning multiple arguments.

Exceptions

matlab::engine::MATLABException	There is a MATLAB run-time error in the function.
matlab::engine::TypeConversionException	The result of a MATLAB function cannot be converted to the specified type.
matlab::engine::MATLABSyntaxException	There is a syntax error in the MATLAB function.

For more information, see Call MATLAB Functions from MEX Functions

matlab::engine::MATLABEngine::fevalAsync

FutureResult<std::vector<matlab::data::Array>> fevalAsync(const std::u16string &function,
   const size_t numReturned,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())

FutureResult<matlab::data::Array> fevalAsync(const std::u16string &function,
   const std::vector<matlab::data::Array> &args,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>())

FutureResult<matlab::data::Array> fevalAsync(const std::u16string &function,
   const matlab::data::Array &arg,
   const std::shared_ptr<matlab::engine::StreamBuffer> & output = std::shared_ptr<matlab::engine::StreamBuffer>(),
   const std::shared_ptr<matlab::engine::StreamBuffer> & error = std::shared_ptr<matlab::engine::StreamBuffer>())

FutureResult<ResultType> fevalAsync(const std::u16string &function,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output,
   const std::shared_ptr<matlab::engine::StreamBuffer> &error,
   RhsArgs&&... rhsArgs)

FutureResult<ResultType> fevalAsync(const std::u16string &function,
   RhsArgs&&... rhsArgs)

Description

Call MATLAB function with arguments and returned values asynchronously. For more information Making async Requests Using mexCallMATLAB.

Parameters

const std::u16string &function	Name of the MATLAB function or script to evaluate. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.
const size_t numReturned	Number of returned values
const std::vector<matlab::data::Array> &args	Multiple input arguments to pass to the MATLAB function in an std::vector. The vector is converted to a column array in MATLAB.
const matlab::data::Array arg	Single input argument to pass to the MATLAB function.
const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>()	Stream buffer used to store the standard output from the MATLAB function.
const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>()	Stream buffer used to store the error message from the MATLAB function.
RhsArgs&&... rhsArgs	Native C++ data types used for function inputs. feval accepts scalar inputs of these C++ data types: bool, int8_t, int16_t, int32_t, int64_t, uint8_t, uint16_t, uint32_t, uint64_t, float, double.

Return Value

FutureResult

A FutureResult object used to get the result of calling the MATLAB function.

Exceptions

None

matlab::engine::MATLABEngine::eval

void eval(const std::u16string &statement,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = 
       std::shared_ptr<matlab::engine::StreamBuffer> (),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = 
       std::shared_ptr<matlab::engine::StreamBuffer> ())

Description

Evaluate a MATLAB statement as a text string in the calling function workspace.

Parameters

const std::u16string &statement	MATLAB statement to evaluate
const std::shared_ptr<matlab::engine::StreamBuffer> &output	Stream buffer used to store the standard output from the MATLAB statement
const std::shared_ptr<matlab::engine::StreamBuffer> &error	Stream buffer used to store the error message from the MATLAB command

Exceptions

matlab::engine::MATLABExecutionException	There is a run-time error in the MATLAB statement.
matlab::engine::MATLABSyntaxException	There is a syntax error in the MATLAB statement.

For more information, see Execute MATLAB Statements from MEX Function

matlab::engine::MATLABEngine::evalAsync

FutureResult<void> evalAsync(const std::u16string &str,
   const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer> (),
   const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer> ())

Description

Evaluate a MATLAB statement as a string asynchronously. For more information Making async Requests Using mexCallMATLAB.

Parameters

const std::u16string &str	MATLAB statement to evaluate
const std::shared_ptr<matlab::engine::StreamBuffer> & output	Stream buffer used to store the standard output from the MATLAB statement.
const std::shared_ptr<matlab::engine::StreamBuffer> & error	Stream buffer used to store the error message from the MATLAB command.

Return Value

matlab::engine::FutureResult

A FutureResult object used to wait for the completion of the MATLAB statement.

Exceptions

None

matlab::engine::MATLABEngine::getVariable

matlab::data::Array getVariable(const std::u16string &varName,
    WorkspaceType workspaceType = WorkspaceType::BASE)

Description

Get a variable from the MATLAB base or global workspace.

Parameters

const std::u16string& varName	Name of a variable in the MATLAB workspace. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.
matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE	MATLAB workspace (BASE or GLOBAL) to get the variable from. For more information, see global and matlab::engine::WorkspaceType.

Return Value

matlab::data::Array

Variable obtained from the MATLAB base or global workspace

Exceptions

matlab::engine::MATLABExecutionException

The requested variable does not exist in the specified MATLAB base or global workspace.

For more information, see Set and Get MATLAB Variables from MEX

matlab::engine::MATLABEngine::getVariableAsync

FutureResult<matlab::data::Array> getVariableAsync(const std::u16string &varName,
    WorkspaceType workspaceType = WorkspaceType::BASE)

Description

Get a variable from the MATLAB base or global workspace asynchronously.

Parameters

const std::u16string& varName	Name of the variable in MATLAB workspace. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.
WorkspaceType workspaceType = WorkspaceType::BASE	MATLAB workspace (BASE or GLOBAL) to get the variable from. For more information, see global.

Return Value

matlab::engine::FutureResult

A FutureResult object that you can use to get the variable obtained from the MATLAB workspace as a matlab.data.Array.

Exceptions

None

matlab::engine::MATLABEngine::setVariable

void setVariable(const std::u16string &varName,
   const matlab::data::Array &var,
   WorkspaceType workspaceType = WorkspaceType::BASE)

Description

Put a variable into the MATLAB base or global workspace. If a variable with the same name exists in the MATLAB workspace, setVariable overwrites it.

Parameters

const std::u16string& varName	Name of the variable to create in the MATLAB workspace. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.
const matlab::data::Array var	Value of the variable to create in the MATLAB workspace.
matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE	MATLAB workspace (BASE or GLOBAL) to put the variable into. For more information, see global and matlab::engine::WorkspaceType.

For more information, see Set and Get MATLAB Variables from MEX

matlab::engine::MATLABEngine::setVariableAsync

FutureResult<void> setVariableAsync(const std::u16string &varName,
   const matlab::data::Array var,
   WorkspaceType workspaceType = WorkspaceType::BASE)

Description

Put a variable into the MATLAB base or global workspace asynchronously. If a variable with the same name exists in the MATLAB base workspace, setVariableAsync overwrites it.

Parameters

const std::u16string& varName	Name of the variable to create in the MATLAB workspace. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.
const matlab::data::Array var	Value of the variable to create in the MATLAB workspace
WorkspaceType workspaceType = WorkspaceType::BASE	Put the variable in the MATLAB BASE or GLOBAL workspace. For more information, see global.

Exceptions

None

matlab::engine::MATLABEngine::getProperty

matlab::data::Array getProperty(const matlab::data::Array &objectArray,
    size_t index,
    const std::u16string &propertyName)

matlab::data::Array getProperty(const matlab::data::Array &object,
    const std::u16string &propertyName)

Description

Get the value of an object property. If the object input argument is an array of objects, specify the index of the array element that corresponds to the object whose property value you want to get.

Parameters

const matlab::data::Array &objectArray	Array of MATLAB objects
const matlab::data::Array &object	Scalar MATLAB object
size_t index	Zero-based index into the object array, specifying the object in that array whose property value is returned
const std::u16string &propertyName	Name of the property. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.

Return Value

matlab::data::Array

Value of the named property

Exceptions

matlab::engine::MATLABExecutionException

The property does not exist.

For more information, see MATLAB Objects in MEX Functions

matlab::engine::MATLABEngine::getPropertyAsync

matlab::engine::FutureResult<matlab::data::Array> getPropertyAsync(const matlab::data::Array &objectArray,
    size_t index,
    const std::u16string &propertyName)

matlab::engine::FutureResult<matlab::data::Array> getPropertyAsync(const matlab::data::Array &object,
   const std::u16string &propertyName)

Description

Get the value of an object property asynchronously. If the object input argument is an array of objects, specify the index of the array element that corresponds to the object whose property value you want to get.

Parameters

const matlab::data::Array &objectArray	Array of MATLAB objects
const matlab::data::Array &object	Scalar MATLAB object
size_t index	Zero-based index into the object array, specifying the object in that array whose property value is returned
const std::u16string &propertyName	Name of the property. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.

Return Value

matlab::engine::FutureResult

matlab::engine::FutureResult object that is used to synchronize the operation.

Exceptions

None

matlab::engine::MATLABEngine::setProperty

void setProperty(matlab::data::Array &objectArray,   
    size_t index,
    const std::u16string &propertyName,
    const matlab::data::Array &propertyValue)

void setProperty(matlab::data::Array &object, 
    const std::u16string &propertyName,
    const matlab::data::Array &propertyValue)

Description

Set the value of an object property. If the object input argument is an array of objects, specify the index of the array element that corresponds to the object whose property value you want to set.

Parameters

matlab::data::Array &objectArray	Array of MATLAB objects
matlab::data::Array &object	Scalar MATLAB object
size_t index	Zero-based index into the object array, specifying the object in that array whose property value is set
const std::u16string &propertyName	Name of the property to set. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.
const matlab::data::Array &propertyValue	Value assigned to the property

Exceptions

matlab::engine::MATLABExecutionException

The property does not exist.

For more information, see MATLAB Objects in MEX Functions

matlab::engine::MATLABEngine::setPropertyAsync

FutureResult<void> setPropertyAsync(matlab::data::Array &objectArray,   
    size_t index,
    const std::u16string &propertyName,
    const matlab::data::Array &propertyValue)

FutureResult<void> setPropertyAsync(matlab::data::Array &object,
 const std::u16string &propertyName,
 const matlab::data::Array &propertyValue)

Description

Set the value of an object property asynchronously. If the object input argument is an array of objects, specify the index of the array element that corresponds to the object whose property value you want to set.

Parameters

matlab::data::Array &objectArray	Array of MATLAB objects
matlab::data::Array &object	Scalar MATLAB object
size_t index	Zero-based index into the object array, specifying the object in that array whose property value is set
const std::u16string &propertyName	Name of the property to set. Specify the name as an std::u16string. Also, you can specify this parameter as an std::string.
const matlab::data::Array &propertyValue	Value assigned to the property.

Exceptions

None

Exception Classes

Exception	Cause
matlab::engine::EngineException	There is a MATLAB run-time error in the function or MATLAB fails to start.
matlab::engine::MATLABSyntaxException	There is a syntax error in the MATLAB function.
matlab::engine::MATLABExecutionException	There is a MATLAB run-time error in the MATLAB function or statement.
matlab::engine::TypeConversionException	The result of the MATLAB function cannot be converted to the specified type

For more information, see Catch Exceptions in MEX Function

Related Topics

• Write C++ Functions Callable from MATLAB (MEX Files)