Microsoft SDK for Java

IJavaEventMonitor::
Initialize

The Initialize method of the IJavaEventMonitor interface is called by the Microsoft VM to initialize the profiler (event monitor) whenever a new Java process is started. The Microsoft VM passes in the class name of the Java class that started the VM, a pointer to an IJavaEventMonitorIDInfo object implemented by the Microsoft VM, the Microsoft VM state flags, and a pointer to the requested events that will trigger notification. The profiler must set the requested events bitmask to the list of events for which it wants to receive notification.

Syntax

HRESULT Initialize(LPCSTR pclass_file_name, IJavaEventMonitorIDInfo *pmonitor_info, DWORD java_flags, DWORD *prequested_events);

Return Value

A list of events for which the profiler wants to receive notification.

Parameters

[in] pclass_file_name The string name of the class in UTF-8 format that started the Microsoft VM. This parameter is taken directly from the Java class file, unmodified.
[in] pmonitor_info The Microsoft VM passes in a pointer to the IJavaEventMonitorIDInfo object that it implements. The profiler application calls methods on this interface to communicate with the MicrosoftVM.
[in] java_flags A bitmask of JVM_STATE_FLAGS that indicate which features are enabled in the Microsoft VM for this Java process.
[out] prequested_events A pointer to a bitmask of flags from the JAVA_EVENT_CATEGORY enumeration indicating events for which the profiler wants to receive notification.

Remarks

The Microsoft VM passes the profiler the name of Java class that has started execution of the VM. The profiler is also passed a set of flags that indicate the state of the Microsoft VM and which features are enabled. These state flags can be a combination of the flags defined in the JVM_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.

The Microsoft VM passes the profiler application a pointer to a bitmask of flags from JAVA_EVENT_CATEGORY indicating which events that the profiler wants to receive notification for. The profiler application should set this parameter to the bitmask of events for which it wants to receive notification. Profilers or event monitors can request notification for any combination of the 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.

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