データ収集のプログラム制御 (Sun Studio 12: パフォーマンスアナライザ)

Sun Studio 12: パフォーマンスアナライザ

データ収集のプログラム制御

プログラムからデータ収集を制御するには、コレクタ共有ライブラリ libcollector.so に入っている API 関数をプログラムで使用します。これらの関数は C で記述されており、Fortran インタフェースも用意されています。ライブラリとともに提供されるヘッダーファイルに、C インタフェースと Fortran インタフェースの両方が定義されています。

API 関数は、次のように定義されます。

void collector_sample(char *name);
void collector_pause(void);
void collector_resume(void);
void collector_thread_pause(unsigned int t);
void collector_thread_resume(unsigned int t);
void collector_terminate_expt(void);

CollectorAPI クラスに、Java^TM プログラム用の類似の機能が用意されており、これについては、「Java インタフェース」で説明しています。

C/C++ インタフェース

C/C++ インタフェースにアクセスする方法は 2 通りあります。

collectorAPI.h を取り込み、基になっている libcollector.so API 関数の有無をチェックする実関数が含まれている -lcollectorAPI とリンクする。

この方法では、API ライブラリとリンクする必要があります。この方法は、あらゆる環境下で有効です。有効な実験がない場合、API 呼び出しは無視されます。
基になっている libcollector.so API 関数の有無をチェックするマクロを含む、libcollector.h を取り込む。

この方法は、メインの実行可能ファイル内で使用する場合と、プログラムの起動と同時にデータ収集を開始する場合にのみ有効です。dbx を使用してプロセスに接続する場合や、プロセスが dlopen する共有ライブラリ内で使用した場合は、必ずしも機能しません。この方法は、下位互換性を維持する目的で提供されており、ほかの目的での使用は推奨されません。

注 –
どんな言語を使用している場合も、プログラムを -lcollector とリンクしないでください。リンクした場合、コレクタが予期しない動作をすることがあります。

Fortran インタフェース

Fortran API の libfcollector.h ファイルには、ライブラリに対する Fortran インタフェースが定義されています。このライブラリを使用するには、アプリケーションを -lcollectorAPI にリンクする必要があります。このライブラリには、下位互換性を維持するため、-lfcollector というもう 1 つの名前も用意されています。動的関数とスレッドによる呼び出しの一時停止と再開を除けば、Fortran API は C/C++ API と同じ機能を提供します。

Fortran の場合、API 関数を使用するには、次の文を挿入します。

include "libfcollector.h"

注 –

どんな言語を使用している場合も、プログラムを -lcollector とリンクしないでください。リンクした場合、コレクタが予期しない動作をすることがあります。

Java インタフェース

次の文を使用して、CollectorAPI クラスをインポートし、Java API にアクセスできます。ただし、アプリケーションは / installation_directory/lib/collector.jar (ここで、installation-directory は Sun Studio ソフトウェアがインストールされているディレクトリ) を指すクラスパスがある状態で呼び出される必要があります。

import com.sun.forte.st.collector.CollectorAPI;

Java CollectorAPI メソッドは、次のように定義されます。

CollectorAPI.sample(String name)
CollectorAPI.pause()
CollectorAPI.resume()
CollectorAPI.threadPause(Thread thread)
CollectorAPI.threadResume(Thread thread)
CollectorAPI.terminate()

Java API には、動的関数 API 以外の C および C++ API と同じ関数が含まれています。

C インクルードファイルの libcollector.h には、データが収集されていないときには実際の API 関数の呼び出しを迂回するマクロが入っています。この場合、関数は動的に読み込まれません。ただし、一部の環境ではうまく機能しないことがあるため、これらのマクロを使用するのは危険です。collectorAPI.h はマクロを使用していないため、このファイルを利用する方が安全です。このファイルでは、関数が直接参照されます。

Fortran API サブルーチンはパフォーマンスデータが収集されているときには C API 関数を呼び出し、そうでないときには復帰します。チェック処理のオーバーヘッドは非常に小さいので、プログラムのパフォーマンスにはあまり影響がないはずです。

パフォーマンスデータを収集するには、この章で後述するように、コレクタを使用してプログラムを実行する必要があります。API 関数への呼び出しを挿入することによって、データ収集が有効になることはありません。

マルチスレッドプログラムで API 関数を使用する場合には、これらの関数が 1 つのスレッドによってのみ呼び出されるようにする必要があります。collector_thread_pause() および collector_thread_resume() 以外は、API 関数が行うアクションの対象はプロセスであって、個々のスレッドではありません。各スレッドが API 関数を呼び出すと、記録されたデータが期待したものにならない可能性があります。たとえば、あるスレッドが collector_pause() や collector_terminate_expt() を呼び出したときに、ほかのスレッドがまだプログラム内のそのポイントに達していない場合、すべてのスレッドについて収集が一時停止または停止され、この API 呼び出しの前にコードを実行していたスレッドのデータが失われる可能性があります。データ収集を個々のスレッドレベルで制御するには、collector_thread_pause() 関数と collector_thread_resume() 関数を使用します。これらの関数の使用方法として、1 つのマスタースレッドで、それ自体を含むすべてのスレッドのすべての呼び出しを行う方法と、各スレッドで自身のみの呼び出しを行う方法があります。その他の使用方法では、結果が予測できないものになる可能性があります。