Extension SDK 9.0.5

oracle.jdeveloper.profiler
Class ProfilerAPI

java.lang.Object
  extended byoracle.jdeveloper.profiler.ProfilerAPI

public class ProfilerAPI
extends java.lang.Object

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

This class 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.

See Also:
Profiler Package Summary

Field Summary
static boolean isActive
           
 
Method Summary
static void addComment(int handle, boolean o)
          Add boolean to the event comment.
static void addComment(int handle, char o)
          Add char to the event comment.
static void addComment(int handle, char[] o)
          Add char[] to the event comment.
static void addComment(int handle, char[] o, int offset, int count)
          Add part of char[] to the event comment.
static void addComment(int handle, double o)
          Add double to the event comment.
static void addComment(int handle, float o)
          Add float to the event comment.
static void addComment(int handle, int o)
          Add int to the event comment.
static void addComment(int handle, long o)
          Add long to the event comment.
static void addComment(int handle, java.lang.Object o)
          Add to the event comment.
static void addComment(int handle, java.lang.String comment)
          Add String comment to the event.
static void addStackToComment(int handle)
          Add the current stack as to the event comment.
static void clearEventHistory()
          Clear the event history.
static void createEvent(int id, long start, long stop, java.lang.String comment)
          Create event.
static void dumpEventHistory()
          Dump event history.
static void endEvent(int handle)
          End an event.
static void endEvent(int handle, java.lang.String comment)
          End an event.
static java.lang.String getDMSParams()
          Get DMS internal parameters.
static long getTimer()
          Get high performance timer.
static boolean isEventActive(int event)
          Check if this particular Event ID is active during this run.
static void pulseEvent(int event, java.lang.String comment)
          Create a pulse event.
static int startEvent(int event)
          Start profiler event.
static int startEvent(int event, java.lang.String comment)
          Start profiler event.
static void startSampling()
          Start sampling, this call must be paired with stopSampling().
static void stopSampling()
          Stop sampling, this call must be paired with startSampling().
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

isActive

public static boolean isActive
Method Detail

startSampling

public static void startSampling()
Start sampling, this call must be paired with stopSampling(). Sampling is on as long as the outermost call to stopSampling is executed.

See Also:
stopSampling()

stopSampling

public static void stopSampling()
Stop sampling, this call must be paired with startSampling().

See Also:
startSampling()

startEvent

public static int startEvent(int event,
                             java.lang.String comment)
Start profiler event.

The returned handle which must be used for any further references to this event.

This call must be paired with a call to endEvent.

Multiple events with the same ID can be started and ended independently.

Start time and code position are evaluated during this call.

The comment String argument is stored within the VM, any futher comments will be appended.

If event profiler is not activated or this event is not active, the returned value is -1. All further calls to any event function will then return immediatly. It's why it's a good idea to initialize the handle to -1.

Parameters:
event - Event ID.
comment - Comment.
Returns:
Event handle. -1 if profiler or event inactive.
See Also:
endEvent(int), endEvent(int, String)

startEvent

public static int startEvent(int event)
Start profiler event.

The returned handle which must be used for any further references to this event.

This call must be paired with a call to endEvent.

Multiple events with the same ID can be started and ended independently.

Start time and code position are evaluated during this call.

If event profiler is not activated or this event is not active, the returned value is -1. All further calls to any event function will then return immediatly. It's why it's a good idea to initialize the handle to -1.

This call is equivalent to startEvent(event, null);

Parameters:
event - Event ID.
Returns:
Event handle. -1 if profiler or event inactive.
See Also:
endEvent(int), endEvent(int, String)

endEvent

public static void endEvent(int handle,
                            java.lang.String comment)
End an event.

This call must be paired with a call to startEvent. The Handler must have been provided by a startEvent function or be -1, any other value will be ignored and a warning will be sent on stderr.

Multiple events with the same ID can be started and ended independently.

End time is evaluated during this call.

The comment String argument appended to the current comment.

Once an event is ended, no further calls should be made using this particular handle. endEvent must be the last call to generate this event.

Parameters:
handle - Event Handle.
comment - Comment
See Also:
endEvent(int), startEvent(int, String), startEvent(int)

endEvent

public static void endEvent(int handle)
End an event.

This call must be paired with a call to startEvent. The Handler must have been provided by a startEvent function or be -1, any other value will be ignored and a warning will be sent on stderr.

Multiple events with the same ID can be started and ended independently.

Equivalent to endEvent(handle, null); End time is evaluated during this call.

Once an event is ended, no further calls should be made using this particular handle. endEvent must be the last call to generate this event.

Parameters:
handle - Event Handle.
See Also:
endEvent(int, String), startEvent(int, String), startEvent(int)

pulseEvent

public static void pulseEvent(int event,
                              java.lang.String comment)
Create a pulse event.

Position, Start and End time are evaluated during this call.

This function allows you to create an event with no significant duration.

Parameters:
event - Event ID.
comment - Comment.

isEventActive

public static boolean isEventActive(int event)
Check if this particular Event ID is active during this run. This function should be used to avoid extra overhead if any event is not needed in this particular run.

Parameters:
event - Event ID.
Returns:
true if active and profiling in active false otherwise.

addComment

public static void addComment(int handle,
                              java.lang.String comment)
Add String comment to the event. The Handler must have been provided by a startEvent function or be -1, any other value will output a warning message on stderr.

The comment is appended at the end of the current comment.

Parameters:
handle - Event Handle.
comment - Comment to append.
See Also:
startEvent(int, String), startEvent(int)

addStackToComment

public static void addStackToComment(int handle)
Add the current stack as to the event comment. The Handler must have been provided by a startEvent function or be -1, any other value will output a warning message on stderr.

The current stack is appended at the end of the current comment.

This function can be time and memory expensive, it's not advisable to use it for very common events.

Parameters:
handle - Event Handle.
See Also:
startEvent(int, String), startEvent(int)

clearEventHistory

public static void clearEventHistory()
Clear the event history. Discard all currently stored events, pending (unfinished) events are not discarded.


dumpEventHistory

public static void dumpEventHistory()
Dump event history. Current event history is dumped to stdout.


addComment

public static void addComment(int handle,
                              java.lang.Object o)
Add to the event comment. The Handler must have been provided by a startEvent function or be -1, any other value will output a warning message on stderr.

o.toString() is appended at the end of the current comment.

Parameters:
handle - Event Handle.
o - Object to append.
See Also:
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              int o)
Add int to the event comment. The Handler must have been provided by a startEvent function or be -1, any other value will output a warning message on stderr.

String.valueOf(o) is appended at the end of the current comment.

Parameters:
handle - Event Handle.
o - int to append.
See Also:
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              char o)
Add char to the event comment. The Handler must have been provided by a startEvent function or be -1, any other value will output a warning message on stderr.

String.valueOf(o) is appended at the end of the current comment.

Parameters:
handle - Event Handle.
o - char to append.
See Also:
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              boolean o)
Add boolean to the event comment. The Handler must have been provided by a startEvent function or be -1, any other value will output a warning message on stderr.

String.valueOf(o) is appended at the end of the current comment.

Parameters:
handle - Event Handle.
o - boolean to append.
See Also:
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              float o)
Add float to the event comment. The Handler must have been provided by a startEvent function or be -1, any other value will output a warning message on stderr.

String.valueOf(o) is appended at the end of the current comment.

Parameters:
handle - Event Handle.
o - float to append.
See Also:
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              double o)
Add double to the event comment. The Handler must have been provided by a startEvent function or be -1, any other value will output a warning message on stderr.

String.valueOf(o) is appended at the end of the current comment.

Parameters:
handle - Event Handle.
o - double to append.
See Also:
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              long o)
Add long to the event comment. The Handler must have been provided by a startEvent function or be -1, any other value will output a warning message on stderr.

String.valueOf(o) is appended at the end of the current comment.

Parameters:
handle - Event Handle.
o - long to append.
See Also:
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              char[] o)
Add char[] to the event comment. The Handler must have been provided by a startEvent function or be -1, any other value will output a warning message on stderr.

String.valueOf(o) is appended at the end of the current comment.

Parameters:
handle - Event Handle.
o - char[] to append.
See Also:
startEvent(int, String), startEvent(int)

addComment

public static void addComment(int handle,
                              char[] o,
                              int offset,
                              int count)
Add part of char[] to the event comment. The Handler must have been provided by a startEvent function or be -1, any other value will output a warning message on stderr.

String.valueOf(o, fffset, count) is appended at the end of the current comment.

Parameters:
handle - Event Handle.
o - int to append.
offset - index of first char to append.
count - Number of char to append.
See Also:
startEvent(int, String), startEvent(int)

getTimer

public static long getTimer()
Get high performance timer.

This method allows the user to get a time stamp at any given time to create events in a single call. This method can be usefull to coordinate start or end time of a group of events. Unless it's very important to have the exact same start or stop time it's strongly advised to use tha classical startEvent / endEvent logic to instrument your application.

Returns:
High performance time counter.
See Also:
createEvent(int ,long ,long ,String)

createEvent

public static void createEvent(int id,
                               long start,
                               long stop,
                               java.lang.String comment)
Create event. Once time stamps have been obtained with the getTimer() method, events can be created directly with this method

Code position are evaluated during this call.

Parameters:
id - Event ID
start - start time
stop - end time
comment - event comment
See Also:
getTimer()

getDMSParams

public static java.lang.String getDMSParams()
Get DMS internal parameters. Internal function used by the DMS stub interface.

This function shouldn't be used by anything else.

Returns:
DMS parameters.

Extension SDK

 

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