Extension SDK 9.0.5

Package oracle.jdeveloper.profiler

Utility package to provide code level support for the profiling features.

See:
          Description

Interface Summary
EventTester  
 

Class Summary
DefaultEventTester  
ProfilerAPI Utility class to provide code level support for the profiling features.
 

Package oracle.jdeveloper.profiler Description

Utility package to provide code level support for the profiling features.

This package contains a set of static methods allowing code instrumentation for profiling. Instrumented code will run on any VM or in any mode with OJVM, but the instrumentation will be effective only if you run your program with OJVM in profiling mode. In any other cases the implementation is designed to be 'transparent' and add no execution penalty if the instrumentation is done properly.

It currently support 2 of the profiling mode of jdeveloper. Sample profiling and Event Profiling.

In Sample Profiling mode you can instrument your code to start / stop the sampler to profile a specific area of your program. See ProfilerAPI

Typical sampling code implementation :
public void foo()
{
  ProfilerAPI.startSampling(); // Starts the sampler
  // execute some code
  ProfilerAPI.startSampling(); // Starts the sampler
}

Nested calls of start/stop sampling are allowed.

Usefull Event profiling requires code instrumentation, even if the VM and some libraries generate events. The ProfilerAPI class allows you to do so.

Events have the folowing attributes :

An ID : Integer value describing the event type, User is responsible to provide unique ID system wide, it's strongly recommended to use static final int CSTXXX to define events ID. OJVM might generate events ID from 0-99 but the event ID unicity is not enforced by the API.

A comment : Extra information associated with every events. Unless the Event is trivial, it's your best interest to provide meaningfull information thru this comment.

Start and End time : Provided automaticaly using a high performance time counter.

Code position : Provided automaticaly by the VM.

Recomended event instrumentation :
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 usefull for the user
          ProfilerAPI.addComment(eventHandler, " Simple request\n");
        }
        // actual code of the simple request
      }
      else
      {
        if (EVENT_ON)
        { // might be usefull 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
}

This implementation looks complex but it try to deal with all cases, and to have almost no performance penalty if you are not event profiling. If you know that your code will not throw any exceptions, all the try / catch / finally structure is useless. Using a static boolean evaluated only once minimize the performance penalty when not profiling, it would work properly without this 'trick' as the ProfilerAPI functions would just return instantly but all the methods arguments would have been evaluated already.


Extension SDK

 

Copyright © 1997, 2004, Oracle. All rights reserved.