Microsoft SDK for Java

Initializing Event Monitors

Once a profiler is registered, the Microsoft VM attempts to load the profiler whenever a new Java process is started with profiling enabled. Whenever the Microsoft VM is first loaded in a Win32 process, it checks the registry for any event monitor entries under the HKEY_LOCAL_MACHINE\Software\Microsoft\Java VM\Monitors key and checks for the existence of the MSJAVA_EVENT_MONITORS environment variable. If profiling is enabled, the Microsoft VM calls CoCreateInstance on each event monitor's CLSID and calls the object's Initialize method.

Note   The event monitor lists are not checked for duplicates. If a CLSID is specified multiple times in the registry, the environment variable, or both, the associated profiler is loaded multiple times.

As one of the parameters to the Initialize method, the profiler is passed a pointer to the event monitor information interface, IJavaEventMonitorIDInfo, implemented by the Microsoft VM. This interface can then used by the profiler to communicate with the Microsoft VM. The Initialize method is also passed a bitmask of flags that represent the Microsoft VM's execution state. The profiler returns another bitmask of flags indicating the list of events for which it wants to receive notification. The profiler can also later call SetEventMask to change the list of events that will trigger notification to the profiler.

After all registered monitors have been instantiated, the Microsoft VM initializes the monitors. Certain APIs are only functional during the monitor's Initialize callback; after this time, they will either not function at all or will not have their full effect.

The following lists the settings that must be enabled or disabled during the Initialize callback, and the effects of attempting to modify the settings after this time.

After the Initialize callback returns, the monitor will later receive a NotifyEvent2 callback for the JVM_EVENT_TYPE2_MONITORS_INITIALIZED event. This event provides the number of attached event monitors and the maximum set of event categories that all attached event monitors have indicated that they may ever enable. Monitors may use this information to adjust the accuracy of profiling information. The monitor may call GetFinalInitializationOptions to determine which of the JAVA_MONITOR_INIT_OPTIONS initialization options were able to be used.

JAVA_MONITOR_INIT_OPTIONS

Constant Value Description
JVM_INIT_OPT_DONT_NEED_
ALLOCATION_CALLBACK
N/A Indicates the profiler will not register an IObjectAllocationCallback via IJavaHeapMonitor::NotifyOnObjectAllocations. If this option is enabled and IJavaHeapMonitor::NotifyOnObjectAllocations is called with a non-NULL callback interface, it will return E_FAIL.

Setting this and the JVM_INIT_OPT_DONT_NEED_ALLOCATION_COUNTS flag allows the Microsoft VM to use the normal uninstrumented JIT allocation helpers.

JVM_INIT_OPT_DONT_NEED_
ALLOCATION_COUNTS
N/A Indicates that allocation counts aren't needed from IJavaEventMonitorIDInfo::ClassInformation. If the pobjects_created parameters is specified, its output value is indeterminate.

Setting this and the JVM_INIT_OPT_DONT_NEED_ALLOCATION_CALLBACK flag allows the Microsoft VM to use the normal uninstrumented JIT allocation helpers.

JVM_INIT_OPT_FP_SAFE_
METHOD_CALLS
0x1 The monitor agrees to preserve floating point state during MethodEntry, MethodExit, and MethodExit2 callbacks. If the monitor modifies floating point state, operation of the profilee may be adversely affected.
JVM_INIT_OPT_GC_SAFE_
METHOD_CALLS
0x2 The monitor will not enable garbage collection during MethodEntry and MethodExit2 callbacks. Operations that enable garbage collection include calling any VM APIs, and directly or indirectly causing Java code to execute. IJavaEventMonitorIDInfo APIs may be called, except for those that are explicitly noted as enabling garbage collection. (Currently, none of these APIs enable garbage collection.) Performing a garbage collection-enabling operation may have unpredictable effects. A monitor should only enable this option if it intends to perform a small amount of work during method call events and will not make use of externally implemented components.
JVM_INIT_OPT_RETURN_
VALUE_NOT_NEEDED
0x4 The monitor will not call GetMethodExitReturnValue. If the monitor calls this method, it will return E_FAIL.
JVM_INIT_OPT_WONT_TOGGLE
_METHOD_CALL_EVENTS
0x8 The monitor will not toggle JVM_MONITOR_METHOD_CALLS or JVM_MONITOR_SPECIFIC_METHOD_CALLS after initialization by calling SetEventMask. If this is attempted, SetEventMask will return E_FAIL.

Use the settings of JAVA_MONITOR_INIT_OPTIONS during initialization of the Microsoft VM to optimize profiling overhead. Without these options, the VM selects the most general profiling mechanism. By enabling these options, the monitor agrees not to perform certain operations that this general procedure permits, so that a better profiling mechanism may be selected. These options are enabled or disabled by calling SetMonitorInitializationOptions during the monitor's Initialize callback.

Enabling both JVM_INIT_OPT_GC_SAFE_METHOD_CALLS and JVM_INIT_OPT_WONT_TOGGLE_METHOD_CALL_EVENTS produces a substantial improvement in JIT-compiled method call event overhead. Additionally enabling JVM_INIT_OPT_FP_SAFE_METHOD_CALLS and JVM_INIT_OPT_RETURN_VALUE_NOT_NEEDED produces small improvements.

Older event monitor implementations may not be aware of these new initialization options, but may not perform the associated actions and could benefit from the performance improvement. To force an older event monitor to make use of these options, a DWORD value, InitOptions, may be added under the event monitor's registry key. The Microsoft VM will use this value as though the monitor called SetMonitorInitializationOptions.

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