C++ MEX API

Note

The C++ MEX API is not compatible with the C MEX API described in C MEX File Applications. 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::FunctionBase class for C++ MEX functions
matlab::mex::ArgumentListContainer for inputs and outputs from C++ MEX functions
matlab::engine::MATLABEngineClass 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::fevalCall MATLAB functions with arguments
matlab::engine::MATLABEngine::fevalAsyncCall MATLAB function with arguments and returned values asynchronously.
matlab::engine::MATLABEngine::evalEvaluate MATLAB statements in the base workspace
matlab::engine::MATLABEngine::evalAsyncEvaluate MATLAB statements in the base workspace asynchronously
matlab::engine::MATLABEngine::getVariableGet variables from the MATLAB base or global workspace
matlab::engine::MATLABEngine::getVariableAsyncGet variables from the MATLAB base or global workspace asynchronously
matlab::engine::MATLABEngine::setVariablePut variables in the MATLAB base or global workspace
matlab::engine::MATLABEngine::setVariableAsyncPut variables in the MATLAB base or global workspace asynchronously
matlab::engine::MATLABEngine::getPropertyGet object property
matlab::engine::MATLABEngine::getPropertyAsyncGet object property asynchronously
matlab::engine::MATLABEngine::setPropertySet object property
matlab::engine::MATLABEngine::setPropertyAsyncSet 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. 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

ExceptionCause

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

MATLAB Documentation

Support

Introducing Deep Learning with MATLAB

Introducing Deep Learning with MATLAB

Download ebook