Microsoft SDK for Java

IJavaEventMonitorIDInfo2::
GetProfilingCapabilities

The GetProfilingCapabilities method of the IJavaEventMonitorIDInfo2 interface is called by a profiler to query the Microsoft VM for the profiling capabilities that it supports.

The GetProfilingCapabilities method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.

Syntax

HRESULT GetProfilingCapabilities(DWORD *pStates, DWORD *pCategories, JAVA_EXECUTION_MODEL *pLastModel, JVM_EVENT_TYPE *pLastType, JVM_EVENT_TYPE2 *pLastType2);

Return Value

A bitmask of flags indicating the maximum possible list of event categories on which a profiler can request notification, a bitmask of flags indicating which event categories are currently being notified, the highest possible value for the Java execution model, and the highest possible value for the type of events that will be notified on the profiler's NotifyEvent and NotifyEvent2 methods.

Parameters

[out] *pStates A bitmask of flags from JAVA_STATE_FLAGS indicating the possible state flags that are supported for this Java process.
[out] *pCategories A bitmask of flags indicating the possible list of event categories (JVM_EVENT_CATEGORY) supported by the Microsoft VM for this Java process on which a profiler can request notification.
[out] *pLastModel The highest possible value for the Java execution model supported by the Microsoft VM.
[out] *pLastType The highest possible value for the type of events that will be notified on the profiler's NotifyEvent method.
[out] *pLastType2 The highest possible value for the type of events that will be notified on the profiler's NotifyEvent2 method.

Remarks

The possible Java state flags can be a combination of the JAVA_STATE_FLAGS types or the last predefined combined type as defined in the JAVA_STATE_FLAGS enumeration.

JAVA_STATE_FLAGS

Constant Value Description
JVM_STATE_INTERPRETER_ENABLED 0x1 The Java interpreter is enabled.
JVM_STATE_FAST_INTERPRETER_ENABLED 0x2 The fast interpreter is enabled.
JVM_STATE_JIT_COMPILER_ENABLED 0x4 The JIT-compiler is enabled.
JVM_STATE_DEBUGGER_ENABLED 0x8 The debugger is enabled.
ALL_JVM_FLAGS 0xF All the previous flags are enabled.

Profilers or event monitors can request notification for any combination of the following event categories as defined in the JAVA_EVENT_CATEGORY enumeration.

JAVA_Event_Category

Constant Value Description
JVM_MONITOR_NONE 0 Do not send notification for any event categories.
JVM_MONITOR_CLASS_LOADS 1 Send event notification when a Java class is loaded or when the class is unloaded. The Microsoft VM will call the NotifyEvent method implemented by the profiler.
JVM_MONITOR_METHOD_CALLS 2 Send event notification when a Java method is about to be called and upon completion of the method call. The Microsoft VM will call the MethodEntry and MethodExit methods implemented by the profiler. If the profiler implements IJavaEventMonitor2 interface, the Microsoft VM will call MethodExit2 on this interface rather than MethodExit.
JVM_MONITOR_JIT_COMPILATION 4 Send event notification when a Java class is about to be JIT compiled and after JIT compilation is completed. The Microsoft VM will call the NotifyEvent method implemented by the profiler.
JVM_MONITOR_BYTE_CODE_EXECUTION 8 Send event notification when a byte code instruction of an interpreted method is about to be executed. The Microsoft VM will call the ExecuteByteCode method implemented by the profiler. If any profiler requests this event category, then JIT compilation will be disabled for all methods.
JVM_MONITOR_SOURCE_LINE_EXECUTION 0x10 Send event notification when a Java source line is about to be executed. The Microsoft VM will call the ExecuteSourceLine method implemented by the profiler.
JVM_MONITOR_EXCEPTIONS 0x20 Send event notification when an exception is about to be thrown. The Microsoft VM will call the NotifyEvent2 method if the IJavaEventMonitor2 interface is implemented by the profiler. Otherwise the Microsoft VM will call the NotifyEvent method.
JVM_MONITOR_GARBAGE_COLLECTIONS 0x80 Send event notification when the VM is about to execute garbage collection. The Microsoft VM will call the NotifyEvent method implemented by the profiler.
JVM_MONITOR_THREADS 0x100 Send event notification when a Java thread is about to be created or destroyed. The Microsoft VM will call the NotifyEvent method implemented by the profiler. If the IJavaEventMonitor2 interface is implemented by the profiler, the Microsoft VM will also call the NotifyEvent2 method when a thread's name has been set.
JVM_MONITOR_SAMPLING 0x200 Changes the behavior of the Microsoft VM to improve the accuracy of sampling. Note that this event category doesn't generate any additional event notifications, but improves the accuracy of the SampleThreadLocation method implemented by the Microsoft VM. Specifying this event category slows down the execution of non-JIT compiled methods, but improves the accuracy of the sampling data for these methods.
JVM_MONITOR_EXCEPTION_UNWIND 0x400 Send event notification when a Java exception is about to be thrown past a stack frame. If the IJavaEventMonitor2 interface is implemented by the profiler, the Microsoft VM will call the NotifyEvent2 method.
JVM_MONITOR_SPECIFIC_METHOD_CALLS 0x800 Send event notification when specific methods are called. The Microsoft VM will call the MethodEntry and MethodExit methods implemented by the profiler. If the IJavaEventMonitor2 interface is implemented by the profiler, the Microsoft VM will call the MethodExit2 method rather than MethodExit.
ALL_JVM_MONITOR_EVENTS 0xFFF Send event notification on all event categories.

The possible execution models can be one of the types defined in the JAVA_EXECUTION_MODEL enumeration.

JAVA_EXECUTION_MODEL

Constant Value Description
JVM_EXECUTION_INVALID -1 The execution model for this method is invalid.
JVM_EXECUTION_JIT_COMPILED 0 The method is JIT-compiled.
JVM_EXECUTION_NATIVE 1 The method is a native Win32 method.
JVM_EXECUTION_INTERPRETED 2 The method is interpreted.
JVM_EXECUTION_FAST_INTERPRETED 3 The method is fast-interpreted.
JVM_EXECUTION_COM 4 The method is a native COM method.

The possible event types that can be passed to the NotifyEvent method can be one of the following types as defined in the JVM_EVENT_TYPE enumeration.

JVM_EVENT_TYPE

Constant Value Description
JVM_EVENT_TYPE_EXCEPTION_OCCURRED 0 An exception occurred. The UniqueID passed as the second parameter is a StackID of the stack frame that the exception handler will be executed in.
JVM_EVENT_TYPE_THREAD_CREATE 4 A Java thread is being created. The UniqueID passed as the second parameter is the ThreadID of the Java thread.
JVM_EVENT_TYPE_THREAD_DESTROY 5 A Java thread is being destroyed. The UniqueID passed as the second parameter is the ThreadID of the Java thread.
JVM_EVENT_TYPE_CLASS_LOAD_STARTED 6 A Java class is starting to be loaded. The UniqueID passed as the second parameter is a pointer to the class name (a UTF-8 string) of the class.
JVM_EVENT_TYPE_CLASS_LOAD_FINISHED 7 A Java class is finished loading. The UniqueID passed as the second parameter is a pointer to the ClassID of the class loaded.
JVM_EVENT_TYPE_CLASS_LOAD_FAILED 17 A Java class failed to be loaded. The UniqueID passed as the second parameter is a pointer to the class name (a UTF-8 string) of the class.
JVM_EVENT_TYPE_CLASS_UNLOAD 8 A Java class is being unloaded. The UniqueID passed as the second parameter is the ClassID of the class.
JVM_EVENT_TYPE_JIT_COMPILE_STARTED 9 The JIT compiler is starting to compile a class method. The UniqueID passed as the second parameter is the MethodID of the class method being compiled.
JVM_EVENT_TYPE_JIT_COMPILE_FINISHED 10 The JIT compiler is finished compiling a class method. The UniqueID passed as the second parameter is the MethodID of the class method that was compiled.
JVM_EVENT_TYPE_GC_STARTED 11 Garbage collection is starting. The UniqueID passed as the second parameter is undefined (this parameter is not used).
JVM_EVENT_TYPE_GC_FINISHED 12 Garbage collection has finished. The UniqueID passed as the second parameter is undefined. (This parameter is not used.)
JVM_EVENT_TYPE_SHUTDOWN 12 The program is exiting. The UniqueID passed as the second parameter is undefined. (This parameter is not used.)
JVM_EVENT_TYPE_RESERVED_14 14 This event type, formerly called JVM_EVENT_TYPE_SHUTDOWN_ERROR, is deprecated and no longer dispatched by the Microsoft VM.
JVM_EVENT_TYPE_RESERVED_15 15 This event type, formerly called JVM_EVENT_TYPE_SHUTDOWN_INTERRUPTED, is deprecated and no longer dispatched by the Microsoft VM.
JVM_EVENT_TYPE_RESERVED_17 17 This formerly reserved event type is now used for JVM_EVENT_TYPE_CLASS_LOAD_FAILED.

The possible event types that can be passed to the NotifyEvent2 method can be one of the types defined in the JVM_EVENT_TYPE2 enumeration.

JAVA_EVENT_TYPE2

Constant Value Description
JVM_EVENT_TYPE2_THREAD_SET_NAME 1025 A thread's name has been set.
JVM_EVENT_TYPE2_EXCEPTION_OCCURRED 1026 An exception occurred. This event supercedes JVM_EVENT_TYPE_EXCEPTION_OCCURRED if IJavaEventMonitor2 is implemented and JVM_EVENT_TYPE_EXCEPTION_OCCURRED will never be passed to NotifyEvent.
JVM_EVENT_TYPE2_EXCEPTION_THROWN 1027 An exception is about to be thrown.
JVM_EVENT_TYPE2_EXCEPTION_UNWIND 1028 An exception is being thrown past this frame.
JVM_EVENT_TYPE2_STACK_TRACE 1029 This event notifies a callback from GetStackTrace.
JVM_EVENT_TYPE2_INITIALIZED 1030 The Microsoft VM has fully initialized.
JVM_EVENT_TYPE2_MONITORS_INITIALIZED 1031 All event monitors have initialized. ID1 is the number of event monitors attached to the VM. ID2 is a bitmask of JAVA_EVENT_CATEGORY, indicating the maximum possible set of events that may be enabled by all attached profilers.

Note   JVM_EVENT_TYPE2_MONITORS_INITIALIZED is the number of monitors that were attached at the time the VM started initializing. This number is used by the VM as part of optimizing profiling overhead. If profilers detach in response to this event, this overhead remains, based on the original number. Programmatically, it is really a BOOL. Any profiler that needs timing accuracy will care only that there are other profilers, not how many. However, if it needed to present the user interface, this would indicate how many applicationss were running that needed to be closed. Otherwise, you keep re-running it until it says there are none.

© 1999 Microsoft Corporation. All rights reserved. Terms of use.