プログラムからデータ収集を制御するために、コレクタ共有ライブラリ libcollector.so に含まれているいくつかの API 関数を使用できます。これらの関数は C で記述されています。また、Fortran インタフェースも提供されています。ライブラリとともに提供されるヘッダーファイルに、C インタフェースと Fortran インタフェースの両方が定義されています。
API 関数は、次のように定義されます。
void collector_sample(char *name); void collector_pause(void); void collector_resume(void); void collector_terminate_expt(void);
CollectorAPI クラスに、Java プログラム用の類似の機能が用意されており、これについては、Java インタフェースで説明しています。
collectorAPI.h を取り込み、配下の libcollector.so API 関数の存在をチェックする実際の関数を含む、-lcollectorAPI にリンクすることにより、コレクタ API の C/C++ インタフェースにアクセスできます。
有効な実験がない場合、API 呼び出しは無視されます。
Fortran API の libfcollector.h ファイルは、ライブラリへの Fortran インタフェースを定義します。このライブラリを使用するには、アプリケーションを -lcollectorAPI にリンクする必要があります。このライブラリには、下位互換性を維持するため、-lfcollector というもう 1 つの名前も用意されています。動的関数とスレッドによる呼び出しの一時停止と再開を除けば、Fortran API は C/C++ API と同じ機能を提供します。
Fortran の場合、API 関数を使用するには、次の文を挿入します。
include "libfcollector.h"
次の文を使用して、CollectorAPI クラスをインポートし、Java API にアクセスします。ただし、アプリケーションは、クラスパスが /installation_directory/lib/collector.jar (installation_directory は Oracle Solaris Studio ソフトウェアがインストールされているディレクトリです) を指している状態で起動される必要があります。
import com.sun.forte.st.collector.CollectorAPI;
Java CollectorAPI メソッドは、次のように定義されます。
CollectorAPI.sample(String name) CollectorAPI.pause() CollectorAPI.resume() CollectorAPI.terminate()
Java API には、動的関数 API 以外の C および C++ API と同じ関数が含まれています。
C インクルードファイルの libcollector.h には、データが収集されていないときには実際の API 関数への呼び出しを迂回するマクロが含まれています。この場合、関数は動的にロードされません。ただし、一部の条件では適切に機能しないことがあるため、これらのマクロを使用するのは危険です。 マクロを使用しないので、collectorAPI.h を使用すると安全性が高まります。このファイルでは、関数が直接参照されます。
Fortran API サブルーチンはパフォーマンスデータが収集されているときには C API 関数を呼び出し、そうでないときには復帰します。チェック処理のオーバーヘッドは非常に小さいので、プログラムのパフォーマンスにはあまり影響がないはずです。
パフォーマンスデータを収集するには、この章で後述するように、コレクタを使用してプログラムを実行する必要があります。API 関数への呼び出しを挿入することによって、データ収集が有効になることはありません。
マルチスレッドプログラムで API 関数を使用する場合は、これらの関数が 1 つのスレッドによってのみ呼び出されるようにしてください。API 関数は、個別のスレッドではなくプロセスに適用される動作を実行します。各スレッドが API 関数を呼び出すと、記録されたデータが期待したものにならない可能性があります。たとえば、あるスレッドが collector_pause() や collector_terminate_expt() を呼び出したときに、ほかのスレッドがまだプログラム内のそのポイントに達していない場合、すべてのスレッドについて収集が一時停止または停止され、この API 呼び出しの前にコードを実行していたスレッドのデータが失われる可能性があります。