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 (Application 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)、 およびマニュアル
『プログラムのパフォーマンス解析』