マニュアルページ libcollector.3
名前
libcollector - Forte パフォーマンスツール「コレクタ」用ラ イ
ブラリの API
形式 -- C and C++ API
#include "libcollector.h"
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);
void collector_func_load(char *name, char *alias,
char *sourcename, void *vaddr, int size,
int lntsize, Lineno *lntable);
void collector_func_unload(void *vaddr);
void collector_module_load(char *modulename, void *vaddr);
void collector_module_unload(void *vaddr);
形式 -- Fortran API
include "libfcollector.h"
collector_sample(string)
character*(*) string
collector_pause()
collector_resume()
collector_terminate_expt()
形式 -- Java(TM) API
import com.sun.forte.st.collector.CollectorAPI
CollectorAPI.sample(String name);
CollectorAPI.pause();
CollectorAPI.resume();
CollectorAPI.threadPause(Thread thread);
CollectorAPI.threadResume(Thread thread);
CollectorAPI.terminate();
機能説明
パフォーマンスデータの収集に使用される共 有 オ ブ ジェ ク ト
libcollector.so は、 コレクタが有効であれば、通常は collect
コマンドまたは dbx により、LD_PRELOAD を使用して読み込まれま
す。-lcollector には、プログラムをリンクしないでください。
C および C++ libcollector.h ファイルで定義された API (Appli-
cation Programming Interface）には、関数の存在をチェックする
マクロが含まれています。関数がアドレス空間にない場合は、呼び
出しが無視されます。つまり、ライブラリが存在しなくても実行可
能ファイルは正常に実行されます。ライブラリが存在する場合、実
行 可 能 ファイルは API 関数を呼び出します。ただしこの場合、
collect コマンドから、または dbx により、データを記録する た
め収集を有効にして API を起動する必要があります。
Fortran API libfcollector.h ファイルは、ライブラリへのインタ
フェー ス を定義します。このライブラリを使用するには、アプリ
ケーションが -lfcollector にリンクされていなければなり ま せ
ん。 Fortran API に は、動的関数および動的モジュールインタ
フェースを除いて、C および C++ API と同じ機能があります。
Java(TM) API ファイルは、Java コードからアクセス可能なメソッ
ドを定義します。アプリケーションは、以下のファイルを指すクラ
スパスを使用して起動する必要があります。
<installation-directory>/lib/collector.jar
<installation-directory> には、Sun ONE Studio がインストール
されているディレクトリを指定します。
Java API は、動的関数 API を除いて、Fortran API と同じ関数を
備えています。JVM から呼び出される動的関数や JIT(HotSpot) を
使用してコンパイルしたコードは Java API を使用せず、通 常 の
C++ API を使用します。
この API は、マルチスレッド環境で安全に使用することができ ま
す。 すべての関数の実装は libcollector.so ファイルに収められ
ており、どの関数も、ターゲットプロセス内のルーチンへのコール
バック (libc.so、libthread.so ファイル内の関数のコールバック
を除く) を行いません。
実験の制御
C、C++、Fortran APIは、実験中に標本収集ポイントを記 録 し た
り、実験中にイベント固有のデータの記録を停止、開始したり、実
験を終了する関数を備えています。実験は、collect コマンドを使
用するか、dbx でコレクタを有効にして作成する必要があります。
collector_sample() 関数は、呼び出されると、標本収集ポイン ト
を記録し、渡された文字列を使用して標本にラベルを付けます。実
行中の実験が存在しない場合には、呼び出しは無視されます。ラベ
ルを付ける際には、現在使用されているラベルを使用することはで
きません。
標本収集ポイントでは、個々のスレッドのデータではなく、プロセ
ス の データが収集されます。マルチスレッドアプリケーションで
は、標本の記録中に collector_sample() 関数が呼び出された場合
でも、その標本のみが書き込まれます。
collector_pause() 関数は、実験へのイベント固有のデータの書き
込 み を停止します。この動作は、すべてのスレッドに適用されま
す。実験がすでに終了しているか、実行中の実験が存在しないか、
データの書き込みがすでに取り消されている場合は、この関数への
呼び出しは無視されます。
collector_resume() 関数は、停止している実験へのイベント固 有
のデータの書き込みを再開します。この動作は、すべてのスレッド
に適用されます。実験がすでに終了しているか、実行中の実験が存
在しないか、データの書き込みがすでに行われている場合は、この
関数への呼び出しは無視されます。
マルチスレッドアプリケーションでは、collector_resume() へ の
呼 び出しと同時に行われる collector_pause への呼び出しは、実
験ログファイルに書き込まれる記録状態についての誤った情報を生
成する原因となることがあります。
collector_thread_pause() 関数は、特定のスレッドからイベン ト
固有のデータを実験に書き込む動作を停止します。実験がすでに終
了しているか、実行中の実験が存在しないか、スレッドからのデー
タの書き込みがすでに取り消されている場合は、この関数への呼び
出しは無視されます。この関数の引数は、Solaris[tm] 環境 の ス
レッドの場合は thr_self(3THR) によって、POSIX スレッドの場合
は pthread_self(3THR) によって返される POSIX スレッド ID で
す。
collector_thread_resume() 関数は、特定のスレッドからイベント
固有のデータを実験に書き込む動作を再開します。実験がすでに終
了しているか、実行中の実験が存在しないか、スレッドからのデー
タの書き込みがすでに開始されている場合は、この関数への呼び出
しは無視されます。この関数の引数は、Solaris 環境のスレッドの
場 合 は thr_self(3THR) に よっ て、POSIX スレッドの場合は
pthread_self(3THR) によって返される POSIX スレッド ID です。
大域的な停止または再開の設定とスレッドの停止または再開の設定
はお互いに無関係です。大域的な設定またはスレッドの設定が「停
止」である場合、そのスレッドからのデータの書き込みは行われま
せん。大域的な設定とスレッドの設定がどちらも「再開」である場
合、スレッドからのデータの書き込みが行われます。すべて の ス
レッドの初期設定は「再開」です。
スレッドの停止、再開の機能は、1 つのマスタスレッドを使用して
マスタスレッドを含むすべてのスレッドの呼び出しを行うか、各ス
レッドに自分自身のみの呼び出しを行わせることによって使用しま
す。他の方法を使用すると、予測できない結果が生じる可能性があ
ります。
collector_terminate_expt() 関数は、データ収集中の実験を終 了
します。データの収集は行われなくなりますが、プログラムの実行
は正常に継続します。実験がすでに終了しているか、実行中の実験
が存在しない場合は、この関数への呼び出しは無視されます。
C または C++ プログラムからのインタフェースを使用するに は、
API ルーチンを呼び出す関数に、関連するインクルード文のみを挿
入する必要があります。Fortran プログラムからのインタフェース
を使用するには、-lfcollector にリンクする必要があります。
動的関数
C および C++ AIP には、動的に生成される関数についての情報 を
コレクタに渡すために使用される関数セットが含まれます。
collector_func_load() は、動的に生成される関数についての情報
を、実験ファイルに記録する目的でコレクタに渡すために使用され
ます (Java(TM) HotSpot 仮想マシンは、多少異なる非公共イン タ
フェースを使用します)。
name は、動的に構築される関数の名前を指定します。こ の 名 前
は、パフォーマンスアナライザの関数タブに使用される名前です。
この名前は、通常の関数名の取り決めに従う必要はありませんし、
組み込み空白文字や組み込み引用文字を使用できます。
alias は、関数の記述に使用される任意の文字列です。NULL を 指
定することもできます。alias はいかなる解釈もされず、組み込み
空白文字を含めることもでき、アナライザの要約タブに表示されま
す。alias を使用して、関数が何かを示したり、関数が動的に構築
された理由を示すことができます。
sourcename は、関数が構築された元のソースファイルへのパス を
指定します。NULL を指定することもできます。
vaddr は、関数がロードされたアドレスです。
size は、関数のバイト単位のサイズです。
lntsize は、行番号テーブル内のエントリ数のカウントです。行番
号情報が与えられないと、lntsize はゼロになります。
lntable は、lntsize エントリを含むテーブルです。各エントリは
1 組の整数です。最初の整数はオフセットで、2 番目のエントリは
行番号です。あるエントリのオフセットと次のエントリに指定され
るオフセット間のすべての命令は、最初のエントリに指定される行
番号に属します。オフセットは数値の昇順でなければなりま せ ん
が、 行 番号の順序は任意です。lntable が NULL の場合、関数の
ソースリストは使用不可ですが、逆アセンブリリストは使用可能で
す。
collector_func_unload() は、コレクタに、指定されたアドレスの
動 的 関数がロードされていないことを知らせるために使用されま
す。
動的モジュール
C および C++ API には、動的に読み込まれたモジュールについ て
の情報をコレクタに渡す関数セットがあります。
collector_module_load() は、モジュール (*.o) がターゲット に
よってアドレス空間に読み込まれたことをコレクタに知らせるため
に使用されます。モジュールが読み込まれると、モジュールの関数
とそのソースおよび行番号のマップが決定されます。
collector_module_unload() は、前に読み込まれたモジュールが読
み込み解除されたことをコレクタに知らせるために使用されます。
属性
____________________________________________________________
| 属性タイプ | 属性値 |
|_____________________________|_____________________________|
| 安定レベル | 安定 |
|_____________________________|_____________________________|
関連項目
collect(1)、 collector(1)、 er_print(1)、およびマニュアル
『プログラムのパフォーマンス解析』