oracle.jdeveloper.profiler
クラスProfilerAPI


java.lang.Object
  |
  +--oracle.jdeveloper.profiler.ProfilerAPI

public class ProfilerAPI
extends java.lang.Object

プロファイリング機能のコード・レベル・サポートを提供するユーティリティ・クラス。

このクラスには、プロファイリングのコード・インストルメンテーションを可能にするstaticメソッドのセットが含まれます。インストルメント・コードは任意のVMまたは任意のモードのOJVMで実行可能ですが、インストルメンテーションはプロファイリング・モードのOJVMでプログラムを実行した場合のみ有効です。それ以外の場合には、実装は透過的になるよう設計されており、またインストルメンテーションが適切に行われているかぎり、実行に問題が生じないよう設計されています。

現在このクラスは、実行プロファイリングおよびイベント・プロファイリングの2つのJDeveloperプロファイリング・モードをサポートしています。

実行プロファイラの使用例

実行プロファイリング・モードでは、プログラムの特定の領域をプロファイリングするために、プロファイラを開始または停止するようコードをインストルメントできます。startSampling()stopSampling()を参照してください。

典型的なサンプリング・コードの実装は次のとおりです。
public void foo()
{
  ProfilerAPI.startSampling(); // Starts the sampler
  // execute some code
  ProfilerAPI.stopSampling(); // Stops the sampler
}

サンプリングの開始および停止のコールはネストできます。

イベント・プロファイラの使用例

VMおよびいくつかのライブラリがイベントを生成する場合でも、有用なイベント・プロファイリングにはコード・インストルメントが必要です。ProfilerAPIクラスでこれを行うことができます。

イベントには次の属性があります。

ID
イベント・タイプを説明する整数値。ユーザーは、システム全体で一意のIDを指定する必要があります。イベントIDの定義にはstatic final int CSTXXXを使用することを強くお薦めします。OJVMは0から99のイベントIDを生成しますが、APIではイベントIDの単一性は保証されません。
コメント
すべてのイベントに関連付けられているその他の情報。単純なイベントでないかぎり、このコメントに情報を指定するようにしてください。
開始時刻および終了時刻
パフォーマンスの高いタイム・カウンタを使用して自動的に指定されます。
コード位置
VMにより自動的に指定されます。

推奨されるイベント・インストルメンテーションは次のとおりです。
class foo
{
  private static final int EVENT_ID = 500;
  private static final boolean EVENT_ON =
      ProfilerAPI.isActive && ProfilerAPI.isEventActive(EVENT_ID);
  // some code
  String getInfo(String request)
  {
    int eventHandler = -1; // default value
    if (EVENT_ON)
    {
      eventHandler = ProfilerAPI.startEvent(EVENT_ID, "Getting info for " + request + "\n");
    }
    try
    {
      // some code
      if (simpleRequest)
      {
        if (EVENT_ON)
        { // might be useful for the user
          ProfilerAPI.addComment(eventHandler, " Simple request\n");
        }
        // actual code of the simple request
      }
      else
      {
        if (EVENT_ON)
        { // might be useful for the user
          ProfilerAPI.addComment(eventHandler, " Complex request\n");
        }
        // actual code of the complex request
      }
    }
    catch (Throwable e)
    {
      if (EVENT_ON)
      {
        ProfilerAPI.addComment(eventHandler, " Interrupted with exception " + e);
      }
      throw(e);
    }
    finally
    {
      if (EVENT_ON)
      {
        ProfilerAPI.endEvent(eventHandler, " Result = " + res);
      }
    }
    return res;
  }
  // other methods
}

この実装は複雑に見えますが、これはすべてのケースに対処するようにしたためです。イベント・プロファイリング以外では、パフォーマンスにほとんど問題はありません。コードが例外をスローしないことがわかっている場合、try/catch/finally構造はすべて不要です。1回だけ評価されるstatic booleanを使用すると、プロファイリング時のパフォーマンスの問題を最小限に抑えることができます。ProfilerAPI関数は即時に戻りますが、メソッド引数はすべて評価されるため、この方法を使用しなくても正しく動作します。


フィールドの概要
static boolean isActive
           
 
メソッドの概要
static void addComment(int handle, boolean o)
          イベントにコメントを追加します。
static void addComment(int handle, char o)
          イベントにコメントを追加します。
static void addComment(int handle, char[] o)
          イベントにコメントを追加します。
static void addComment(int handle, char[] o, int offset, int count)
          イベントにコメントを追加します。
static void addComment(int handle, double o)
          イベントにコメントを追加します。
static void addComment(int handle, float o)
          イベントにコメントを追加します。
static void addComment(int handle, int o)
          イベントにコメントを追加します。
static void addComment(int handle, long o)
          イベントにコメントを追加します。
static void addComment(int handle, java.lang.Object o)
          イベントにコメントを追加します。
static void addComment(int handle, java.lang.String o)
          イベントにStringコメントを追加します。
static void addStackToComment(int handle)
          コメントに現在のスタックを追加します。
static void clearEventHistory()
          終了していないイベントを除くすべてのイベントを消去します。
static void dumpEventHistory()
          現在のストアド・イベントをstderrに出力します。
static void endEvent(int handle)
          イベントを終了します。
static void endEvent(int handle, java.lang.String comment)
          イベントを終了します。
static boolean isEventActive(int event)
          このイベントIDがこの実行中にアクティブかどうかをチェックします。
static void pulseEvent(int event, java.lang.String comment)
          パルス・イベントを作成します。
static int startEvent(int event)
          このイベントの参照に使用するハンドルを返します。
static int startEvent(int event, java.lang.String comment)
          このイベントの参照に使用するハンドルを返します。
static void startSampling()
          サンプリングを開始します。このコールは、stopSampling()とペアになっている必要があります。
static void stopSampling()
          サンプリングを停止します。このコールは、startSampling()とペアになっている必要があります。
 
クラス java.lang.Objectから継承したメソッド
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

フィールドの詳細

isActive

public static boolean isActive
メソッドの詳細

startSampling

public static void startSampling()
サンプリングを開始します。このコールは、stopSampling()とペアになっている必要があります。

サンプリングは、stopSamplingに対する最も外側のコールが実行されるまで行われます。

関連項目: 
stopSampling()

stopSampling

public static void stopSampling()
サンプリングを停止します。このコールは、startSampling()とペアになっている必要があります。
関連項目: 
startSampling()

startEvent

public static int startEvent(int event,
                             java.lang.String comment)
このイベントの参照に使用するハンドルを返します。

このコールは、endEventへのコールとペアになっている必要があります。

同じIDを持つ複数のイベントは、個別に開始および停止できます。

開始時刻およびコード位置はこのコール中に評価されます。

コメントString引数は、VM内に格納されます。コメントがさらに追加されます。

イベント・プロファイラまたはイベントがアクティブでない場合、戻り値は-1です。イベント関数へのすべてのコールは即時に戻ります。このため、ハンドルは-1に初期化することをお薦めします。

パラメータ: 
event - イベントID
comment - コメント
戻り値: 
イベント・ハンドル
関連項目: 
endEvent(int), endEvent(int, String)

startEvent

public static int startEvent(int event)
このイベントの参照に使用するハンドルを返します。

このコールは、endEventへのコールとペアになっている必要があります。

同じIDを持つ複数のイベントは、個別に開始および停止できます。

このコールはstartEvent(event, null);と等価です。

パラメータ: 
event - イベントID
戻り値: 
イベント・ハンドル
関連項目: 
startEvent(int, String), endEvent(int), endEvent(int, String)

endEvent

public static void endEvent(int handle,
                            java.lang.String comment)
イベントを終了します。

このコールは、startEventへのコールとペアになっている必要があります。ハンドラは、startEvent関数により提供されるか、または-1である必要があります。その他の値は無視され、警告メッセージがstderrに出力されます。

同じIDを持つ複数のイベントは、個別に開始および停止できます。

終了時刻はこのコール中に評価されます。

コメントString引数は、現在のコメントに追加されます。

イベントIDの終了後は、このハンドルを使用してコールを行わないでください。endEventを、このイベントを生成する最後のコールとする必要があります。

パラメータ: 
handle - イベント・ハンドル
comment - コメント
関連項目: 
endEvent(int), startEvent(int, String), startEvent(int)

endEvent

public static void endEvent(int handle)
イベントを終了します。

このコールは、startEventへのコールとペアになっている必要があります。ハンドラは、startEvent関数により提供されるか、または-1である必要があります。その他の値は無視され、警告メッセージがstderrに出力されます。

同じIDを持つ複数のイベントは、個別に開始および停止できます。

endEvent(handle, null);と等価です。終了時刻はこのコール中に評価されます。

イベントIDの終了後は、このハンドルを使用してコールを行わないでください。endEventを、このイベントを生成する最後のコールとする必要があります。

パラメータ: 
handle - イベント・ハンドル
comment - コメント
関連項目: 
endEvent(int, String), startEvent(int, String), startEvent(int)

pulseEvent

public static void pulseEvent(int event,
                              java.lang.String comment)
パルス・イベントを作成します。

位置、開始時刻および終了時刻はこのコール中に評価されます。

この関数では、継続時間の長くないイベントを作成できます。

パラメータ: 
event - イベントID
comment - コメント

isEventActive

public static boolean isEventActive(int event)
このイベントIDがこの実行中にアクティブかどうかをチェックします。

この実行でイベントが不要な場合に余分なオーバーヘッドを回避するには、この関数を使用する必要があります。

パラメータ: 
event - イベントID
戻り値: 
イベント・ハンドル

addComment

public static void addComment(int handle,
                              java.lang.String o)
イベントにStringコメントを追加します。

ハンドラは、startEvent関数により提供されるか、または-1である必要があります。その他の値は無視され、警告メッセージがstderrに出力されます。

コメントは、現在のコメントの最後に追加されます。

パラメータ: 
handle - イベント・ハンドル
Comment - コメント
関連項目: 
startEvent(int, String), startEvent(int)

addStackToComment

public static void addStackToComment(int handle)
コメントに現在のスタックを追加します。

ハンドラは、startEvent関数により提供されるか、または-1である必要があります。その他の値は無視され、警告メッセージがstderrに出力されます。

現在のスタックは、現在のコメントの最後に追加されます。

パラメータ: 
handle - イベント・ハンドル
Comment - コメント
関連項目: 
startEvent(int, String), startEvent(int)

clearEventHistory

public static void clearEventHistory()
終了したすべてのイベントを消去します。

dumpEventHistory

public static void dumpEventHistory()
現在のストアド・イベントをstderrに出力します。

addComment

public static void addComment(int handle,
                              java.lang.Object o)
イベントにコメントを追加します。

ハンドラは、startEvent関数により提供されるか、または-1である必要があります。その他の値は無視され、警告メッセージがstderrに出力されます。

コメントは、現在のコメントの最後に追加されます。

addComment(handle, String.valueOf(o))と等価です。

パラメータ: 
handle - イベント・ハンドル
o - コメント
関連項目: 
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              int o)
イベントにコメントを追加します。

ハンドラは、startEvent関数により提供されるか、または-1である必要があります。その他の値は無視され、警告メッセージがstderrに出力されます。

コメントは、現在のコメントの最後に追加されます。

addComment(handle, String.valueOf(o))と等価です。

パラメータ: 
handle - イベント・ハンドル
o - コメント
関連項目: 
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              char o)
イベントにコメントを追加します。

ハンドラは、startEvent関数により提供されるか、または-1である必要があります。その他の値は無視され、警告メッセージがstderrに出力されます。

コメントは、現在のコメントの最後に追加されます。

addComment(handle, String.valueOf(o))と等価です。

パラメータ: 
handle - イベント・ハンドル
o - コメント
関連項目: 
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              Boolean o)
イベントにコメントを追加します。

ハンドラは、startEvent関数により提供されるか、または-1である必要があります。その他の値は無視され、警告メッセージがstderrに出力されます。

コメントは、現在のコメントの最後に追加されます。

addComment(handle, String.valueOf(o))と等価です。

パラメータ: 
handle - イベント・ハンドル
o - コメント
関連項目: 
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              float o)
イベントにコメントを追加します。

ハンドラは、startEvent関数により提供されるか、または-1である必要があります。その他の値は無視され、警告メッセージがstderrに出力されます。

コメントは、現在のコメントの最後に追加されます。

addComment(handle, String.valueOf(o))と等価です。

パラメータ: 
handle - イベント・ハンドル
o - コメント
関連項目: 
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              double o)
イベントにコメントを追加します。

ハンドラは、startEvent関数により提供されるか、または-1である必要があります。その他の値は無視され、警告メッセージがstderrに出力されます。

コメントは、現在のコメントの最後に追加されます。

addComment(handle, String.valueOf(o))と等価です。

パラメータ: 
handle - イベント・ハンドル
o - コメント
関連項目: 
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              long o)
イベントにコメントを追加します。

ハンドラは、startEvent関数により提供されるか、または-1である必要があります。その他の値は無視され、警告メッセージがstderrに出力されます。

コメントは、現在のコメントの最後に追加されます。

addComment(handle, String.valueOf(o))と等価です。

パラメータ: 
handle - イベント・ハンドル
o - コメント
関連項目: 
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              char[] o)
イベントにコメントを追加します。

ハンドラは、startEvent関数により提供されるか、または-1である必要があります。その他の値は無視され、警告メッセージがstderrに出力されます。

コメントは、現在のコメントの最後に追加されます。

addComment(handle, String.valueOf(o))と等価です。

パラメータ: 
handle - イベント・ハンドル
o - コメント
関連項目: 
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              char[] o,
                              int offset,
                              int count)
イベントにコメントを追加します。

ハンドラは、startEvent関数により提供されるか、または-1である必要があります。その他の値は無視され、警告メッセージがstderrに出力されます。

コメントは、現在のコメントの最後に追加されます。

addComment(handle, String.valueOf(o))と等価です。

パラメータ: 
handle - イベント・ハンドル
o - コメント
関連項目: 
startEvent(int, String), startEvent(int)