#include "collectorAPI.h" ld ... -lcollectorAPI (C コンパイルの場合、lib- collectorAPI.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); [deprecated] void collector_thread_resume(pthread_t tid); [deprecated] 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 システムでは使用できず非推奨になりました。今後のリリースですべてのシステムから削除されます。
include "libfcollector.h" collector_sample(string) character*(*) string collector_pause() collector_resume() collector_terminate_expt()
import com.sun.forte.st.collector.CollectorAPI CollectorAPI.sample(String name); CollectorAPI.pause(); CollectorAPI.resume(); CollectorAPI.threadPause(Thread thread); [deprecated] CollectorAPI.threadResume(Thread thread); [deprecated] CollectorAPI.terminate();
共有オブジェクト libcollector.so は、パフォーマンスデータの収集に使用され、コレクタが有効になっているときに、通常は collect コマンドまたは dbx により LD_PRELOAD を使用してロードされます。-lcollector にはプログラムをリンクさせないでください。
C および C++ インタフェースにアクセスするには、collectorAPI.h をインクルードし、-lcollectorAPI (ここには、基となる libcollector.so API 関数の有無を確認する実際の関数が含まれます) とリンクする方法と、libcollector.h (ここには、基となる libcollector.so API 関数の有無を確認するマクロが含まれます) をインクルードする方法の 2 つがあります。
最初の方法は、API ライブラリとのリンクを必要とし、あらゆる状況下で機能しますが、実行しているシステムに API ライブラリ (libcollectorAPI.so) をインストールすることが必要になります。
2 番目の方法は、主要な実行可能ファイルで使用する場合と、プログラムの起動と同時にデータコレクションが起動した場合に機能します。プロセスへのアタッチに dbx が使用されている場合や、プロセスによって dlopen でロードされた共有ライブラリ内から使用される場合に必ずしも機能するわけではありません。これは、Solaris システムでのみ下位互換性を確保するために用意されています。
いずれの方法でも、呼び出しの効果が生じるのは、実験が収集されている場合に限られます。
Fortran API libfcollector.h ファイルは、ライブラリへの Fortran インタフェースを定義します。このライブラリを使用するには、アプリケーションを -lcollectorAPI にリンクする必要があります。このライブラリには、下位互換性を維持するため、-lfcollector というもう 1 つの名前も用意されています。動的関数とスレッドによる呼び出しの一時停止と再開を除けば、Fortran API は C/C++ API と同じ機能を提供します。
Java(TM) API ファイルは、Java コードからアクセス可能なメソッドを定義します。アプリケーションは、次のファイルを示すクラスパスを使用して呼び出す必要があります。
<installation-directory>/lib/collector.jar
ここで、<installation-directory> は、Solaris Studio リリースをインストールしたディレクトリです。
-Xbootclasspath でロードされたクラスに Java API からアクセスできるようにするには、
<installation-directory>/lib/collector.jar
を -Xbootclasspath 引数に付加し、
<installation-directory>/lib
を sun.boot.library.path プロパティーに追加する必要があります。
Java API には、動的関数呼び出しを除いて、C/C++ API と同じ関数が含まれています。JVM からの動的関数も、JIT(HotSpot) でコンパイルしたコードも、Java API を使用せず、C++ API を使用します。
パフォーマンスツールと同じリリースに付属しているコンパイラ以外のコンパイラでコンパイルやリンクを行う場合は、インクルードファイルとライブラリ (必要な場合) へのパスを指定する必要があります。
C および C++ でコンパイルする場合
-I<installation-directory>/prod/include/cc
Fortran でコンパイルする場合
-I<installation-directory>/prod/include/f95
どちらの場合でも、v8 または x86 アプリケーションでは、次とリンクします
-R<installation-directory>/lib -L<installation-directory>/lib
また、v9 アプリケーションでは
-R<installation-directory>/lib/v9 -L<installation-directory>/lib/v9
コレクタ API は、マルチスレッド環境で安全に使用できます。これらの関数の実装はすべて libcollector.so ファイルに完全に収められており、どの関数も、ターゲットプロセス内のルーチンへのコールバックを行いません (libc.so および libthread.so ファイル内の関数へのコールバックは除く)。
C、C++、および Fortran API には、実験で標本ポイントを記録したり、実験でのイベント固有のデータの記録を停止および開始したり、実験を終了したりするために使用できる一連の関数が含まれています。実験は、collect コマンドを使用するか、dbx でコレクタを有効にして作成する必要があります。
collector_sample() 関数は、呼び出されたときに標本ポイントを記録し、API 関数に渡された文字列でその標本にラベルを付けます。実行中の実験がない場合、呼び出しは無視されます。ラベルは現在使用されていません。
標本ポイントに含まれるデータは、プロセスに関するものであり、個々のスレッドに関するものではありません。マルチスレッドアプリケーションの場合、collector_sample() API 関数は、標本の記録中に別の呼び出しが行われても、1 つの標本だけが書き込まれるようにします。
collector_pause() 関数は、実験へのイベント固有のデータの書き込みをオフにします。このアクションはすべてのスレッドに適用されます。実験がすでに終了しているか、実行中の実験がないか、データの書き込みがすでにオフになっている場合、呼び出しは無視されます。
collector_resume() 関数は、実験へのイベント固有のデータの書き込みをオンにします。このアクションはすべてのスレッドに適用されます。実験がすでに終了しているか、実行中の実験がないか、データの書き込みがすでにオンになっている場合、呼び出しは無視されます。
マルチスレッドアプリケーションでは、collector_pause() が collector_resume() の呼び出しと同時に呼び出された場合、実験ログファイルに書き込まれる記録ステータスに関する情報が誤ったものになる可能性があります。
collector_thread_pause() 関数は、特定のスレッドから実験へのイベント固有のデータの書き込みをオフにします。実験がすでに終了しているか、実行中の実験がないか、そのスレッドのデータの書き込みがすでにオフになっている場合、呼び出しは無視されます。関数の引数は、Solaris[tm] オペレーティング環境スレッドの場合は thr_self (3C) によって、POSIX スレッドの場合は pthread_self (3C) によって返される POSIX スレッド ID です。collector_thread_pause() は非推奨になり、今後のリリースで削除されます。インタフェースを使用するターゲットで記録された警告が実験で記録されます。
collector_thread_resume() 関数は、特定のスレッドから実験へのイベント固有のデータの書き込みをオンにします。実験がすでに終了しているか、実行中の実験がないか、そのスレッドのデータの書き込みがすでにオンになっている場合、呼び出しは無視されます。この関数の引数は、Solaris オペレーティング環境スレッドの場合は thr_self() によって、POSIX スレッドの場合は pthread_self() によって返される POSIX スレッド ID です。collector_thread_resume() は非推奨になり、今後のリリースで削除されます。インタフェースを使用するターゲットで記録された警告が実験で記録されます。
collector_terminate_expt() 関数は、データが収集されている実験を終了します。それ以後のデータは収集されませんが、プログラムの実行は正常に続行されます。実験がすでに終了しているか、実行中の実験がない場合、呼び出しは無視されます。
C および C++ API には、動的に生成される関数に関する情報をコレクタに提供するために使用される一連の関数が含まれます。
collector_func_load() は、動的に生成される関数に関する情報を、実験で記録する目的でコレクタに渡すために使用されます。(Java(TM) HotSpot 仮想マシンは若干異なる非公共インタフェースを使用します)。
name は、動的に構築される関数の名前を指定します。この名前は、パフォーマンスアナライザの「関数」タブで使用される名前になります。この名前は関数の通常の命名規則に従う必要はなく、空白文字や引用符を含めることができます。
alias は、関数の説明に使用する任意の文字列です。NULL も使用できます。この文字列が解釈の対象となることはありません。空白文字を含めることができます。アナライザの「サマリー」タブに表示されます。何の関数であるか、またはなぜ関数が動的に構築されたかを示すために使用できます。
sourcename は、関数の構築元であるソースファイルのパスを指定します。NULL も使用できます。
vaddr は、関数がロードされたアドレスを指定します。
size は、バイト数による関数のサイズです。
lntsize は、行番号テーブルのエントリの数を示すカウントです。行番号情報がない場合には、ゼロとなります。
lntable は、lntsize エントリを含むテーブルです。各エントリは 1 組の整数です。第 1 整数はオフセット、第 2 整数は行番号です。あるエントリのオフセットと次のエントリのオフセットとの間の命令はすべて、最初のエントリの行番号に対応します。オフセットは数値の昇順にする必要がありますが、行番号の順序は任意です。lntable が NULL の場合、関数のソースリストは利用できませんが、逆アセンブリリストは利用できます。
collector_func_unload() は、指定されたアドレスにある動的関数がアンロードされたことをコレクタに通知するために使用されます。
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Stability Level | Stable |
|_____________________________|_____________________________|
collect (1) , collector (1) 、 er_print (1)
パフォーマンスアナライザマニュアル