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 および plhs を mxArray * 型として宣言します。つまり、これは 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 を参照してください。

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

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

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

計算ルーチン

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

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

参考