C++ MEX API
メモ
C++ MEX API は、C MEX ファイル アプリケーションで説明されている C MEX API と互換性がありません。これらの API を MEX ファイルで混在させることはできません。
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 ) かどうかを示す logical 値を返します。 |
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 関数に返します。
入力と出力は、MATLAB データ APIによって定義された型です。また、ネイティブ C++ 型をサポートするための構文もあります。
パラメーター
| 評価する MATLAB 関数またはスクリプトの名前。名前は |
| 返される値の数。 |
|
|
| MATLAB 関数に渡される単一の入力引数。 |
| MATLAB 関数からの標準出力を格納するために使用するストリーム バッファー。 |
| MATLAB 関数からのエラー メッセージを格納するために使用するストリーム バッファー。 |
| 関数の入力に使用するネイティブ C++ データ型。 |
戻り値
| MATLAB 関数から返される出力。 |
| MATLAB 関数から返される単一の出力。 |
| MATLAB 関数からユーザー指定の型として返される出力。複数の引数を返す場合は |
例外
| 関数に MATLAB ランタイム エラーが存在します。 |
| MATLAB 関数の結果を指定された型に変換できません。 |
| MATLAB 関数に構文エラーが存在します。 |
詳細については、MEX 関数からの MATLAB 関数の呼び出しを参照してください。
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 関数を非同期的に呼び出す。詳細については、mexCallMATLAB を使用した async 要求を参照してください。
パラメーター
| 評価する MATLAB 関数またはスクリプトの名前。名前は |
| 返される値の数 |
|
|
| MATLAB 関数に渡される単一の入力引数。 |
| MATLAB 関数からの標準出力を格納するために使用するストリーム バッファー。 |
| MATLAB 関数からのエラー メッセージを格納するために使用するストリーム バッファー。 |
| 関数の入力に使用するネイティブ C++ データ型。 |
戻り値
| MATLAB 関数を呼び出した結果を取得するために使用する |
例外
なし
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 ステートメントに構文エラーがあります。 |
詳細については、MEX 関数からの 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 ステートメントを文字列として非同期的に評価します。詳細については、mexCallMATLAB を使用した async 要求を参照してください。
パラメーター
| 評価する MATLAB ステートメント |
| 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 のベース ワークスペースまたはグローバル ワークスペース内にありません。 |
詳細については、MEX からの MATLAB 変数の設定と取得を参照してください。
matlab::engine::MATLABEngine::getVariableAsync
FutureResult<matlab::data::Array> getVariableAsync(const std::u16string &varName, WorkspaceType workspaceType = WorkspaceType::BASE)
説明
MATLAB のベース ワークスペースまたはグローバル ワークスペースから変数を非同期的に取得します。
パラメーター
| MATLAB ワークスペース内の変数の名前。名前は |
| 変数の取得先の MATLAB ワークスペース (BASE または GLOBAL)。詳細については、 |
戻り値
| MATLAB ワークスペースから |
例外
なし
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)。詳細については、 |
詳細については、MEX からの MATLAB 変数の設定と取得を参照してください。
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 ベースのインデックス。その配列内のどのオブジェクトのプロパティ値を返すかを指定します。 |
| プロパティの名前です。名前は |
戻り値
| 指定した名前のプロパティの値 |
例外
| プロパティが存在しません。 |
詳細については、MEX 関数の MATLAB オブジェクトを参照してください。
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 | プロパティに代入された値 |
例外
| プロパティが存在しません。 |
詳細については、MEX 関数の MATLAB オブジェクトを参照してください。
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 関数の結果を指定された型に変換できません。 |
詳細については、MEX 関数での例外のキャッチを参照してください。