Main Content

C MEX ファイルのコンポーネント

このトピックは、C 行列 APIでビルドされた MEX ファイルに関するものです。C++ MEX ファイルのビルドの詳細については、MEX アプリケーションの選択を参照してください。

mexFunction ゲートウェイ ルーチン

"ゲートウェイ ルーチン" は、MEX ファイルへのエントリ ポイントです。MATLAB® が MEX ファイルの残りのルーチンにアクセスするとき、このルーチンが使用されます。ゲートウェイ ルーチンの名前は mexFunction です。これは、ソース コードの関数 main を置き換えるものです。

MEX ファイルの命名

mexFunction を含むソース ファイルの名前が MEX 関数の名前、つまり MATLAB で呼び出す関数の名前になります。

バイナリ MEX ファイルのファイル拡張子は、プラットフォームに依存します。ファイル拡張子は、関数 mexext を使って現在のマシンの値を返すことで確認します。

必須パラメーター

関数 mexFunction のシグネチャは以下のとおりです。

void mexFunction(
    int nlhs, mxArray *plhs[],
    int nrhs, const mxArray *prhs[])

この関数は、ソース ファイル内の計算ルーチンやその他の関数の後に配置します。

次の表は mexFunction のパラメーターを説明したものです。

パラメーター説明
prhs右辺入力引数の配列。
plhs左辺出力引数の配列。
nrhs右辺引数の数、つまり配列 prhs のサイズ。
nlhs左辺引数の数、つまり配列 plhs のサイズ。

prhs および plhsmxArray * 型として宣言します。つまり、これは MATLAB 配列を指します。これらは MEX ファイルの引数へのポインターを含むベクトルです。prhs を変更するキーワード const は、MEX ファイルによって入力引数が変更されないことを意味します。

名前 prhs は "parameters, right-hand side (パラメーター、右辺)" を表していると解釈でき、入力パラメーターであることがわかります。同様に、plhs は "parameters, left-hand side (パラメーター、左辺)" を表しており、出力パラメーターであることがわかります。

入出力パラメーターの管理

入力パラメーター (配列 prhs にある) は読み取り専用です。MEX ファイルで変更しないようにしてください。入力パラメーター内のデータを変更すると、好ましくない副次作用が生じることがあります。

出力データや MEX ファイルでローカルに使用する任意のデータを作成するために入力パラメーターを使用する際も、注意が必要です。入力配列をローカルで定義された変数 myData にコピーするには、関数 mxDuplicateArray を呼び出して入力配列のコピーを作成します。たとえば、次のようになります。

mxArray *myData = mxCreateStructMatrix(1,1,nfields,fnames);
mxSetField(myData,0,"myFieldName",mxDuplicateArray(prhs[0]));

詳細は、トラブルシューティングのトピックセルまたは構造体 mxArray の不適切な作成を参照してください。

入力の検証

関数の入力を検証する関数の一覧は、C 行列 API を参照してください。

関数 mxIsClassmxArray をテストするための汎用的方法です。たとえば、2 番目の入力引数 (prhs[1] で指定) が実数の完全な行列でなければならないとします。この条件を確認するには、次のステートメントを使用します。

if(mxIsSparse(prhs[1]) || 
   mxIsComplex(prhs[1]) || 
   mxIsClass(prhs[1],"char")) {
      mexErrMsgIdAndTxt("MyToolbox:myfnc:nrhs",
          "input2 must be full matrix of real values.");
}

この例は、網羅的なチェックではありません。構造体、cell 配列、関数ハンドル、MATLAB オブジェクトなどもテストできます。

計算ルーチン

"計算ルーチン" には、バイナリ MEX ファイルへの実装が望まれる計算を実行するためのコードが含まれています。必須ではありませんが、ゲートウェイ ルーチン mexFunction を記述して計算ルーチンを呼び出すことを検討してください。mexFunction コードをラッパーとして使用して入力パラメーターを検証し、それらを計算ルーチンで必要な型に変換します。

ゲートウェイ ルーチンと計算ルーチンを別々に記述する場合、1 つのソース ファイルにまとめることも別々のファイルにすることもできます。別々のファイルを使用する場合、mexFunction を含むファイルは mex コマンドでリストされる最初のソース ファイルでなければなりません。

参考

| | | | |

関連するトピック