マニュアルページ libcollector.3




名前

     libcollector - パフォーマンスツール「コレクタ」用ライブラ リ
     の API


形式 -- C および C++ API

     #include "collectorAPI.h"
     ld ... -lcollectorAPI
     C コンパイルの場合、libcollectorAPI.so の検索場所を指定す る
     に は、 -L  <lib-path> および -R <lib-path> も追加してくださ
     い。C++ および Fortran コンパイルの場合、-L および -R は必要
     ありません。
             または、
     #include "libcollector.h"  (Solaris システム上のみでの 旧 リ
     リースとの互換性確保のため)

     void collector_sample(char *name);
     void collector_pause(void);
     void collector_resume(void);
     void collector_thread_pause(pthread_t tid);
     void collector_thread_resume(pthread_t tid);
     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);

       注  :       関  数   collector_thread_pause()   お  よ  び
           collector_thread_resume() は、Linux システムでは利用で
           きません。


形式 -- 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++ イ ン タ フェー ス に ア ク セ ス す る に は、
     collectorAPI.h  を イ ン クルードして -lcollectorAPI (配下の
     libcollector.so API 関数の存在をチェックする実際の関数を含む
     ) にリンクする方法と、libcollector.h (配下の libcollector.so
     API 関数の存在をチェックするマクロを含む) をインクルードする
     方法があります。

     1 つ目の方法では、API ライブラリへのリンクが必要ですが、あら
     ゆる状況下で機能するようになります。ただし、実行するシステム
     に API ライブラリ (libcollectorAPI.so) をインストールする 必
     要があります。

     2 つ目の方法では、主要な実行ファイルにのみ有効で、データコレ
     クションがプログラムの起動と同時にデータコレクションが起動し
     た場合にのみ機能します。必ずしも、dbx がプロセスに接続するた
     め に 使用される場合に機能するわけではなく、また、プロセスに
     よって dlopen が行われた共有ライブラリ内から使用される場合に
     機能するわけでもありません。これは、Solaris システム上で旧リ
     リースとの互換性を確保するために提供されています。

     いずれの場合も、実験が収集されている場合にのみ呼び出しが機能
     します。

     Fortran API libfcollector.h ファイルは、ライブラリへの  For-
     tran  インタフェースを定義します。このライブラリを使用するに
     は、アプリケーションが -lfcollector にリンクされていなければ
     な り ません。(旧リリースとの互換性を確保するために、-lfcol-
     lector ライブラリの別名が用意されています。) Fortran API  に
     は、動的関数およびスレッドの停止、再開の機能を除いて、C およ
     び C++ API と同じ機能があります。

     Java(TM) API ファイルは、Java コードからアクセス可能なメソッ
     ドを定義します。アプリケーションは、次のファイルを指すクラス
     パスを使用して起動する必要があります。
          <installation-directory>/lib/collector.jar
     <installation-directory> には、Sun Studio がインストールされ
     ているディレクトリを指定します。

     Java API を -Xbootclasspath で読み込まれるクラスでアクセス可
     能にするには、
          <installation-directory>/lib/collector.jar
     を -Xbootclasspath 引数に付加し、
          <installation-directory>/lib
     を sun.boot.library.path に追加します。

     Java API は、動的関数呼び出しを除いて、Fortran API と同じ 関
     数 を 備 え て い ま す。 JVM  か ら 呼 び出される動的関数や
     JIT(HotSpot) を使用してコンパイルしたコードは Java API を 使
     用せず、C++ API を使用します。

     パフォーマンスツールに付属しているコンパイラ以外のコンパイラ
     で、コンパイルやリンクを行う場合は、インクルードファイルとラ
     イブラリ (必要な場合) へのパスを指定する必要があります。

     C および C++ でコンパイルする場合
          -I<installation-directory>/prod/include/cc
     Fortran でコンパイルする場合
          -I<installation-directory>/prod/include/f95

     リンクする場合 (C/C++/Fortran)
          -R<installation-directory>/lib         -L<installation-
          directory>/lib (v8 または x86 アプリケーション)
     または
          -R<installation-directory>/lib/v9      -L<installation-
          directory>/lib/v9 (v9 アプリケーション)

     この 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++ 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() は、コレクタに、指定されたアドレスの
     動 的 関数がロードされていないことを知らせるために使用されま
     す。


属性

          ____________________________________________________________
         |       属性タイプ            |       属性値                |
         |_____________________________|_____________________________|
         | 安定レベル                  | 安定                        |
         |_____________________________|_____________________________|



関連項目

     collect(1)collector(1)er_print(1)、およびマニュア ル