Main Content

C++ MEX API

メモ

C++ MEX API は、C MEX ファイル アプリケーションで説明されている C MEX API と互換性がありません。これらの API を MEX ファイルで混在させることはできません。

C++ MEX API を使用すると、移動セマンティクス、例外処理、メモリ管理などの C++11 機能を活用するアプリケーションを作成できます。

matlab::mex::FunctionC++ MEX 関数の基底クラス
matlab::mex::ArgumentListC++ 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::getVariableMATLAB ベースまたはグローバル ワークスペースから変数を取得する
matlab::engine::MATLABEngine::getVariableAsyncMATLAB ベースまたはグローバル ワークスペースから変数を非同期的に取得する
matlab::engine::MATLABEngine::setVariableMATLAB ベースまたはグローバル ワークスペースに変数を配置する
matlab::engine::MATLABEngine::setVariableAsyncMATLAB ベースまたはグローバル ワークスペースに変数を非同期的に配置する
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++ 型をサポートするための構文もあります。

パラメーター

const std::u16string &function

評価する MATLAB 関数またはスクリプトの名前。名前は std::u16string として指定します。また、このパラメーターは std::string として指定することもできます。

const size_t nlhs

返される値の数。

const std::vector<matlab::data::Array> &args

std::vector で MATLAB 関数に渡される複数の入力引数。ベクトルは MATLAB で列配列に変換されます。

const matlab::data::Array &arg

MATLAB 関数に渡される単一の入力引数。

const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>()

MATLAB 関数からの標準出力を格納するために使用するストリーム バッファー。

const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>()

MATLAB 関数からのエラー メッセージを格納するために使用するストリーム バッファー。

RhsArgs&&... rhsArgs

関数の入力に使用するネイティブ C++ データ型。feval は、C++ データ型 bool、int8_t、int16_t、int32_t、int64_t、uint8_t、uint16_t、uint32_t、uint64_t、float、double のスカラー入力を受け入れます。

戻り値

std::vector<matlab::data::Array>

MATLAB 関数から返される出力。

matlab::data::Array

MATLAB 関数から返される単一の出力。

ResultType

MATLAB 関数からユーザー指定の型として返される出力。複数の引数を返す場合は std::tuple にすることができます。

例外

matlab::engine::MATLABException

関数に MATLAB ランタイム エラーが存在します。

matlab::engine::TypeConversionException

MATLAB 関数の結果を指定された型に変換できません。

matlab::engine::MATLABSyntaxException

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 要求を参照してください。

パラメーター

const std::u16string &function

評価する MATLAB 関数またはスクリプトの名前。名前は std::u16string として指定します。また、このパラメーターは std::string として指定することもできます。

const size_t numReturned

返される値の数

const std::vector<matlab::data::Array> &args

std::vector で MATLAB 関数に渡される複数の入力引数。ベクトルは MATLAB で列配列に変換されます。

const matlab::data::Array arg

MATLAB 関数に渡される単一の入力引数。

const std::shared_ptr<matlab::engine::StreamBuffer> &output = std::shared_ptr<matlab::engine::StreamBuffer>()

MATLAB 関数からの標準出力を格納するために使用するストリーム バッファー。

const std::shared_ptr<matlab::engine::StreamBuffer> &error = std::shared_ptr<matlab::engine::StreamBuffer>()

MATLAB 関数からのエラー メッセージを格納するために使用するストリーム バッファー。

RhsArgs&&... rhsArgs

関数の入力に使用するネイティブ C++ データ型。feval は、C++ データ型 bool、int8_t、int16_t、int32_t、int64_t、uint8_t、uint16_t、uint32_t、uint64_t、float、double のスカラー入力を受け入れます。

戻り値

FutureResult

MATLAB 関数を呼び出した結果を取得するために使用する FutureResult オブジェクト。

例外

なし

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 ステートメントを、呼び出し元の関数ワークスペース内のテキスト文字列として評価します。

パラメーター

const std::u16string &statement

評価する MATLAB ステートメント

const std::shared_ptr<matlab::engine::StreamBuffer> &output

MATLAB ステートメントからの標準出力を格納するために使用するストリーム バッファー

const std::shared_ptr<matlab::engine::StreamBuffer> &error

MATLAB コマンドからのエラー メッセージを格納するために使用するストリーム バッファー

例外

matlab::engine::MATLABExecutionException

MATLAB ステートメントにランタイム エラーがあります。

matlab::engine::MATLABSyntaxException

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 要求を参照してください。

パラメーター

const std::u16string &str

評価する MATLAB ステートメント

const std::shared_ptr<matlab::engine::StreamBuffer> & output

MATLAB ステートメントからの標準出力を格納するために使用するストリーム バッファー。

const std::shared_ptr<matlab::engine::StreamBuffer> & error

MATLAB コマンドからのエラー メッセージを格納するために使用するストリーム バッファー。

戻り値

matlab::engine::FutureResult

MATLAB ステートメントの完了を待機するために使用する FutureResult オブジェクト。

例外

なし

matlab::engine::MATLABEngine::getVariable

matlab::data::Array getVariable(const std::u16string &varName,
    WorkspaceType workspaceType = WorkspaceType::BASE)

説明

MATLAB のベース ワークスペースまたはグローバル ワークスペースから変数を取得します。

パラメーター

const std::u16string& varName

MATLAB ワークスペース内の変数の名前。名前は std::u16string として指定します。また、このパラメーターは std::string として指定することもできます。

matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE

変数の取得先の MATLAB ワークスペース (BASE または GLOBAL)。詳細については、global と matlab::engine::WorkspaceType を参照してください。

戻り値

matlab::data::Array

MATLAB のベース ワークスペースまたはグローバル ワークスペースから取得した変数

例外

matlab::engine::MATLABExecutionException

要求された変数は指定された MATLAB のベース ワークスペースまたはグローバル ワークスペース内にありません。

詳細については、MEX からの MATLAB 変数の設定と取得を参照してください。

matlab::engine::MATLABEngine::getVariableAsync

FutureResult<matlab::data::Array> getVariableAsync(const std::u16string &varName,
    WorkspaceType workspaceType = WorkspaceType::BASE)

説明

MATLAB のベース ワークスペースまたはグローバル ワークスペースから変数を非同期的に取得します。

パラメーター

const std::u16string& varName

MATLAB ワークスペース内の変数の名前。名前は std::u16string として指定します。また、このパラメーターは std::string として指定することもできます。

WorkspaceType workspaceType = WorkspaceType::BASE

変数の取得先の MATLAB ワークスペース (BASE または GLOBAL)。詳細については、global を参照してください。

戻り値

matlab::engine::FutureResult

MATLAB ワークスペースから matlab.data.Array として得られた変数を取得するために使用できる FutureResult オブジェクト。

例外

なし

matlab::engine::MATLABEngine::setVariable

void setVariable(const std::u16string &varName,
   const matlab::data::Array &var,
   WorkspaceType workspaceType = WorkspaceType::BASE)

説明

MATLAB のベース ワークスペースまたはグローバル ワークスペースに変数を入れます。同じ名前の変数が MATLAB ワークスペース内に存在する場合は、setVariable によって上書きされます。

パラメーター

const std::u16string& varName

MATLAB ワークスペースで作成する変数の名前。名前は std::u16string として指定します。また、このパラメーターは std::string として指定することもできます。

const matlab::data::Array var

MATLAB ワークスペースで作成する変数の値。

matlab::engine::WorkspaceType workspaceType = matlab::engine::WorkspaceType::BASE

変数を配置する MATLAB ワークスペース (BASE または GLOBAL)。詳細については、global と matlab::engine::WorkspaceType を参照してください。

詳細については、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 によって上書きされます。

パラメーター

const std::u16string& varName

MATLAB ワークスペースで作成する変数の名前。名前は std::u16string として指定します。また、このパラメーターは std::string として指定することもできます。

const matlab::data::Array var

MATLAB ワークスペースで作成する変数の値

WorkspaceType workspaceType = WorkspaceType::BASE

MATLAB の BASE ワークスペースまたは GLOBAL ワークスペースに変数を入れます。詳細については、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)

説明

オブジェクト プロパティの値を取得します。オブジェクトの入力引数がオブジェクトの配列である場合は、プロパティ値を取得するオブジェクトに対応する配列要素のインデックスを指定します。

パラメーター

const matlab::data::Array &objectArray

MATLAB オブジェクトの配列

const matlab::data::Array &object

スカラー MATLAB オブジェクト

size_t index

オブジェクト配列への 0 ベースのインデックス。その配列内のどのオブジェクトのプロパティ値を返すかを指定します。

const std::u16string &propertyName

プロパティの名前です。名前は std::u16string として指定します。また、このパラメーターは std::string として指定することもできます。

戻り値

matlab::data::Array

指定した名前のプロパティの値

例外

matlab::engine::MATLABExecutionException

プロパティが存在しません。

詳細については、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)

説明

オブジェクト プロパティの値を非同期的に取得します。オブジェクトの入力引数がオブジェクトの配列である場合は、プロパティ値を取得するオブジェクトに対応する配列要素のインデックスを指定します。

パラメーター

const matlab::data::Array &objectArray

MATLAB オブジェクトの配列

const matlab::data::Array &object

スカラー MATLAB オブジェクト

size_t index

オブジェクト配列への 0 ベースのインデックス。その配列内のどのオブジェクトのプロパティ値を返すかを指定します。

const std::u16string &propertyName

プロパティの名前です。名前は std::u16string として指定します。また、このパラメーターは std::string として指定することもできます。

戻り値

matlab::engine::FutureResult

演算を同期させるために使用する matlab::engine::FutureResult オブジェクト。

例外

なし

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::data::Array &objectArray

MATLAB オブジェクトの配列

matlab::data::Array &object

スカラー MATLAB オブジェクト

size_t index

オブジェクト配列への 0 ベースのインデックス。その配列内のどのオブジェクトのプロパティ値を設定するかを指定します。

const std::u16string &propertyName

設定するプロパティの名前。名前は std::u16string として指定します。また、このパラメーターは std::string として指定することもできます。

const matlab::data::Array &propertyValue

プロパティに代入された値

例外

matlab::engine::MATLABExecutionException

プロパティが存在しません。

詳細については、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::data::Array &objectArray

MATLAB オブジェクトの配列

matlab::data::Array &object

スカラー MATLAB オブジェクト

size_t index

オブジェクト配列への 0 ベースのインデックス。その配列内のどのオブジェクトのプロパティ値を設定するかを指定します。

const std::u16string &propertyName

設定するプロパティの名前。名前は std::u16string として指定します。また、このパラメーターは std::string として指定することもできます。

const matlab::data::Array &propertyValue

プロパティに割り当てられた値。

例外

なし

例外クラス

例外原因

matlab::engine::EngineException

関数に MATLAB ランタイム エラーが存在するか、または MATLAB を起動できません。

matlab::engine::MATLABSyntaxException

MATLAB 関数に構文エラーが存在します。

matlab::engine::MATLABExecutionException

MATLAB 関数またはステートメントに MATLAB ランタイム エラーが存在します。

matlab::engine::TypeConversionException

MATLAB 関数の結果を指定された型に変換できません。

詳細については、MEX 関数での例外のキャッチを参照してください。

関連するトピック