外部インタフェース/API

Fortran MEX-ファイルの作成

本章では、Fortran言語でMEX-ファイルを作成する方法を説明します。MEX-ファイル本体、Fortran言語ファイルがMATLABとどのように作用するか、異なるデータタイプの引数をどのように渡して操作するか、MEX-ファイルプログラムのデバッグ方法、その他のアドバンスドトピックスについて説明します。

つぎの一覧は、本章の内容をまとめたものです。:

• Fortran MEX-ファイル
• Fortran MEX-ファイルの例
• アドバンスドトピックス
• Fortran言語MEX-ファイルのデバッグ

Fortran MEX-ファイル

Fortran MEX-ファイルは、APIルーチンの呼び出しを使ってFortranソースコードをコンパイルするために、mexスクリプトを使って作られます。

FortranのMEX-ファイルは、倍精度データと文字列のみを作成することができます(MATLABがサポートする任意のデータタイプを作成できるCの場合と異なります)。Fortran MEX-ファイルはコンパイルするとM-ファンクションのように扱うことができます。

Fortran MEX-ファイルの部分

この節では、Fortran MEX-ファイルで必要な特定の要素について説明します。Fortran MEX-ファイルのソースコードは、C MEX-ファイルのように2つの部分から成り立ちます。

• MEX-ファイルでインプリメントされたユーザの希望する計算を実行するコードを含む計算ルーチン。計算は、データの入出力や数値計算です。
• エントリポイントmexFunctionとパラメータprhs, nrhs, plhs, nlhsにより、計算ルーチンとMATLABのインタフェースを行うゲートウェイルーチン。ここで、prhsは右辺入力引数の配列、nrhsは右辺入力引数の数、plhsは左辺出力引数の配列、nlhsは左辺出力引数の数です。ゲートウェイは、計算ルーチンをサブルーチンとして呼び出します。

計算ルーチンとゲートウェイルーチンは、分離しているか、結合しています。つぎの図Fortran MEXサイクルは、どのように入力がAPI関数に入るか、ゲートウェイ関数がどの関数を実行するか、どのようにMATLABに出力するかを示します。

図 3-1: Fortran MEXサイクル

ポインタのコンセプト

MATLAB APIは、一意的なデータタイプmxArrayをもちます。Fortranでは新しいデータタイプを作成する方法がないため、MATLABはポインタと呼ばれる特殊な識別子をFortranプログラムに渡します。このポインタをアクセスルーチンと呼ばれる様々なAPI関数に渡すことで、mxArrayについての情報を得ることができます。これらのアクセスルーチンにより、mxArrayのサイズ、文字列かどうか、データの内容のような、ユーザの知りたい情報を含むネイティブなFortranのデータタイプを得ることができます。

Fortranでポインタを使うときには、つぎのような特徴があります。

• %valコンストラクト

Fortranコンパイラが%val コンストラクトをサポートしていれば、アクセスルーチンを要求しないで使うことができるポインタ(mxGetPrまたはmxGetPiが出力するポインタ)、すなわちデータのポインタがあります。このポインタの内容をサブルーチンに渡すために%valを使うことができ、これはFortranの倍精度行列として宣言されます。

Fortranコンパイラが%valコンストラクトをサポートしていない場合、ポインタの内容にアクセスするためには、mxCopy__ ルーチン(例、 mxCopyPtrToReal8)を使わなければなりません。%valコンストラクトとその例に関する情報は、「%valコンストラクト」を参照してください。

• 変数の宣言

ポインタを適切に使うために、正しいサイズになるように宣言しなければなりません。DEC Alphaマシンでは、すべてのポインタはinteger*8と宣言されます。他のすべてのプラットフォームでは、ポインタはinteger*4と宣言されます。

FortranコンパイラがCのプリプロセッサをサポートしていれば、プリプロセッシングステージを使ってポインタを適切な宣言へマップすることができます。UNIXでの可能な例については、examplesディレクトリの.Fで終わる例を参照してください。

注意    不正なサイズでポインタを宣言すると、プログラムのクラッシュが起こる場合があります。

ゲートウェイルーチン

ゲートウェイサブルーチンのエントリポイントは、mexFunctionという名前で、つぎのパラメータを含まなければなりません。

subroutine mexFunction(nlhs, plhs, nrhs, prhs)
integer plhs(*), prhs(*)
integer nlhs, nrhs

注意    Fortranは、大文字と小文字の区別を行いません。このドキュメントは読みやすさのために、大文字と小文字の混在した関数を使います。

Fortran MEX-ファイルでは、パラメータnlhsとnrhsは、MEX-ファイルが呼び込まれる左辺と右辺の引数の数を含みます。prhsは、MEX-ファイルの右辺入力へのポインタを含む長さnrhsの配列で、plhsはFortran関数が出力する左辺出力のポインタを含む長さnlhsの配列です。

MATLAB言語のシンタックスでは、関数はつぎのような一般的な形式をもちます。

[a,b,c,...] = fun(d,e,f,...)

ここで、省略形(...)は同じ形式の項を表わします。a,b,c,...は左辺引数で、d,e,f,... は右辺引数です。

ゲートウェイルーチンの例として、MEX-ファイルをつぎのコマンドでMATLABワークスペースから呼び込むことを考えます。

x = fun(y,z);

MATLABインタプリタは、つぎの引数をもつmexFunctionをコールします。

plhsは、一つの要素がnullポインタである1要素のC配列です。prhsは、1番目の要素がYというmxArrayのポインタで、2番目の要素がZというmxArrayのポインタである2要素のC配列です。

出力xはサブルーチンが実行するまで作成されないので、パラメータplhs は何もポイントしません。出力配列を作成し、plhs(1)の配列のポインタを設定するのはゲートウェイルーチンです。plhs(1)が割り当てられない場合は、MATLABは出力が割り当てられていないことを示すワーニングメッセージを表示します。

注意    nlhs = 0であっても出力値を返すことは可能です。これは、結果をans変数に返すことに相当します。

ゲートウェイルーチンは入力引数を確認し、誤りがあればmexErrMsgTxtを呼び出します。これは、出力配列数のチェックと同様に、入力配列の数、タイプ、サイズのチェックを含みます。この節の後の例では、このテクニックを説明します。

mxファンクションは、MATLAB配列操作のためのアクセス法(サブルーチン)を提供します。これらの関数は、オンラインのAPIリファレンスページに記述されています。接頭語mxはmxArrayに対する省略表現で、関数を使ってMATLAB配列の情報の操作やアクセスができることを意味します。たとえば、mxGetPrはMATLAB配列内の実数データを取得します。MATLAB配列とFortran配列のデータの転送のためにルーチンが提供されています。

ゲートウェイルーチンは、結果を出力するために要求されるサイズの配列を作成するために、mxCreateFull, mxCreateSparse, mxCreateStringを呼び出さなければなりません。これらの呼び出しの出力値は、plhsの適切な要素に割り当てられます。

ゲートウェイルーチンは、必要ならば計算ルーチン用の一時的な作業配列を割り当てるためにmxCallocを呼び出します。

ゲートウェイルーチンは、希望する計算や演算を行うために、計算ルーチンを呼び出します。MEX-ファイルが使用できる多くのルーチンがあります。これらのルーチンは、mexCallMATLABとmexErrMsgTxtのように最初のキャラクタmexで区別されます。

MEX-ファイルがその作業を終了するとき、MATLABに制御が戻ります。左辺引数によってMATLABに制御が戻らないMEX-ファイルが作成するデータ構造体は、自動的に破棄されます。

Windowsでのデバッグ

%valコンストラクト