JavaTM 仮想マシン・プロファイラインタフェース (JVMPI)

このドキュメントでは、Java 2 SDK, Standard Edition の Java 仮想マシン・プロファイラインタフェース (JVMPI) について説明します。 このインタフェースは、Sun の Java 仮想マシン* の実装とともに機能するプロファイラを開発する目的で、ツールベンダーのために提供されています。

注: このインタフェースは、Java 2 SDK での試験的な機能です。 JVMPI は、現時点では標準のプロファイル用インタフェースではありません。 このドキュメントは、Java 仮想マシンでのプロファイリング用フックをすぐに必要としているツールベンダーを対象として提供されています。 JVMPI は、カスタマおよびツールベンダーからのフィードバックに基づいて今後も改良されます。 コメントは、jvmpi@eng.sun.com までお寄せください。

注: このインタフェースは、Classic VM、Java 2 Client VM (Java HotSpotTM テクノロジによって実装される)、および Java HotSpot Server VM 2.0 に実装されています。 Java Hotspot テクノロジに特有の注意事項がある場合は、その旨記載されます。

目次

1. 概要

JVMPI は、Java 仮想マシンとインプロセスのプロファイラエージェントとの間の、双方向の関数呼び出しインタフェースです。 仮想マシンは、プロファイラエージェントに、ヒープ割り当て、スレッドの開始などに対応するさまざまなイベントを通知します。 一方、プロファイラエージェントは、JVMPI を使ってより多くの情報を得るための制御や要求を発行します。 たとえば、プロファイラエージェントは、プロファイラのフロントエンドの必要に基づいて、特定のイベント通知をオンまたはオフにすることができます。

プロファイラフロントエンドは、必ずしもプロファイラエージェントと同じプロセスで実行される必要はありません。 プロファイラフロントエンドは、同じマシン上の別のプロセスに置いたり、ネットワーク経由で接続されたリモートマシン上のプロセスに置いたりできます。 JVMPI は、標準のワイヤプロトコルを指定しません。 ツールベンダーは、個々のプロファイラフロントエンドの必要に応じて、ワイヤプロトコルを設計できます。

JVMPI を基にしたプロファイリングツールを使用することにより、多量のメモリが割り当てられている場所、CPU に負荷のかかるホットスポット、不必要なオブジェクトの保持、モニターの競合など、パフォーマンス全般の分析に役立つ多くの情報を取得できます。

JVMPI では、部分的なプロファイリングもサポートされています。つまり、ユーザは、仮想マシンの動作中の特定期間を指定してアプリケーションのプロファイリングを実行したり、特定の種類のプロファイリング情報を選んで取得したりできます。

現在のバージョンの JVMPI では、1 つの仮想マシンにつき 1 つのエージェントだけをサポートできます。

1.1. 初期設定

ユーザは、Java 仮想マシンに対するコマンド行オプションを使って、プロファイラエージェントの名前と、プロファイラエージェントに対するオプションを指定できます。 たとえば、ユーザが次のように指定したとします。 
     java -Xrunmyprofiler:heapdump=on,file=log.txt ToBeProfiledClass
VM は、Java の次のライブラリディレクトリから myprofiler というプロファイラエージェントライブラリを探します。 Java ライブラリディレクトリにライブラリが見つからない場合は、それぞれのプラットフォームの通常のライブラリ検索方法に従って、ライブラリの検索が続けられます。 VM は、プロファイラエージェントライブラリをロードし、次のようなエントリポイントを探します。 
jint JNICALL JVM_OnLoad(JavaVM *jvm, char *options, void *reserved);
VM は、JavaVM インスタンスへのポインタを第 1 引数、文字列 「heapdump=on,file=log.txt」 を第 2 引数に指定して、JVM_OnLoad 関数を呼び出します。 JVM_OnLoad への第 3 引数は予約されており、null に設定されます。

成功した場合、JVM_OnLoad 関数は JNI_OK を返さなければなりません。 なんらかの理由で JVM_OnLoad 関数の実行が失敗した場合、その関数は JNI_ERR を返さなければなりません。

1.2. 関数呼び出しインタフェース

プロファイラエージェントは、JavaVM ポインタに対して GetEnv を呼び出すことによって、関数呼び出しインタフェースを取得できます。 たとえば、次のコードは、Java 2 SDK に実装されたバージョンの JVMPI インタフェースを取得します。 
JVMPI_Interface *jvmpi_interface;

JNIEXPORT jint JNICALL JVM_OnLoad(JavaVM *jvm, char *options, void *reserved)
{
    int res = (*jvm)->GetEnv(jvm, (void **)&jvmpi_interface, JVMPI_VERSION_1);
    if (res < 0) {
        return JNI_ERR;
    }
    ... /* use entries in jvmpi_interface */
}
JVMPI_Interface 構造体は、プロファイラエージェントと VM の間の関数呼び出しインタフェースを定義します。 
/* interface functions */
typedef struct {
    jint version;   /* JVMPI version */
    
    /* ------interface implemented by the profiler------ */

    void (*NotifyEvent)(JVMPI_Event *event);
  
    /* ------interface implemented by the JVM------ */
        
    jint (*EnableEvent)(jint event_type, void *arg);
    jint (*DisableEvent)(jint event_type, void *arg);
    jint (*RequestEvent)(jint event_type, void *arg);
  
    void (*GetCallTrace)(JVMPI_CallTrace *trace, jint depth);

    void (*ProfilerExit)(jint);

    JVMPI_RawMonitor (*RawMonitorCreate)(char *lock_name);
    void (*RawMonitorEnter)(JVMPI_RawMonitor lock_id);
    void (*RawMonitorExit)(JVMPI_RawMonitor lock_id);
    void (*RawMonitorWait)(JVMPI_RawMonitor lock_id, jlong ms);
    void (*RawMonitorNotifyAll)(JVMPI_RawMonitor lock_id);
    void (*RawMonitorDestroy)(JVMPI_RawMonitor lock_id);


    jlong (*GetCurrentThreadCpuTime)(void);
    void (*SuspendThread)(JNIEnv *env);
    void (*ResumeThread)(JNIEnv *env);
    jint (*GetThreadStatus)(JNIEnv *env);
    jboolean (*ThreadHasRun)(JNIEnv *env);
    jint (*CreateSystemThread)(char *name, jint priority, void (*f)(void *));
    void (*SetThreadLocalStorage)(JNIEnv *env_id, void *ptr);
    void * (*GetThreadLocalStorage)(JNIEnv *env_id);

    void (*DisableGC)(void);
    void (*EnableGC)(void);
    void (*RunGC)(void);

    jobjectID (*GetThreadObject)(JNIEnv *env);
    jobjectID (*GetMethodClass)(jmethodID mid);

    /* JNI handle <-> object ID conversions; implemented only in Hotspot VM*/

    jobject   (*jobjectID2jobject)(jobjectID jid);
    jobjectID (*jobject2jobjectID)(jobject   j);

} JVMPI_Interface;
GetEnv 関数は JVMPI_Interface へのポインタを返します。JVMPI_Interface の version フィールドは、GetEnv の呼び出しで引き渡すバージョン番号引数と互換性がある、JVMPI のバージョンを示します。 ただし、version フィールドの値は、GetEnv の呼び出しで引き渡すバージョン引数と常に同じであるとは限らないので注意してください。

GetEnv によって返される JVMPI_Interface には、NotifyEvent 以外のすべての関数が設定されています。 プロファイラエージェントは、JVM_OnLoad から復帰する前に、NotifyEvent 関数のポインタを設定する必要があります。

Hotspot に関する注: 新しい 2 つの関数 jobjectID2jobject および jobject2jobjectID は、Hotspot VM にだけ追加されました。

1.3. イベントの通知

VM は、JVMPI_Event データ構造体を引数として NotifyEvent を呼び出すことにより、イベントを送信します。 サポートされるイベントは次のとおりです。

JVMPI_Event 構造体には、イベント型、現在のスレッドの JNIEnv ポインタ、およびその他のイベント特有の情報が格納されます。 イベント特有の情報は、イベント特有の構造体の共用体として表現されます。 「イベント」の項では、イベント特有の構造体すべてについて説明します。 ここでは、クラスロードおよびクラスアンロードのイベントに特有の構造体を示します。 

typedef struct {
    jint event_type;                  /* event_type */
    JNIEnv *env_id;                   /* env where this event occurred */
  
    union {
        struct {
	    char *class_name;         /* class name */
	    char *source_name;        /* name of source file */
	    jint num_interfaces;      /* number of interfaces implemented */
  	    jint num_methods;         /* number of methods in the class */
	    JVMPI_Method *methods;    /* methods */
	    jint num_static_fields;   /* number of static fields */
	    JVMPI_Field *statics;     /* static fields */
	    jint num_instance_fields; /* number of instance fields */
	    JVMPI_Field *instances;   /* instance fields */
	    jobjectID class_id;       /* id of the class object */
	} class_load;

        struct {
	    jobjectID class_id;       /* id of the class object */
	} class_unload;

        ... /* Refer to the section on JVMPI events for a full listing */
    } u;
} JVMPI_Event;

1.4. JVMPI の ID

JVMPI では、Java 仮想マシン内のエンティティが、さまざまな種類の ID で参照されます。 スレッド、クラス、メソッド、オブジェクト、ヒープ領域、および JNI グローバル参照には、すべて一意の ID があります。

各 ID には、定義イベントおよび定義取り消しイベントがあります。 定義イベントは、ID に関連した情報を提供します。 たとえば、スレッド ID の定義イベントには、そのスレッドの名前や、その他のエントリが含まれます。

ID は、定義取り消しイベントが着信するまで有効です。 定義取り消しイベントは ID を無効にし、その後その ID の値は別の種類の ID として再利用が可能になります。 たとえば、スレッドの終了後に、そのスレッド ID の値がメソッド ID として再定義されることがあります。

ID データ型定義イベント 定義取り消しイベント
スレッド ID JNIEnv *スレッドの開始 スレッドの終了
オブジェクト ID jobjectIDオブジェクトの割り当て オブジェクトの解放、オブジェクトの移動、および領域の削除
クラス ID jobjectIDクラスのロード クラスのアンロードおよびオブジェクトの移動
メソッド ID jmethodID定義しているクラスのロード 定義しているクラスのアンロード
領域 ID jint領域の新規作成 領域の削除
JNI グローバル参照 ID jobjectグローバル参照の割り当て グローバル参照の解放

定義イベントがプロファイラの初期化中に有効にされている場合、エンティティの作成の通知は、そのエンティティがほかの JVMPI イベントで使われるより前に、定義イベントを介してプロファイラエージェントに届くことが保証されています。

定義イベントが有効にされていない場合、プロファイラエージェントは未知の ID を受け取る可能性があります。 この場合、プロファイラエージェントは、RequestEvent 呼び出しを発行することによって、対応する定義イベントの送信を必要に応じて要求できます。

オブジェクトを表す ID の型は、jobjectID です。 クラスは、対応する java.lang.Class オブジェクトのオブジェクト ID によって表されます。 このため、クラス ID の型も jobjectID です。

jobjectID は、オブジェクトの割り当てイベントによって定義され、そのオブジェクトが割り当てられた領域について次の定義取り消しイベントの 1 つが着信するまでは、その領域内で有効です。

オブジェクトの解放イベントまたは領域の削除イベントによってオブジェクト ID が無効にされた場合、そのオブジェクトはガベージコレクトされたと言います。

通常、プロファイラエージェントは、jobjectID とオブジェクト ID の内部表現とのマッピングを保持し、JVMPI のオブジェクト ID に対する定義イベントおよび定義取り消しイベントに対応してそのマッピングを更新します。

ガベージコレクション (GC) 中にオブジェクト ID が無効にされることがあるので、VM は、jobjectID エントリを含むすべてのイベントを、GC を無効にした状態で発行します。 また、プロファイリングエージェントは、jobjectID データ型を直接操作しているときは、GC を無効にする必要があります。 GC を無効にしないと、エージェントコードで jobjectID が操作されている間に、GC によってその jobjectID が無効にされる可能性があります。 プロファイラエージェントは、jobjectID の引数をとる JVMPI 関数、または jobjectID の結果を返す JVMPI 関数を呼び出す場合には、必ず GC を無効にする必要があります。 ただし、GC がすでに無効にされているイベントハンドラ内で関数を呼び出す場合、プロファイラエージェントは明示的に再度 GC を無効にする必要はありません。

スレッドは、JNIEnv インタフェースポインタか、対応する java.lang.Thread オブジェクトのオブジェクト ID によって識別が可能です。 JNIEnv ポインタは、スレッド開始イベントからスレッド終了イベントまで有効で、スレッドが有効な間はずっと一定です。 これに対し、java.lang.Thread のオブジェクト ID は、スレッドの終了後も、ガベージコレクトされるまで有効なままです。 プロファイラエージェントは、GetThreadObject 関数を呼び出すことによって、JNIEnv ポインタを、対応するスレッドオブジェクト ID に変換できます。

1.5. スレッドとロックの問題

JVMPI は、Java 仮想マシンと同じプロセス内で実行されているプロファイラエージェントによって使用されます。 エージェントを記述するプログラマは、データの破壊とデッドロックを防ぐために、スレッドとロックの扱いに注意する必要があります。

イベントは、生成されたスレッドと同じスレッド内で送信されます。 たとえば、クラスロードイベントは、クラスがロードされるスレッドと同じスレッド内で送信されます。 複数のイベントが異なるスレッド内で同時に着信する可能性があります。 このため、複数のスレッドが同じデータ構造体を同時に更新することによるデータの破壊を防ぐために、エージェントプログラムは、必要な同期を提供しなければなりません。

頻繁に発生する特定のイベント (メソッドに入る、メソッドから出るなど) の同期が、プログラムの実行に過大なオーバーヘッドを課す場合があります。 このため、エージェントは、JVMPI がサポートするスレッドローカルな記憶領域を利用して、グローバルロックを獲得せずにプロファイリングデータを記録し、特定の周期でスレッドローカルなデータをグローバルプロファイルにマージすることができます。 JVMPI は、ポインタサイズのスレッドローカル記憶領域をエージェントに提供します。 以下に、プロファイラエージェントがこの機能を利用する方法を示す簡単な例を紹介します。 ここでは、各スレッド内で実行されたメソッド数をカウントするプロファイラエージェントを記述する必要があるとします。 このエージェントは、スレッドの開始イベント、メソッドに入るイベント、およびスレッドの終了イベント用のイベントハンドラをインストールします。 

/* thread start event handler
 * sets up the storage for thread-local method invocation counter
 */
void ThreadStartHandler(JNIEnv *thread_id)
{
    int *p_ctr = (int *)malloc(sizeof(int));
    CALL(SetThreadLocalStorage)(thread_id, p_ctr);
}

/* method enter event handler
 * increments thread local method invocation counter
 */
void MethodEntryHandler(jmethodID method_id, JNIEnv *thread_id)
{
    int *p_ctr = (int *)CALL(GetThreadLocalStorage)(thread_id);
    (*p_ctr)++;
}

/* thread end handler
 * prints the number of methods executed
 */
void ThreadEndHandler(JNIEnv *thread_id)
{
    int *p_ctr = (int *)CALL(GetThreadLocalStorage)(thread_id);
    fprintf(stdout, "Thread %x executed %d methods¥n",
	    thread_id, (*p_ctr));
    free(p_ctr);
}

次の JVMPI 関数は、関数の実行中に、同じスレッド内でイベントの通知を同期的に送信する可能性があります。

RequestEvent 関数は、プロファイラエージェントによって明示的に要求された JVMPI イベントを提供します。 CreateSystemThread 関数は、スレッドオブジェクトの割り当てイベント、およびスレッドの開始イベントを発行します。 RunGC 関数は、GC 関連のいくつかのイベントを生成します。

プロファイリングエージェントが Java 仮想マシンにロードされる際のプロセスは、GC が有効なマルチスレッドモード、GC が無効なマルチスレッドモード、およびスレッド中断モードのいずれかが可能です。 発行される JVMPI イベントは、モードによって異なります。 特定の JVMPI 関数は、プロセスを、あるモードから別のモードに変更します。

デッドロックを避けるため、プロファイラエージェントは、次のガイドラインに従う必要があります。

1.6. プロファイラエージェントとフロントエンドの間のデータ通信

JVMPI は、プロファイラエージェントが仮想マシンと通信するための下位レベルの機構を提供しています。 この機構の目的は、フロントエンドの要件に応じてデータを提示する柔軟性をプロファイラエージェントに与え、仮想マシン側で実行される処理を最小限に抑えることです。 このため、JVMPI は、プロファイリングエージェントとフロントエンドの間のワイヤプロトコルを指定していません。 その代わりに、ツールベンダーが、各フロントエンドの要件に応じて独自のプロファイリングエージェントを設計します。

プロファイラエージェントとフロントエンドを異なるマシンに配置できるようにするには、ワイヤプロトコルを設計するときに、次の点について考慮する必要があります。

たとえば、Java 2 SDK に付属している HPROF プロファイラエージェントでは、すべての ID のサイズが最初のレコードとして送信され、整数および浮動小数点のデータには標準ネットワークのバイト順が使用されます。

2. インタフェース関数

jint (*CreateSystemThread)(char *name, jint priority, void (*f)(void *));

プロファイラエージェントによって呼び出され、Java 仮想マシン内にデーモンスレッドを作成します。

プロファイラエージェントからこの関数を呼び出すのを、JVM が JVMPI_EVENT_INIT_DONE を通知したあと、かつ、システムが GC の有効なマルチスレッドモードのときだけにすると安全です。

引数:

name - スレッドの名前
priority - スレッドの優先順位。次の値を指定できる
JVMPI_NORMAL_PRIORITY
JVMPI_MAXIMUM_PRIORITY
JVMPI_MINIMUM_PRIORITY
f - スレッドによって実行される関数

戻り値:

JNI_OK - 成功
JNI_ERR - 失敗

jint (*DisableEvent)(jint event_type, void *arg);

プロファイラエージェントによって呼び出され、特定の型のイベント通知が無効にされます。 プロファイラエージェントは、event_type のほかに、特定のイベント型に特有の補足情報を提供する引数を渡すことも可能です。

VM の起動時には、すべてのイベントが無効にされています。 イベントは、一度有効にされると、明示的に無効にされるまで有効のままです。

この関数は、event_type が JVMPI_EVENT_HEAP_DUMP、JVMPI_EVENT_MONITOR_DUMP、または JVMPI_EVENT_OBJECT_DUMP の場合には、JVMPI_NOT_AVAILABLE を返します。

引数:

event_type - イベントの型。JVMPI_EVENT_CLASS_LOAD など
arg - イベントに特有の情報

戻り値:

JVMPI_SUCCESS 無効にする操作が成功
JVMPI_FAIL 無効にする操作が失敗
JVMPI_NOT_AVAILABLE 指定された event_type を無効にする操作がサポートされていない

void (*DisableGC)(void);

プロファイラによって呼び出され、EnabledGC が呼び出されるまでガベージコレクションを無効にします。 DisableGC および EnableGC の呼び出しは、入れ子にできます。

jint (*EnableEvent)(jint event_type, void *arg);

プロファイラエージェントによって呼び出され、特定の型のイベント通知を有効にします。 プロファイラエージェントは、event_type のほかに、特定のイベント型に特有の補足情報を提供する引数を渡すことも可能です。

VM の起動時には、すべてのイベントが無効にされています。 イベントは、一度有効にされると、明示的に無効にされるまで有効のままです。

この関数は、event_type が JVMPI_EVENT_HEAP_DUMP、JVMPI_EVENT_MONITOR_DUMP、または JVMPI_EVENT_OBJECT_DUMP の場合には、JVMPI_NOT_AVAILABLE を返します。 プロファイラエージェントがこれらのイベントを要求するには、RequestEvent 関数を使う必要があります。

引数:

event_type - イベントの型。JVMPI_EVENT_CLASS_LOAD など
arg - イベントに特有の引数

戻り値:

JVMPI_SUCCESS 有効にする操作が成功
JVMPI_FAIL 有効にする操作が失敗
JVMPI_NOT_AVAILABLE 指定された event_type を有効にする操作がサポートされていない

void (*EnableGC)(void);

ガベージコレクションを有効にします。 DisableGC および EnableGC の呼び出しは、入れ子にできます。

void (*GetCallTrace)(JVMPI_CallTrace *trace, jint depth);

プロファイラによって呼び出され、指定されたスレッドについて、現在のメソッド呼び出しスタックトレースを取得します。 スレッドは、JVMPI_CallTrace 構造体の env_id フィールドによって識別されます。 プロファイラエージェントは、JVMPI_CallTrace 構造体に、要求されたスタックの深さに十分なメモリを割り当てる必要があります。 VM は、frames バッファおよび num_frames フィールドに情報を入れます。

引数:

trace - VM によって情報が入れられるトレースデータ構造体
depth - 呼び出しスタックトレースの深さ

jlong (*GetCurrentThreadCpuTime)(void);

プロファイラエージェントによって呼び出され、現在のスレッドによって消費された累積 CPU 時間を取得します。

戻り値:

ナノ秒単位の時間

jobjectID (*GetMethodClass)(jmethodID mid);

プロファイラエージェントによって呼び出され、メソッドを定義しているクラスのオブジェクト ID を取得します。

プロファイラは、この関数を呼び出す前に GC を無効にする必要があります。

引数:

mid - メソッド ID

戻り値:

定義しているクラスのオブジェクト ID

void * (*GetThreadLocalStorage)(JNIEnv *env_id);

プロファイラによって呼び出され、JVMPI のスレッドローカルな記憶領域の値を取得します。 JVMPI は、エージェントに対して、スレッドごとのプロファイリング情報を記録するために利用できる、ポインタサイズのスレッドローカルな記憶領域を提供します。

引数:

env_id - スレッドの JNIEnv *

戻り値:

スレッドローカルな記憶領域の値

jobjectID (*GetThreadObject)(JNIEnv *env);

プロファイラエージェントによって呼び出され、JNIEnv ポインタに対応するスレッドオブジェクト ID を取得します。

プロファイラは、この関数を呼び出す前に GC を無効にする必要があります。

引数:

env - - スレッドの JNIEnv ポインタ

戻り値:

スレッドのオブジェクト ID

jint (*GetThreadStatus)(JNIEnv *env);

プロファイラエージェントによって呼び出され、スレッドのステータスを取得します。

JVMPI 関数 SuspendThread および ResumeThread は、GetThreadStatus が返すステータスには影響を与えません。 JVMPI によって中断されたスレッドのステータスは変更されずに残っているため、中断時のステータスが返されます。

引数:

env - スレッドの JNIEnv *

戻り値:

JVMPI_THREAD_RUNNABLE - スレッドは実行可能
JVMPI_THREAD_MONITOR_WAIT - スレッドはモニターを待機している
JVMPI_THREAD_CONDVAR_WAIT - スレッドは条件変数を待機している

スレッドが (java.lang.Thread.suspend によって) 中断されているか、上記のいずれかの状態によって割り込まれているときは、JVMPI_THREAD_SUSPENDED または JVMPI_THREAD_INTERRUPTED ビットがセットされます。

void (*NotifyEvent)(JVMPI_Event *event);

VM によって呼び出され、プロファイリングエージェントにイベントを送信します。 プロファイラエージェントは、EnableEvent を呼び出すことによって関心のあるイベントを登録するか、または RequestEvent を呼び出すことによって特定の型のイベントを要求します。

EnableEvent によってイベントが有効にされた場合は、イベントを生成したスレッドでイベントが送信されます。 RequestEvent によってイベントが要求された場合は、イベントを要求したスレッドでイベントが送信されます。 複数のスレッドが複数のイベントを同時に送信することがあります。

イベント特有の情報に jobjectID が含まれている場合、この関数は、GC が無効な状態で呼び出されます。 GC は、関数からの復帰後に有効になります。

JVMPI_Event 構造体およびイベント特有の情報に割り当てられた領域は、この関数からの復帰後に、仮想マシンによって解放されます。 プロファイラエージェントは、残しておく必要のあるデータを内部バッファにコピーする必要があります。

引数:

event - VM からプロファイリングエージェントに送信される JVMPI イベント

void (*ProfilerExit)(jint err_code);

プロファイラエージェントによって呼び出され、エラーコードに err_code を設定した状態でプロファイラが終了することを VM に通知します。 この関数により、VM も同じ err_code で終了します。

引数:

err_code - 終了コード

JVMPI_RawMonitor (*RawMonitorCreate)(char *lock_name);

プロファイラによって呼び出され、raw モニターを作成します。

raw モニターは、Java モニターと似ています。 しかし、raw モニターは Java オブジェクトに関連付けられていない点が異なります。

プロファイラエージェントが、スレッド中断モードでこの関数を呼び出すことは安全ではありません。それは、この関数が malloc などの任意のシステム関数を呼び出して、内部システムライブラリロックをブロックする可能性があるからです。

raw モニターがアンダースコア (_) で始まる名前で作成された場合は、そのモニターのコンテンションイベントはプロファイラエージェントに送信されません。

引数:

lock_name - raw モニターの名前

戻り値:

raw モニター

void (*RawMonitorDestroy)(JVMPI_RawMonitor lock_id);

プロファイラエージェントによって呼び出され、raw モニターを破棄し、そのモニターに関連付けられているすべてのシステムリソースを解放します。

raw モニターは、Java モニターと似ています。 しかし、raw モニターは Java オブジェクトに関連付けられていない点が異なります。

プロファイラエージェントが、スレッド中断モードでこの関数を呼び出すことは安全ではありません。それは、この関数が free などの任意のシステム関数を呼び出して、内部システムライブラリロックをブロックする可能性があるからです。

引数:

lock_id - 破棄する raw モニター

void (*RawMonitorEnter)(JVMPI_RawMonitor lock_id);

プロファイラエージェントによって呼び出され、raw モニターに入ります。

raw モニターは、Java モニターと似ています。 しかし、raw モニターは Java オブジェクトに関連付けられていない点が異なります。

プロファイラエージェントが、スレッド中断モードでこの関数を呼び出すことは安全ではありません。それは、現在のスレッドが、すでに中断されているスレッドの 1 つによって獲得されている raw モニターをブロックする可能性があるからです。

引数:

lock_id - 入る raw モニター

void (*RawMonitorExit)(JVMPI_RawMonitor lock_id);

プロファイラエージェントによって呼び出され、raw モニターから出ます。

raw モニターは、Java モニターと似ています。 しかし、raw モニターは Java オブジェクトに関連付けられていない点が異なります。

引数:

lock_id - 出る raw モニター

void (*RawMonitorNotifyAll)(JVMPI_RawMonitor lock_id);

プロファイラによって呼び出され、raw モニターを待機しているすべてのスレッドに通知を送ります。

raw モニターは、Java モニターと似ています。 しかし、raw モニターは Java オブジェクトに関連付けられていない点が異なります。

引数:

lock_id - 通知する raw モニター

void (*RawMonitorWait)(JVMPI_RawMonitor lock_id, jlong ms);

プロファイラエージェントによって呼び出され、指定したタイムアウトまでの期間、raw モニターを待機します。 タイムアウト期間に 0 を指定すると、スレッドはずっと待機し続けます。

raw モニターは、Java モニターと似ています。 しかし、raw モニターは Java オブジェクトに関連付けられていない点が異なります。

Hotspot に関する注: RawMonitorWait を実行しているスレッドが、指定された raw モニターを所有していない場合、待機は発生しません。

引数:

lock_id - 待機対象の raw モニター
ms - 待機する時間 (ミリ秒)

jint (*RequestEvent)(jint event_type, void *arg);

プロファイラエージェントによって呼び出され、特定の型のイベントを通知することを要求します。 プロファイラエージェントは、event_type のほかに、特定のイベント型に特有の補足情報を提供する引数を渡すことも可能です。

この関数を呼び出すと、JVMPI_EVENT_HEAP_DUMP、JVMPI_EVENT_MONITOR_DUMP、JVMPI_EVENT_OBJECT_DUMP など、1 回限りのイベントを要求できます。 これらのイベントの通知は、 EnableEvent 関数と DisableEvent 関数では制御できません。

また、この関数を呼び出すと、特定のクラス、スレッド、またはオブジェクトの「定義イベント」を要求できます。 これは、プロファイラエージェントがイベントで受け取った未知のクラス、メソッド、スレッド、またはオブジェクト ID を解釈する必要があるにもかかわらず、対応する定義イベントが無効にされていた、という場合に便利です。

したがって、プロファイラエージェントは、EnableEvent を呼び出して上の 3 つのイベントを非同期的に有効にするか、または RequestEvent を呼び出してこれらのイベントを同期的に要求することができます。 要求されたイベントは、RequestEvent 呼び出しを発行したのと同じスレッドで、RequestEvent 関数から復帰する前に送信されます。

RequestEvent 関数は、上記以外のイベントを要求するためには使用できません。

RequestEvent によって要求されたイベントは、event_type で JVMPI_REQUESTED_EVENT ビットがセットされた状態で着信します。

引数:

event_type - イベントの型。JVMPI_EVENT_CLASS_LOAD など
arg - イベントに特有の引数

戻り値:

JVMPI_SUCCESS 要求が成功
JVMPI_FAIL 要求が失敗
JVMPI_NOT_AVAILABLE 要求された event_type の発行がサポートされていない

void (*ResumeThread)(JNIEnv *env);

プロファイラエージェントによって呼び出され、スレッドを再開します。

java.lang.Thread.suspend メソッドによって中断されたスレッドは、JVMPI の ResumeThread 関数では再開できません。

引数:

env - スレッドの JNIEnv *

void (*RunGC)(void);

プロファイラによって呼び出され、完全なガベージコレクションを強制的に実行します。 この関数は、GC が無効な状態で呼び出してはなりません。

void (*SetThreadLocalStorage)(JNIEnv *env_id, void *ptr);

プロファイラエージェントによって呼び出され、JVMPI のスレッドローカルな記憶領域の値を設定します。 JVMPI は、エージェントに対して、スレッドごとのプロファイリング情報を記録するために利用できる、ポインタサイズのスレッドローカルな記憶領域を提供します。

引数:

env_id - スレッドの JNIEnv *
ptr - スレッドローカルな記憶領域に入力する値

void (*SuspendThread)(JNIEnv *env);

プロファイラエージェントによって呼び出され、スレッドを中断します。 この関数が呼び出されると、システムは、スレッド中断モードに入ります。

JVMPI の SuspendThread 関数によって中断されたスレッドは、java.lang.Thread.resume メソッドでは再開できません。

Java 2 SDK の実装では、この関数は、GC が無効な状態で呼び出す必要があります。 GC は、すべてのスレッドが再開されるまで無効でなければなりません。

引数:

env - スレッドの JNIEnv *

jboolean (*ThreadHasRun)(JNIEnv *env);

プロファイラによって呼び出され、指定された JNIEnv ポインタによって識別されるスレッドが、SuspendThread によって最後に中断されて以降に CPU 時間を消費したかどうかを判定します。 この関数は、スレッドが ResumeThread によって再開されたあと、SuspendThread 関数によって再度中断されたときに呼び出す必要があります。

引数:

env - スレッドの JNIEnv *

戻り値:

JNI_TRUE - スレッドは実行される機会があった
JNI_FALSE - スレッドは実行される機会がなかった

jobject (*jobjectID2jobject)(jobjectID jid);

プロファイラエージェントによって呼び出され、オブジェクト ID を JNI ハンドルに変換します。

この関数は試験用で、JVMPI の最終仕様からは削除されるかもしれません。これを使用した場合の安全性は確保されておらず、プロファイラの信頼性が下がる可能性があります。 冒頭の 注も参照してください。

引数:

jid - 変換対象のオブジェクト ID

戻り値:

JNI ハンドル

Hotspot に関する注: この関数は、Hotspot VM でのみ提供されます。

jobjectID (*jobject2jobjectID)(jobject j);

プロファイラエージェントによって呼び出され、JNI ハンドルをオブジェクト ID に変換します。

この関数は試験用で、JVMPI の最終仕様からは削除されるかもしれません。これを使用した場合の安全性は確保されておらず、プロファイラの信頼性が下がる可能性があります。

引数:

j - JNI ハンドル

戻り値:

オブジェクト ID

Hotspot に関する注: この関数は、Hotspot VM でのみ提供されます。

使用上の注意:

JNI 関数を任意の JVMPI イベントハンドラ内で呼び出すのは危険です。 JVMPI イベントは、仮想マシンが JNI 関数の実行に適していない状態のときに発行される可能性があります。 プロファイラエージェントが JNI 関数を呼び出してもよいのは、マルチスレッドモード (JVMPI 仕様の定義による) のときだけです。しかも、競合状態、デッドロック、および無限の再帰が発生しないように、最大限の注意を払わなければなりません。

jobjectID2jobject および jobject2jobjectID を呼び出してもよいのは、GC が無効なモード (JVMPI 仕様の定義による) のときだけです。そのモードで JNI 関数を呼び出すのは危険です。 したがって、GC が無効なモードで動作しているイベントハンドラ内で jobjectID2jobject を呼び出し、その結果の jobject を JNI 関数を使って処理する、ということは絶対に避けてください。

3. イベント

JVMPI_EVENT_ARENA_DELETE

ヒープ領域が削除される時点で送信されます。

この領域内のすべてのオブジェクトが解放されます。 これらのオブジェクトについて、明示的な JVMPI_EVENT_OBJECT_FREE は送信されません。 プロファイラエージェントは、領域内のオブジェクトの割り当て、および領域へのオブジェクトの出入りを記録することによって、領域内に現在存在するすべてのオブジェクトを推測できます。

このイベントは、スレッド中断モードで発行されます。 プロファイラは、モニターに入ったり、C ヒープから割り当てたり (malloc などによる) する、ブロックする呼び出しを実行してはなりません。

このイベントは常に、JVMPI_EVENT_GC_START イベントと、対応する JVMPI_EVENT_GC_FINISH イベントの間で送信されます。 プロファイラエージェントは、このイベントを処理するのに必要なすべてのロックを、JVMPI_EVENT_GC_START のイベントハンドラ内で獲得する必要があります。 

struct {
    jint arena_id;
} delete_arena;
内容:
arena_id - 削除される領域の ID

JVMPI_EVENT_ARENA_NEW

オブジェクトを割り当てる新しい領域が作成される時点で送信されます。 
struct {
    jint arena_id;
    char *arena_name;
} new_arena;
内容:
arena_id - 領域に与えられた ID
arena_name - 領域の名前

JVMPI_EVENT_CLASS_LOAD

VM にクラスがロードされる時点、またはプロファイラエージェントが RequestEvent を呼び出して JVMPI_EVENT_CLASS_LOAD イベントを要求した時点で送信されます。 後者の場合は、イベント型で JVMPI_REQUESTED_EVENT ビットがセットされます。

このイベントは、GC が無効な状態で発行されます。 GC は、NotifyEvent から復帰したあとに、再度有効になります。 

struct {
    char *class_name;
    char *source_name;
    jint num_interfaces;
    jint num_methods;
    JVMPI_Method *methods;
    jint num_static_fields;
    JVMPI_Field *statics;
    jint num_instance_fields;
    JVMPI_Field *instances;
    jobjectID class_id;
} class_load;

内容:

class_name - ロードされているクラスの名前
source_name - クラスを定義しているソースファイルの名前
num_interfaces - このクラスによって実装されるインタフェースの数
methods - クラス内で定義されたメソッド
num_static_fields - このクラス内で定義された static フィールドの数
statics - このクラス内で定義された static フィールド
num_instance_fields - このクラス内で定義されたインスタンスフィールドの数
instances - このクラス内で定義されたインスタンスフィールド
class_id - クラスのオブジェクト ID

注: クラス ID は、クラスオブジェクトの ID で、JVMPI_EVENT_OBJECT_MOVE の着信時に変更されます。

JVMPI_EVENT_CLASS_LOAD_HOOK

VM がクラスファイルデータを取得したとき、そのクラスのメモリ内部表現を構築する前の時点で送信されます。 プロファイラエージェントは、VM によって送信された既存のクラスファイルデータに、プロファイリングフックを組み込むことができます。

プロファイラは、このイベントで送信されるメモリ割り当て関数のポインタを使って、修正したクラスファイルデータのバッファ用の領域を割り当てる必要があります。新しいクラスファイルデータのバッファを解放する処理は、VM によって実行されるからです。 

struct {
    unsigned char *class_data;
    jint class_data_len;
    unsigned char *new_class_data;
    jint new_class_data_len;
    void * (*malloc_f)(unsigned int);
} class_load_hook;

内容:

class_data - 現在のクラスファイルデータのバッファへのポインタ
class_data_len - 現在のクラスファイルデータのバッファの長さ
new_class_data - 修正されたクラスファイルデータのバッファへのポインタ
new_class_data_len - 新しいクラスファイルデータのバッファの長さ
malloc_f - メモリ割り当て関数へのポインタ

プロファイラエージェントは、NotifyEvent から復帰する前に、修正した新しいクラスファイルデータのバッファを指すように new_class_data を設定し、new_class_data_len にそのバッファの長さを設定する必要があります。 このクラスに修正を加えないことにした場合は、new_class_data と new_class_data_len の両方に、古い値を設定する必要があります。

JVMPI_EVENT_CLASS_UNLOAD

クラスがアンロードされる時点で送信されます。

このイベントは、GC が無効な状態で発行されます。 GC は、NotifyEvent から復帰したあとに、再度有効になります。 

struct {
    jobjectID class_id;
} class_unload;

内容:

class_id - アンロードされるクラス

JVMPI_EVENT_COMPILED_METHOD_LOAD

メソッドがコンパイルされ、メモリ内にロードされる時点で送信されます。 
struct {
    jmethodID method_id;
    void *code_addr;
    jint code_size;
    jint lineno_table_size;
    JVMPI_Lineno *lineno_table;
} compiled_method_load;

内容:

method_id - コンパイルおよびロードされているメソッド
code_addr - コンパイルされたメソッドコードがロードされるアドレス
code_size - コンパイルされたコードのサイズ
lineno_table_size - 行番号テーブルのサイズ
lineno_table - メソッドの先頭からのオフセットをソースファイルの行番号にマッピングするテーブル

JVMPI_EVENT_COMPILED_METHOD_UNLOAD

コンパイルされたメソッドがメモリからアンロードされる時点で送信されます。 
struct {
    jmethodID method_id;
} compiled_method_unload;

内容:

method_id - アンロードされる、コンパイルされたメソッド

JVMPI_EVENT_DATA_DUMP_REQUEST

VM によって送信され、プロファイラエージェントにデータをダンプするよう要求します。 これは単に示唆しているだけであり、プロファイラエージェントはこのイベントに必ずしも反応する必要はありません。 これは、ユーザからのコマンド行シグナルを処理する場合に便利です。 たとえば、Java 2 SDK では、Win32 上では Ctrl+Break キー、Solaris 上では Ctrl+¥ キーにより、VM がこのイベントをプロファイラエージェントに送信します。

イベント特有の情報はありません。

JVMPI_EVENT_DATA_RESET_REQUEST

VM によって送信され、プロファイラエージェントにデータをリセットするように要求します。 これは単に示唆しているだけであり、プロファイラエージェントはこのイベントに必ずしも反応する必要はありません。 これは、ユーザからのコマンド行シグナルを処理する場合に便利です。 たとえば、Java 2 SDK では、Win32 上では Ctrl+Break キー、Solaris 上では Ctrl+¥ キーにより、VM がこのイベントをプロファイラエージェントに送信します。

イベント特有の情報はありません。

JVMPI_EVENT_GC_FINISH

GC の終了時に送信されます。 プロファイラエージェントは、オブジェクトの解放イベント、オブジェクトの移動イベント、および領域の削除イベントを処理するために GC の開始通知の処理中に獲得したすべてのロックを、このイベントを処理する際に解放できます。 このイベントのあとに、システムはマルチスレッドモードに戻ります。

イベント特有のデータには、Java ヒープ統計が入っています。 

struct {
    jlong used_objects;
    jlong used_object_space;
    jlong total_object_space;
} gc_info;
内容:
used_objects - ヒープ上で使われていたオブジェクトの数
used_object_space - オブジェクトによって使用されていた領域の量 (バイト単位)
total_object_space - オブジェクト領域の合計量 (バイト単位)

JVMPI_EVENT_GC_START

GC を開始しようとしている時点で送信されます。 このイベントのあとに、システムはスレッド中断モードに入ります。 デッドロックを避けるため、プロファイラエージェントは、オブジェクトの解放イベント、オブジェクトの移動イベント、および領域の削除イベントを処理するのに必要なすべてのロックを、このイベントのイベントハンドラ内で獲得する必要があります。

イベント特有の情報はありません。

JVMPI_EVENT_HEAP_DUMP

RequestEvent 関数によって要求されたときに送信されます。 プロファイラエージェントは、RequestEvent に第 2 引数として JVMPI_HeapDumpArg 構造体を渡し、その heap_dump_level フィールドにダンプレベルを設定することによって、ダンプする情報のレベルを指定できます。

ダンプレベルとしては、次の値のどれかを指定できます。

null 値が渡された場合、ダンプレベルは JVMPI_DUMP_LEVEL_2 に設定されます。

このイベントは、GC が無効な状態で発行されます。 GC は、NotifyEvent から復帰したあとに、再度有効になります。

イベント特有のデータには、Java ヒープ内のすべてのライブオブジェクトのスナップショットが入っています。 

struct {
    int dump_level;
    char *begin;
    char *end;
    jint num_traces;
    JVMPI_CallTrace *traces;
} heap_dump;
内容:
dump_level RequestEvent で指定されたダンプレベル
begin - ヒープのダンプの先頭
end - ヒープのダンプの末尾
num_traces - GC のルートが存在するスタックトレースの数。JVMPI_DUMP_LEVEL_0 の場合は 0
traces - GC のルートが存在するスタックトレース

begin と end の間に置かれるヒープダンプの形式は、要求された情報のレベルによって異なります。 この形式の詳細については、「ダンプの形式」の項を参照してください。

JVMPI_EVENT_JNI_GLOBALREF_ALLOC

JNI グローバル参照が作成される時点で送信されます。 イベント特有のデータには、JNI グローバル参照と、対応するオブジェクト ID が入っています。

このイベントは、GC が無効な状態で発行されます。 GC は、NotifyEvent から復帰したあとに、再度有効になります。 

struct {
    jobjectID obj_id;
    jobject ref_id;
} jni_globalref_alloc;
内容:
obj_id - グローバル参照が参照するオブジェクト ID
ref_id - JNI グローバル参照

JVMPI_EVENT_JNI_GLOBALREF_FREE

JNI グローバル参照が削除される時点で送信されます。 イベント特有のデータには、削除される JNI グローバル参照が入っています。 
struct {
    jobject ref_id;
} jni_globalref_free;
内容:
ref_id - JNI グローバル参照

JVMPI_EVENT_JNI_WEAK_GLOBALREF_ALLOC

JNI グローバル弱参照が作成される時点で送信されます。 イベント特有のデータには、JNI グローバル弱参照と、対応するオブジェクト ID が入っています。

このイベントは、GC が無効な状態で発行されます。 GC は、NotifyEvent から復帰したあとに、再度有効になります。 

struct {
    jobjectID obj_id;
    jobject ref_id;
} jni_globalref_alloc;
内容:
obj_id - グローバル弱参照が参照するオブジェクト ID
ref_id - JNI グローバル弱参照

JVMPI_EVENT_JNI_WEAK_GLOBALREF_FREE

JNI グローバル弱参照が削除される時点で送信されます。 イベント特有のデータには、削除される JNI グローバル弱参照が入っています。 
struct {
    jobject ref_id;
} jni_globalref_free;
内容:
ref_id - JNI グローバル弱参照

JVMPI_EVENT_JVM_INIT_DONE

VM の初期化が実行されるときに VM によって送信されます。 CreateSystemThread を呼び出して安全なのは、このイベントが通知されたあとだけです。

イベント特有のデータはありません。

JVMPI_EVENT_JVM_SHUT_DOWN

VM がシャットダウンしているときに VM によって送信されます。 プロファイラは通常、プロファイリングデータを保存することによって、このイベントに応答します。

イベント特有のデータはありません。

JVMPI_EVENT_METHOD_ENTRY

メソッドに入る時点で送信されます。 JVMPI_EVENT_METHOD_ENTRY2 とは違って、このイベントは、メソッドの呼び出し対象であるターゲットオブジェクトの jobjectID を送信しません。 
struct {
    jmethodID method_id;
} method;

内容:

method_id - 入ろうとしているメソッド

JVMPI_EVENT_METHOD_ENTRY2

メソッドに入る時点で送信されます。 メソッドがインスタンスメソッドの場合は、イベントと一緒にターゲットオブジェクトの jobjectID が送信されます。 メソッドが static メソッドの場合は、このイベントの obj_id フィールドが null に設定されます。

このイベントは、GC が無効な状態で発行されます。 GC は、NotifyEvent から復帰したあとに、再度有効になります。 

struct {
    jmethodID method_id;
    jobjectID obj_id;
} method_entry2;

内容:

method_id - 入ろうとしているメソッド
obj_id - ターゲットオブジェクト。static メソッドの場合は null

JVMPI_EVENT_METHOD_EXIT

メソッドから出る時点で送信されます。 メソッドから出るとは、通常に終了する場合か、または処理されない例外が発生した場合を指します。 
struct {
    jmethodID method_id;
} method;

内容:

method_id - 出ようとしているメソッド

JVMPI_EVENT_MONITOR_CONTENDED_ENTER

スレッドが Java モニターに入ろうとしたとき、そのモニターがすでに別のスレッドによって獲得されている場合に送信されます。

このイベントは、GC が無効な状態で発行されます。 GC は、NotifyEvent から復帰したあとに、再度有効になります。 

struct {
    jobjectID object;
} monitor;
内容:
object - モニターに関連付けられたオブジェクト ID

JVMPI_EVENT_MONITOR_CONTENDED_ENTERED

別のスレッドが Java モニターを解放するのを待ったあとで、スレッドがその Java モニターに入るときに送信されます。

このイベントは、GC が無効な状態で発行されます。 GC は、NotifyEvent から復帰したあとに、再度有効になります。 

struct {
    jobjectID object;
} monitor;
内容:
object - モニターに関連付けられたオブジェクト ID

JVMPI_EVENT_MONITOR_CONTENDED_EXIT

スレッドが Java モニターから出たとき、別のスレッドが同じモニターを獲得するために待機している場合に送信されます。

このイベントは、GC が無効な状態で発行されます。 GC は、NotifyEvent から復帰したあとに、再度有効になります。 

struct {
    jobjectID object;
} monitor;
内容:
object - モニターに関連付けられたオブジェクト ID

JVMPI_EVENT_MONITOR_DUMP

RequestEvent 関数によって要求されたときに送信されます。

イベント特有のデータには、VM 内のすべてのスレッドおよびモニターのスナップショットが入っています。

このイベントは、GC が無効な状態で発行されます。 GC は、NotifyEvent から復帰したあとに、再度有効になります。 

struct {
    char *begin;
    char *end;
    jint num_traces;
    JVMPI_CallTrace *traces;
    jint *threads_status;
} monitor_dump;
内容:
begin - モニターのダンプバッファの先頭
end - ダンプバッファの末尾
num_traces - スレッドトレースの数
traces - すべてのスレッドのトレース
thread_status - すべてのスレッドのステータス

モニターのダンプバッファ形式の詳細については、「ダンプの形式」の項を参照してください。

JVMPI_EVENT_MONITOR_WAIT

スレッドがオブジェクトを待機しようとしているときに送信されます。

このイベントは、GC が無効な状態で発行されます。 GC は、NotifyEvent から復帰したあとに、再度有効になります。 

struct {
    jobjectID object;
    jlong timeout;
} monitor_wait;
内容:
object - 現在のスレッドが待機しようとしているオブジェクトの ID
(null は、スレッドが Thread.sleep であることを示す)
timeout - スレッドが待機する時間 (単位はミリ秒)。 0 は、ずっと待機し続けることを示す

JVMPI_EVENT_MONITOR_WAITED

スレッドがオブジェクトの待機を終了するときに送信されます。

このイベントは、GC が無効な状態で発行されます。 GC は、NotifyEvent から復帰したあとに、再度有効になります。 

struct {
    jobjectID object;
    jlong timeout;
} monitor_wait;
内容:
object - 現在のスレッドが待機しているオブジェクト ID
(null は、スレッドが Thread.sleep であることを示す)
timeout - スレッドが待機した時間 (単位はミリ秒)

JVMPI_EVENT_OBJECT_ALLOC

オブジェクトが割り当てられる時点か、またはプロファイラエージェントが RequestEvent を呼び出して JVMPI_EVENT_OBJECT_ALLOC イベントを要求した時点で送信されます。 後者の場合は、イベント型で JVMPI_REQUESTED_EVENT ビットがセットされます。

このイベントは、GC が無効な状態で発行されます。 GC は、NotifyEvent から復帰したあとに、再度有効になります。 

struct {
    jint arena_id;
    jobjectID class_id;
    jint is_array;
    jint size;
    jobjectID obj_id;
} obj_alloc;

内容:

arena_id - 割り当てられる領域
class_id - このオブジェクトが属するクラス、または is_array が JVMPI_CLASS の場合は、配列要素のクラス
is_array - 値は次のいずれか
JVMPI_NORMAL_OBJECT 通常のオブジェクト
JVMPI_CLASS オブジェクトの配列
JVMPI_BOOLEAN boolean 型の配列
JVMPI_BYTE byte 型の配列
JVMPI_CHAR char 型の配列
JVMPI_SHORT short 型の配列
JVMPI_INT int 型の配列
JVMPI_LONG long 型の配列
JVMPI_FLOAT float 型の配列
JVMPI_DOUBLE double 型の配列
size - サイズ (単位はバイト)
obj_id - 一意のオブジェクト ID

JVMPI_EVENT_OBJECT_DUMP

RequestEvent 関数によって要求されたときに送信されます。 ダンプが要求されているオブジェクトの jobjectID は、第 2 引数として RequestEvent に渡されているはずです。

プロファイラエージェントは、GC が無効な状態でこのイベントを要求する必要があります。

イベント特有のデータには、オブジェクトのスナップショットが入っています。 

struct {
    jint data_len;
    char *data;
} object_dump;
内容:
data_len - オブジェクトのダンプバッファの長さ
data - オブジェクトダンプの先頭

オブジェクトダンプバッファの形式の詳細については、「ダンプの形式」の項を参照してください。

JVMPI_EVENT_OBJECT_FREE

オブジェクトが解放される時点で送信されます。

このイベントは、スレッド中断モードで発行されます。 プロファイラは、モニターに入ったり、C ヒープから割り当てたり (malloc などによる) する、ブロックする呼び出しを実行してはなりません。

このイベントは常に、JVMPI_EVENT_GC_START イベントと、対応する JVMPI_EVENT_GC_FINISH イベントの間で送信されます。 プロファイラエージェントは、このイベントを処理するのに必要なすべてのロックを、JVMPI_EVENT_GC_START のイベントハンドラ内で獲得する必要があります。 

struct {
    jobjectID obj_id;
} obj_free;

内容:

obj_id - 解放されるオブジェクト

JVMPI_EVENT_OBJECT_MOVE

ヒープ内でオブジェクトが移動される時点で送信されます。

このイベントは、スレッド中断モードで発行されます。 プロファイラは、モニターに入ったり、C ヒープから割り当てたり (malloc などによる) する、ブロックする呼び出しを実行してはなりません。

このイベントは常に、JVMPI_EVENT_GC_START イベントと、対応する JVMPI_EVENT_GC_FINISH イベントの間で送信されます。 プロファイラエージェントは、このイベントを処理するのに必要なすべてのロックを、JVMPI_EVENT_GC_START のイベントハンドラ内で獲得する必要があります。 

 struct {
     jint arena_id;
     jobjectID obj_id;
     jint new_arena_id;
     jobjectID new_obj_id;
} obj_move;

内容:

arena_id - 現在の領域
obj_id - 現在のオブジェクト ID
new_arena_id - 新しい領域
new_obj_id - 新しいオブジェクト ID

JVMPI_EVENT_RAW_MONITOR_CONTENDED_ENTER

スレッドが raw モニターに入ろうとしたとき、そのモニターがすでに別のスレッドによって獲得されている場合に送信されます。 
struct {
    char *name;
    JVMPI_RawMonitor id;
} raw_monitor;
内容:
name - raw モニターの名前
id - raw モニターの ID

JVMPI_EVENT_RAW_MONITOR_CONTENDED_ENTERED

別のスレッドが raw モニターを解放するのを待ったあとで、スレッドがその raw モニターに入るときに送信されます。 
struct {
    char *name;
    JVMPI_RawMonitor id;
} raw_monitor;
内容:
name - raw モニターの名前
id - raw モニターの ID

JVMPI_EVENT_RAW_MONITOR_CONTENDED_EXIT

スレッドが raw モニターから出たとき、別のスレッドが同じモニターを獲得するために待機している場合に送信されます。 
struct {
    char *name;
    JVMPI_RawMonitor id;
} raw_monitor;
内容:
name - raw モニターの名前
id - raw モニターの ID

JVMPI_EVENT_THREAD_END

VM 内のスレッドが終了する時点で送信されます。

このイベント通知で受け取る JVMPI_Event の env_id フィールドは、終了したスレッドの JNIEnv インタフェースポインタです。

JVMPI_EVENT_THREAD_START

VM 内でスレッドが開始される時点か、またはプロファイラエージェントが RequestEvent を呼び出して JVMPI_EVENT_THREAD_START イベントを要求した時点で送信されます。 後者の場合は、イベント型で JVMPI_REQUESTED_EVENT ビットがセットされます。

このイベントは、GC が無効な状態で発行されます。 GC は、NotifyEvent から復帰したあとに、再度有効になります。 

struct {
    char *thread_name;
    char *group_name;
    char *parent_name;
    jobjectID thread_id;
    JNIEnv *thread_env_id;
} thread_start;

内容:

thread_name - 開始されるスレッドの名前
group_name - スレッドが属するグループ
parent_name - 親の名前
thread_id - スレッドのオブジェクト ID
thread_env_id - - スレッドの JNIEnv *
スレッドには、JNIEnv ポインタとスレッドオブジェクト ID が関連付けられています。JVMPI は、JNIEnv ポインタをスレッド ID として使います。

JVMPI_EVENT_INSTRUCTION_START

各命令 (バイトコード操作) がインタプリタによって発行される時点で送信されます。

このイベントは、コンパイルされたコードではなく、インタプリタによってのみ発行されます。 

struct {
    jmethodID method_id;
    jint      offset;	
    union {
	    struct {
	        jboolean is_true;
	    } if_info;
	    struct {
	        jint key;
	        jint low;	
	        jint hi;	
	    } tableswitch_info;
	    struct {
	        jint     chosen_pair_index; /* actually chosen pair index (0-based) */
	        jboolean is_default;        /* whether default branch is taken      */
	    } lookupswitch_info;
    } u;
} instruction;

内容:

method_id - 命令を実行するメソッドの ID
offset - メソッドのバイトコード内での命令のオフセット
is_true - if バイトコードで true または false の分岐がとられるかどうかを示す
key tableswitch 内でインデックスとして使われる最上位のスタック値
low tableswitch 内のインデックスの最小値
hi tableswitch 内のインデックスの最大値
chosen_pair_index lookupswitch 内で実際に選択されたペアの、ゼロから始まるインデックス
is_default lookupswitch 内でデフォルトの分岐がとられるかどうかを示す

Hotspot に関する注: -XX:+EnableJVMPIInstructionStartEvent フラグを使って実行してください。そうしないと、このイベントは送信されません。

4. ダンプの形式

4.1. ダンプ形式の説明で使われているサイズと型

u1: 1 バイト
u2: 2 バイト
u4: 4 バイト
u8: 8 バイト
ty: u1 で、次の値をとる:
JVMPI_NORMAL_OBJECT   通常のオブジェクト
JVMPI_CLASS オブジェクトの配列
JVMPI_BOOLEAN boolean 型の配列
JVMPI_BYTE byte 型の配列
JVMPI_CHAR char 型の配列
JVMPI_SHORT short 型の配列
JVMPI_INT int 型の配列
JVMPI_LONG long 型の配列
JVMPI_FLOAT float 型の配列
JVMPI_DOUBLE double 型の配列
vl: 値。正確なサイズは値の型によって異なる
boolean、byte u1
short、char u2
int、float u4
long、double u8
JNIEnv *、jobjectID、および JVMPI_RawMonitor sizeof(void *)

4.2. ヒープのダンプ形式

ヒープのダンプ形式は、要求された情報のレベルによって異なります。

JVMPI_DUMP_LEVEL_0:
ダンプは、次の形式の一連のレコードで構成されます。

ty オブジェクトの型
jobjectID オブジェクト

JVMPI_DUMP_LEVEL_1:
ダンプの形式は、JVMPI_DUMP_LEVEL_2 のダンプの形式と基本的に同じですが、オブジェクトインスタンスダンプのプリミティブフィールド、クラスダンプのプリミティブ static フィールド、およびプリミティブ配列要素の値はダンプに出力されません。

JVMPI_DUMP_LEVEL_2:
ダンプは、一連のレコードで構成され、各レコードには、8 ビットのレコード型と、そのあとに各レコード型に固有の形式のデータが含まれています。

レコード型 レコードデータ
JVMPI_GC_ROOT_UNKNOWN
(未知のルート)
jobjectID オブジェクト
JVMPI_GC_ROOT_JNI_GLOBAL
(JNI グローバル参照ルート)
jobjectID オブジェクト
jobject JNI グローバル参照
JVMPI_GC_ROOT_JNI_LOCAL
(JNI ローカル参照)
jobjectID オブジェクト
JNIEnv * スレッド
u4 スタックトレース内のフレーム番号 (空の場合は -1)
JVMPI_GC_ROOT_JAVA_FRAME
(Java スタックフレーム)
jobjectID オブジェクト
JNIEnv * スレッド
u4 スタックトレース内のフレーム番号 (空の場合は -1)
JVMPI_GC_ROOT_NATIVE_STACK
(ネイティブスタック)
jobjectID オブジェクト
JNIEnv * スレッド
JVMPI_GC_ROOT_STICKY_CLASS
(システムクラス)
jobjectID クラスオブジェクト
JVMPI_GC_ROOT_THREAD_BLOCK
(スレッドブロックからの参照)
jobjectID スレッドオブジェクト
JNIEnv * スレッド
JVMPI_GC_ROOT_MONITOR_USED
(入られているモニター)
jobjectID オブジェクト
JVMPI_GC_CLASS_DUMP
(クラスオブジェクトのダンプ)
jobjectID クラス
jobjectID スーパー
jobjectID クラスローダ
jobjectID 署名者
jobjectID 保護ドメイン
jobjectID クラス名 (String オブジェクト。null のこともある)
void * 予約済み
u4 インスタンスのサイズ (バイト単位)
[jobjectID]* インタフェース
u2 定数プールのサイズ
[u2, 定数プールのインデックス,
 ty, 型,
 vl]* 値
[vl]* static フィールドの値
JVMPI_GC_INSTANCE_DUMP
(通常のオブジェクトのダンプ)
jobjectID オブジェクト
jobjectID クラス
u4 あとに続くバイト数
[vl]* インスタンスフィールドの値 (クラス、スーパー、スーパーのスーパー... の順)
JVMPI_GC_OBJ_ARRAY_DUMP
(オブジェクト配列のダンプ)
jobjectID 配列オブジェクト
u4 要素の数
jobjectID 要素のクラス ID (Java 2 SDK では null のこともある)
[jobjectID]* 要素
JVMPI_GC_PRIM_ARRAY_DUMP
(プリミティブ配列のダンプ)
jobjectID 配列オブジェクト
u4 要素の数
ty 要素の型
[vl]* 要素

4.3. オブジェクトのダンプ形式

ダンプのバッファは、8 ビットのレコード型と、そのあとにレコード型固有のデータが続くという形式のレコードで構成されます。 レコード型は、次のどれかになります。 各レコード型のデータの形式は、「ヒープのダンプ形式」で説明した形式と同じです。 情報のレベルは、JVMPI_DUMP_LEVEL_2 と同じで、オブジェクトインスタンスダンプのプリミティブフィールド、クラスダンプのプリミティブ static フィールド、およびプリミティブ配列要素の値がすべて含まれます。

4.4. モニターのダンプ形式

ダンプは、一連のレコードで構成され、各レコードには、8 ビットのレコード型と、そのあとに各レコード型固有の形式のデータが含まれています。
レコード型 レコードデータ
JVMPI_MONITOR_JAVA
(Java モニター)
jobjectID オブジェクト ID
JNIEnv * 所有するスレッド
u4 エントリカウント
u4 入るのを待っているスレッド数
[JNIEnv *]* 入るのを待っているスレッド
u4 通知を待っているスレッド数
[JNIEnv *]* 通知を待っているスレッド
JVMPI_MONITOR_RAW
(raw モニター)
char * raw モニター名
JVMPI_RawMonitor raw モニター ID
JNIEnv * 所有するスレッド
u4 エントリカウント
u4 入るのを待っているスレッド数
[JNIEnv *]* 入るのを待っているスレッド
u4 通知を待っているスレッド数
[JNIEnv *]* 通知を待っているスレッド

5. データ型

文字は、UTF-8 エンコーディングを使って符号化されます。Java 仮想マシンの仕様を参照してください。

jobjectID

オブジェクト ID を表す隠されたポインタ 

struct _jobjectID;
typedef struct _jobjectID * jobjectID;

JVMPI_CallFrame

実行されているメソッド 

typedef struct {
    jint lineno;
    jmethodID method_id;
} JVMPI_CallFrame;
フィールド:
line number - ソースファイル内の行番号
method_id - 実行されているメソッド

JVMPI_CallTrace

メソッド実行の呼び出しトレース 
typedef struct {
    JNIEnv *env_id;
    jint num_frames;
    JVMPI_CallFrame *frames;
} JVMPI_CallTrace;
フィールド:
env_id - このトレースを実行したスレッドの ID
num_frames - トレース内のフレーム数
frames - このトレースを構成する JVMPI_CallFrame。 呼び出される側の後に、呼び出し側が続く

JVMPI_Field

クラス内で定義されたフィールド 
typedef struct {
    char *field_name;
    char *field_signature;
} JVMPI_Field;
フィールド:
field_name - フィールドの名前
field_signature - フィールドのシグニチャー

JVMPI_HeapDumpArg

要求するヒープダンプについての補足情報 

typedef struct {
    jint heap_dump_level;
} JVMPI_HeapDumpArg;
フィールド:
heap_dump_level - ヒープのダンプ情報のレベル。次の値を指定できる
JVMPI_DUMP_LEVEL_0
JVMPI_DUMP_LEVEL_1
JVMPI_DUMP_LEVEL_2

JVMPI_Lineno

ソース行番号と、コンパイルされたメソッドの先頭からのオフセットとの間のマッピング 
typedef struct {
    jint offset;
    jint lineno;
} JVMPI_Lineno;
フィールド:
offset - メソッドの先頭からのオフセット
lineno - ソースファイルの先頭からの行番号

JVMPI_Method

クラス内で定義されたメソッド 
typedef struct {
    char *method_name;
    char *method_signature;
    jint start_lineno;
    jint end_lineno;
    jmethodID method_id;
} JVMPI_Method;
フィールド:
method_name - メソッドの名前
method_signature - メソッドのシグニチャー
start_lineno - ソースファイルの開始行番号
end_lineno - ソースファイルの終了行番号
method_id - このメソッドに与えられた ID

JVMPI_RawMonitor

raw モニターを表す隠されたポインタ 

struct _JVMPI_RawMonitor;
typedef struct _JVMPI_RawMonitor * JVMPI_RawMonitor;

6. Java 2 SDK, v1.2 からの変更について

6.1. 新機能

6.2. 制限

6.3. v1.3 での変更点

7. HPROF プロファイラエージェント

7.1. 概要

HPROF は、Java 2 SDK に付属している簡単なプロファイラエージェントです。 JVMPI と対話し、ファイルまたはソケットに ASCII またはバイナリ形式でプロファイリング情報を出力する DLL です。 この情報は、プロファイラのフロントエンドツールによってさらに処理できます。

HPROF では、CPU 使用率、ヒープ割り当て統計、およびモニター競合のプロファイルを表示できます。 また、ヒープ全体のダンプ、および Java 仮想マシン内のすべてのモニターとスレッドの状態を報告することもできます。

HPROF は、次のコマンドで呼び出されます。 

java -Xrunhprof ToBeProfiledClass
要求されたプロファイリングの種類に応じて、HPROF は、関連する JVMPI イベントを送り返すように仮想マシンに指示し、イベントデータを処理してプロファイリング情報を生成します。 たとえば、次のコマンドでは、ヒープ割り当てプロファイルを取得できます。 
java -Xrunhprof:heap=sites ToBeProfiledClass
以下のリストは、HPROF に渡すことができるすべてのオプションの一覧です。 
HPROF の使用法: -Xrunhprof[:help]|[オプション=値, ...]

オプション名前と値     説明                            デフォルト
--------------------   ------------------------        -----------
heap=dump|sites|all    ヒープのプロファイリング        all
cpu=samples|times|old  CPU 使用率                      off
monitor=y|n            モニターの競合                  n
format=a|b             ASCII またはバイナリ形式        a
file=name              データをファイルに書き出す      java.hprof (ASCII の場合は .txt)
net=host:port          データをソケット経由で送信      ファイルに書き出す
depth=size             スタックトレースの深さ          4
cutoff=value           出力のカットオフポイント        0.0001
lineno=y|n             トレースに行番号を出力するか    y
thread=y|n             トレースにスレッドを出力するか  n
doe=y|n                終了時にダンプするか            y

例: java -Xrunhprof:cpu=samples,file=log.txt,depth=3 FooClass

デフォルトでは、ヒープのプロファイリング情報 (サイトおよびダンプ) は、java.hprof.txt (ASCII) に出力されます。

7.2. ヒープ割り当てプロファイル

次の出力は、いくつかの入力ファイルに対して Java コンパイラ (javac) を実行して生成された、ヒープ割り当てプロファイルの例です。 プロファイラ出力の一部を示します。 

使用したコマンド: javac -J-Xrunhprof:heap=sites foo.java ...
SITES BEGIN (ordered by live bytes) Wed Oct  7 11:38:10 1998
        percent        live       alloc'ed    stack class
rank  self  accum   bytes objs   bytes   objs trace name
   1 9.18%  9.18%  149224 5916 1984600 129884  1073 char []
   2 7.28% 16.45%  118320 5916  118320   5916  1090 sun/tools/java/Identifier
   3 7.28% 23.73%  118320 5916  118320   5916  1091 java/util/Hashtable$Entry
   ...
   7 3.39% 41.42%   55180 2759   55180   2759  1264 java/util/Hashtable$Entry
   ...
SITES END
ヒーププロファイルで重要な情報は、プログラムのさまざまな箇所で発生する割り当ての量です。 上記の SITES レコードでは、ライブオブジェクトの 9.18% が文字配列であることがわかります。 ライブデータの量は、特定のサイトで発生した割り当て全体のごく一部です。残りのデータは、ガベージコレクトされています。

割り当てサイトをソースコードに関連付けるには、ヒープ割り当てまでの動的なスタックトレースを記録するのが良い方法です。 上記のプロファイラ出力のうち、4 つの割り当てサイトによって参照されるスタックトレースの部分を、このあとに示します。 

THREAD START (obj=1d6b20, id = 1, name="main", group="main")
...
TRACE 1073: (thread=1)
        java/lang/String.<init>(String.java:244)
        sun/tools/java/Scanner.bufferString(Scanner.java:143)
        sun/tools/java/Scanner.scanIdentifier(Scanner.java:942)
        sun/tools/java/Scanner.xscan(Scanner.java:1281)

TRACE 1090: (thread=1)
        sun/tools/java/Identifier.lookup(Identifier.java:106)
        sun/tools/java/Scanner.scanIdentifier(Scanner.java:942)
        sun/tools/java/Scanner.xscan(Scanner.java:1281)
        sun/tools/java/Scanner.scan(Scanner.java:971)

TRACE 1091: (thread=1)
        java/util/Hashtable.put(Hashtable.java:405)
        sun/tools/java/Identifier.lookup(Identifier.java:106)
        sun/tools/java/Scanner.scanIdentifier(Scanner.java:942)
        sun/tools/java/Scanner.xscan(Scanner.java:1281)

TRACE 1264: (thread=1)
        java/util/Hashtable.put(Hashtable.java:405)
        sun/tools/java/Type.<init>(Type.java:90)
        sun/tools/java/MethodType.<init>(MethodType.java:42)
        sun/tools/java/Type.tMethod(Type.java:274)

スタックトレースの各フレームには、クラス名、メソッド名、ソースファイル名、および行番号が含まれています。 ユーザは、HPROF エージェントによって収集されるフレーム数の最大値を設定できます。 デフォルトの最大値は 4 です。 スタックトレースを記録すると、ヒープ割り当てを実行したメソッド以外に、メモリを実際に割り当てた呼び出しが行われたメソッドがわかります。 たとえば、上記のヒーププロファイルでは、同じ java/util/Hashtable$Entry クラスのインスタンスが、トレース 1091 と 1264 で割り当てられていますが、それぞれ異なるメソッドから発生しています。

7.3. CPU 使用率のプロファイル

HPROF では、CPU 使用率の情報は、CPU 時間のプロファイルのサンプリングによって収集されます。 次の出力は、javac コンパイラの実行結果が収集された出力の一部です。 

使用したコマンド: javac -J-Xrunhprof:cpu=samples foo.java ...

CPU SAMPLES BEGIN (total = 252378) Wed Oct 07 13:30:10 1998
rank   self  accum   count trace method
   1  4.96%  4.96%   12514   303 sun/io/ByteToCharSingleByte.convert
   2  3.18%  8.14%    8022   306 java/lang/String.charAt
   3  1.91% 10.05%    4828   301 sun/tools/java/ScannerInputReader.<init>
   4  1.80% 11.85%    4545   305 sun/io/ByteToCharSingleByte.getUnicode
   5  1.50% 13.35%    3783   304 sun/io/ByteToCharSingleByte.getUnicode
   6  1.30% 14.65%    3280   336 sun/tools/java/ScannerInputReader.read
   7  1.13% 15.78%    2864   404 sun/io/ByteToCharSingleByte.convert
   8  1.11% 16.89%    2800   307 java/lang/String.length
   9  1.00% 17.89%    2516  4028 java/lang/Integer.toString
  10  0.95% 18.84%    2403   162 java/lang/System.arraycopy
...
CPU SAMPLES END

HPROF エージェントでは、実行中のすべてのスレッドのスタックが定期的にサンプリングされ、アクティブになる頻度がもっとも高かったスタックトレースが記録されます。 count フィールドは、特定のスタックトレースがアクティブな状態で検出された回数です。 これらのスタックトレースは、アプリケーション内で CPU 使用率がもっとも高い部分に相当します。

8. コード例

8.1. 簡単なクラスロードトレーサ

jvmpi_example.zip ファイルには、Java プログラムによってロードされるすべてのクラスをトレースできる、サンプルプロファイラエージェントが含まれています。 Solaris 版と Win32 版の 2 つが含まれています。

8.2. HPROF プロファイリングエージェント

hprof.zip ファイルには、Java 2 SDK の HPROF プロファイリングエージェントの実装が含まれています。 Solaris 版と Win32 版の 2 つが含まれています。

* この Web サイトで使用されている用語「Java 仮想マシン」または「JVM」は、Java プラットフォーム用の仮想マシンを表します。

最終更新日: 12 月 7 日 16:48:00 PST