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
| Name of the MATLAB function or script to evaluate. Specify the
name as an |
| Number of returned values. |
| Multiple input arguments to pass to the MATLAB function in a |
| Single input argument to pass to the MATLAB function. |
| Stream buffer used to store the standard output from the MATLAB function. |
| Stream buffer used to store the error message from the MATLAB function. |
| Native C++ data types used for function inputs.
|
Return Value
| Outputs returned from MATLAB function. |
| Single output returned from MATLAB function. |
| Output returned from MATLAB function as a user-specified type. Can be a
|
Exceptions
| There is a MATLAB run-time error in the function. |
| The result of a MATLAB function cannot be converted to the specified type. |
| 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
| Name of the MATLAB function or script to evaluate. Specify the
name as an |
| Number of returned values |
| Multiple input arguments to pass to the MATLAB function in an |
| Single input argument to pass to the MATLAB function. |
| Stream buffer used to store the standard output from the MATLAB function. |
| Stream buffer used to store the error message from the MATLAB function. |
| Native C++ data types used for function inputs.
|
Return Value
| A |
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
| MATLAB statement to evaluate |
| Stream buffer used to store the standard output from the MATLAB statement |
| Stream buffer used to store the error message from the MATLAB command |
Exceptions
| There is a run-time error in the MATLAB statement. |
| 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
| MATLAB statement to evaluate |
| Stream buffer used to store the standard output from the MATLAB statement. |
| Stream buffer used to store the error message from the MATLAB command. |
Return Value
| A |
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
| Name of a variable in the MATLAB workspace. Specify the name as an
|
| MATLAB workspace (BASE or GLOBAL) to get the variable
from. For more information, see |
Return Value
| Variable obtained from the MATLAB base or global workspace |
Exceptions
| 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
| Name of the variable in MATLAB workspace. Specify the name as an
|
| MATLAB workspace (BASE or GLOBAL) to get the variable
from. For more information, see |
Return Value
| A |
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
| Name of the variable to create in the MATLAB workspace. Specify the name as an
|
| Value of the variable to create in the MATLAB workspace. |
| MATLAB workspace (BASE or GLOBAL) to put the variable
into. For more information, see |
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
| Name of the variable to create in the MATLAB workspace. Specify the name as an
|
| Value of the variable to create in the MATLAB workspace |
| Put the variable in the MATLAB BASE or GLOBAL workspace. For more
information, see |
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
| Array of MATLAB objects |
| Scalar MATLAB object |
| Zero-based index into the object array, specifying the object in that array whose property value is returned |
| Name of the property. Specify the name as an
|
Return Value
| Value of the named property |
Exceptions
| 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
| Array of MATLAB objects |
| Scalar MATLAB object |
| Zero-based index into the object array, specifying the object in that array whose property value is returned |
| Name of the property. Specify the name as an
|
Return Value
|
|
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
| Array of MATLAB objects |
| Scalar MATLAB object |
| Zero-based index into the object array, specifying the object in that array whose property value is set |
| Name of the property to set. Specify the name as an
|
const matlab::data::Array
&propertyValue | Value assigned to the property |
Exceptions
| 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
| Array of MATLAB objects |
| Scalar MATLAB object |
| Zero-based index into the object array, specifying the object in that array whose property value is set |
| Name of the property to set. Specify the name as an
|
const matlab::data::Array
&propertyValue | Value assigned to the property. |
Exceptions
None
Exception Classes
Exception | Cause |
---|---|
| There is a MATLAB run-time error in the function or MATLAB fails to start. |
| There is a syntax error in the MATLAB function. |
| There is a MATLAB run-time error in the MATLAB function or statement. |
| The result of the MATLAB function cannot be converted to the specified type |
For more information, see Catch Exceptions in MEX Function