C++ MEX API
注意
C++ MEX API 与 编写可从 MATLAB(MEX 文件)调用的 C 函数中所述的 C MEX API 不兼容。您不能在 MEX 文件中混用这些 API。
通过 C++ MEX API,您可以创建利用 C++11 功能(例如移动语义、异常处理和内存管理)的应用程序。
matlab::mex::Function | C++ MEX 函数的基类 |
matlab::mex::ArgumentList | C++ MEX 函数的输入和输出的容器 |
matlab::engine::MATLABEngine | 定义引擎 API 的类 |
matlab::mex::Function
所有 MEX 文件实现均是从 matlab::mex::Function
派生的类。
std::shared_ptr<matlab::engine::MatlabEngine> getEngine() | 获取指向 MATLABEngine 对象的指针 |
void mexLock() | 防止从内存中清除 MEX 文件 |
void mexUnLock() | 允许从内存中清除 MEX 文件 |
std::u16string getFunctionName() | 获取当前 MEX 函数的名称 |
matlab::mex::ArgumentList
通过 MexFunction
类的 operator()
传递的 MEX 函数参数是 matlab::mex::ArgumentList
容器。ArgumentList
完全涵盖数组的基本集合。ArgumentList
对象支持以下函数。
operator[] | 支持对 ArgumentList 的元素进行 [] 索引。 |
begin() | 启动迭代器。 |
end() | 结束迭代器。 |
size() | 返回参数列表中的元素数。使用此函数检查在调用位置指定的输入和输出的数目。 |
empty() | 返回逻辑值,指示参数列表是否为空 (size() == 0 )。 |
C++ 引擎 API
使用以下各节介绍的 matlab::engine::MATLABEngine
API 访问 MATLAB® 函数、变量和对象。要调用 matlab::engine::MATLABEngine
函数,请获取由 matlab::mex::Function::getEngine
函数返回的共享指针。例如:
std::shared_ptr<matlab::engine::MATLABEngine> matlabPtr = getEngine();
使用此指针调用引擎函数。例如:
matlabPtr->feval(...);
仅可在 MexFunction
类所在相同线程上调用引擎函数。
matlab::engine::MATLABEngine::feval | 带参数调用 MATLAB 函数 |
matlab::engine::MATLABEngine::fevalAsync | 以异步方式带参数和返回值调用 MATLAB 函数。 |
matlab::engine::MATLABEngine::eval | 对基础工作区中的 MATLAB 语句进行求值。 |
matlab::engine::MATLABEngine::evalAsync | 以异步方式对基础工作区中的 MATLAB 语句求值。 |
matlab::engine::MATLABEngine::getVariable | 从 MATLAB 基础工作区或全局工作区获取变量 |
matlab::engine::MATLABEngine::getVariableAsync | 以异步方式从 MATLAB 基础工作区或全局工作区获取变量 |
matlab::engine::MATLABEngine::setVariable | 将变量放在 MATLAB 基础工作区或全局工作区中 |
matlab::engine::MATLABEngine::setVariableAsync | 以异步方式将变量放在 MATLAB 基础工作区或全局工作区中 |
matlab::engine::MATLABEngine::getProperty | 获取对象属性 |
matlab::engine::MATLABEngine::getPropertyAsync | 异步获取对象属性 |
matlab::engine::MATLABEngine::setProperty | 设置对象属性 |
matlab::engine::MATLABEngine::setPropertyAsync | 异步设置对象属性 |
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)
说明
从 MEX 函数调用 MATLAB 函数。使用 feval
带从 MEX 函数传递的参数调用 MATLAB 函数,并将来自 MATLAB 的结果返回给 MEX 函数。
输入和输出是由 用于 C++ 的 MATLAB 数据 API 定义的类型。还有一种语法支持原生 C++ 类型。
参数
| 要计算的 MATLAB 函数或脚本的名称。将名称指定为 |
| 返回值的数目。 |
| 要以 |
| 要传递给 MATLAB 函数的单一输入参数。 |
| 用于存储来自 MATLAB 函数的标准输出的流缓冲区。 |
| 用于存储来自 MATLAB 函数的错误消息的流缓冲区。 |
| 用于函数输入的原生 C++ 数据类型。 |
返回值
| 从 MATLAB 函数返回的输出。 |
| 从 MATLAB 函数返回的单个输出。 |
| 从 MATLAB 返回的作为用户指定的类型的输出。如果返回多个参数,可以是 |
异常
| 函数中存在 MATLAB 运行时错误。 |
| MATLAB 函数的结果无法转换为指定的类型。 |
| MATLAB 函数中存在语法错误。 |
有关详细信息,请参阅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)
说明
以异步方式带参数和返回值调用 MATLAB 函数。有关详细信息,请参阅Making async Requests Using mexCallMATLAB。
参数
| 要计算的 MATLAB 函数或脚本的名称。将名称指定为 |
| 返回值的数目 |
| 要以 |
| 要传递给 MATLAB 函数的单一输入参数。 |
| 用于存储来自 MATLAB 函数的标准输出的流缓冲区。 |
| 用于存储来自 MATLAB 函数的错误消息的流缓冲区。 |
| 用于函数输入的原生 C++ 数据类型。 |
返回值
|
|
异常
无
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> ())
说明
在调用函数工作区中,将 MATLAB 语句作为文本字符串进行计算。
参数
| 要计算的 MATLAB 语句 |
| 用于存储来自 MATLAB 语句的标准输出的流缓冲区 |
| 用于存储来自 MATLAB 命令的错误消息的流缓冲区 |
异常
| MATLAB 语句中存在运行时错误。 |
| MATLAB 语句中存在语法错误。 |
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> ())
说明
以异步方式计算 MATLAB 语句字符串。有关详细信息,请参阅Making async Requests Using mexCallMATLAB。
参数
| 要计算的 MATLAB 语句 |
| 用于存储来自 MATLAB 语句的标准输出的流缓冲区。 |
| 用于存储来自 MATLAB 命令的错误消息的流缓冲区。 |
返回值
|
|
异常
无
matlab::engine::MATLABEngine::getVariable
matlab::data::Array getVariable(const std::u16string &varName, WorkspaceType workspaceType = WorkspaceType::BASE)
说明
从 MATLAB 基础工作区或全局工作区获取变量。
参数
| MATLAB 工作区中变量的名称。将名称指定为 |
| 要从中获取变量的 MATLAB 工作区(BASE 或 GLOBAL)。有关详细信息,请参阅 |
返回值
| 从 MATLAB 基础工作区或全局工作区获得的变量 |
异常
| 指定的 MATLAB 基础工作区或全局工作区中不存在请求的变量。 |
有关详细信息,请参阅Set and Get MATLAB Variables from MEX
matlab::engine::MATLABEngine::getVariableAsync
FutureResult<matlab::data::Array> getVariableAsync(const std::u16string &varName, WorkspaceType workspaceType = WorkspaceType::BASE)
说明
以异步方式从 MATLAB 基础工作区或全局工作区获取变量。
参数
| MATLAB 工作区中变量的名称。将名称指定为 |
| 要从中获取变量的 MATLAB 工作区(BASE 或 GLOBAL)。有关详细信息,请参阅 |
返回值
|
|
异常
无
matlab::engine::MATLABEngine::setVariable
void setVariable(const std::u16string &varName, const matlab::data::Array &var, WorkspaceType workspaceType = WorkspaceType::BASE)
说明
将变量放入 MATLAB 基础工作区或全局工作区中。如果 MATLAB 工作区中存在同名变量,setVariable
会覆盖它。
参数
| 要在 MATLAB 工作区中创建的变量的名称。将名称指定为 |
| 要在 MATLAB 工作区中创建的变量的值。 |
| 在其中放入变量的 MATLAB 工作区(BASE 或 GLOBAL)。有关详细信息,请参阅 |
有关详细信息,请参阅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)
说明
以异步方式将变量放入 MATLAB 基础工作区或全局工作区中。如果 MATLAB 基础工作区中存在同名变量,setVariableAsync
会覆盖它。
参数
| 要在 MATLAB 工作区中创建的变量的名称。将名称指定为 |
| 要在 MATLAB 工作区中创建的变量的值 |
| 将变量放入 MATLAB BASE 或 GLOBAL 工作区。有关详细信息,请参阅 |
异常
无
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)
说明
获取对象属性的值。如果对象输入参数是对象数组,请指定对应于要获取其属性值的对象的数组元素的索引。
参数
| MATLAB 对象的数组 |
| 标量 MATLAB 对象 |
| 对象数组中从 0 开始的索引,指定该数组中返回其属性值的对象 |
| 属性的名称。将名称指定为 |
返回值
| 指定属性的值 |
异常
| 该属性不存在。 |
有关详细信息,请参阅 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)
说明
以异步方式获取对象属性的值。如果对象输入参数是对象数组,请指定对应于要获取其属性值的对象的数组元素的索引。
参数
| MATLAB 对象的数组 |
| 标量 MATLAB 对象 |
| 对象数组中从 0 开始的索引,指定该数组中返回其属性值的对象 |
| 属性的名称。将名称指定为 |
返回值
| 用于同步操作的 |
异常
无
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)
说明
设置对象属性的值。如果对象输入参数是对象数组,请指定对应于要设置其属性值的对象的数组元素的索引。
参数
| MATLAB 对象的数组 |
| 标量 MATLAB 对象 |
| 对象数组中元素的索引(从 0 开始),指定该数组中设置了属性值的对象 |
| 要设置的属性的名称。将名称指定为 |
const matlab::data::Array &propertyValue | 赋给属性的值 |
异常
| 该属性不存在。 |
有关详细信息,请参阅 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)
说明
以异步方式设置对象属性的值。如果对象输入参数是对象数组,请指定对应于要设置其属性值的对象的数组元素的索引。
参数
| MATLAB 对象的数组 |
| 标量 MATLAB 对象 |
| 对象数组中元素的索引(从 0 开始),指定该数组中设置了属性值的对象 |
| 要设置的属性的名称。将名称指定为 |
const matlab::data::Array &propertyValue | 赋给属性的值。 |
异常
无
异常类
异常 | 原因 |
---|---|
| 函数中存在 MATLAB 运行时错误,或 MATLAB 无法启动。 |
| MATLAB 函数中存在语法错误。 |
| MATLAB 函数或语句中存在 MATLAB 运行时错误。 |
| MATLAB 函数的结果无法转换为指定的类型 |
有关详细信息,请参阅Catch Exceptions in MEX Function