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::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 ). |
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)
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.
| 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. |
| Outputs returned from MATLAB function. |
| Single output returned from MATLAB function. |
| Output returned from MATLAB function as a user-specified type. Can be a |
| 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)
Call MATLAB function with arguments and returned values asynchronously. For more information Making async Requests Using mexCallMATLAB.
| 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. |
| A |
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> ())
Evaluate a MATLAB statement as a text string in the calling function workspace.
| 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 |
| 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> ())
Evaluate a MATLAB statement as a string asynchronously. For more information Making async Requests Using mexCallMATLAB.
| 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. |
| A |
None
matlab::engine::MATLABEngine::getVariable
matlab::data::Array getVariable(const std::u16string &varName, WorkspaceType workspaceType = WorkspaceType::BASE)
Get a variable from the MATLAB base or global workspace.
| 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 |
| Variable obtained from the MATLAB base or global workspace |
| 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)
Get a variable from the MATLAB base or global workspace asynchronously.
| 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 |
| A |
None
matlab::engine::MATLABEngine::setVariable
void setVariable(const std::u16string &varName, const matlab::data::Array &var, WorkspaceType workspaceType = WorkspaceType::BASE)
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.
| 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)
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.
| 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 |
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)
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.
| 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 |
| Value of the named property |
| 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)
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.
| 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 |
|
|
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)
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.
| 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 |
| 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)
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.
| 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. |
None
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