The Java profiler interfaces assist in the analysis of Java code for speed, memory use, redundancy, and other performance factors. The profiler interfaces are Component Object Model (COM) objects and interfaces implemented by the Microsoft VM. The profiler interfaces support any number of concurrently operating event monitors, thus profiling both execution time and memory usage. These interfaces can also profile components that mix Java classes with Microsoft® Win32® native code.
The profiler interfaces are organized into the following categories.
Category | Purpose |
Event Monitor Information | Interfaces called by the profiler to request event notification from the Microsoft VM and request information when specific events occur. |
Event Notification | Callback interfaces implemented by the profiler through which the Microsoft VM notifies the profiler of various events as they occur. |
Heap Monitor Information | The interface called by the profiler to gather information from the Microsoft VM regarding heap memory usage of the Java code being profiled. |
Heap Monitor Notification | Callback interfaces implemented by the profiler through which the Microsoft VM notifies the profiler of memory and object allocation information. |
This section contains the following topics:
Enabling Profiling in the Microsoft VM discusses the two ways to enable profiling.
Registering with the Microsoft VM for Event Notification shows how to register and initialize an event monitor.
Implementing Event Monitor Information Interfaces gives an overview of the interfaces and methods a profiler must call to use the other optional interfaces.
Implementing Event Notification Interfaces describes the callback interfaces through which the Microsoft VM communicates with the profiler.
Using the Heap Monitor Interfaces gives an overview of those interfaces that allow a memory profiler to collect detailed information on heap memory usage and garbage collection activity for a Java process.
The profiler sets event notification masks and communicates with the Microsoft VM by calling methods on COM objects implemented by the VM. These event masks are passed to the Microsoft VM, indicating the events for which the profiler wants to receive notifications.
The Microsoft VM runtime notifies the profiler about events, and provides requested information in response to method calls made by the profiler on COM objects implemented by the VM.
Under the profiler interfaces, the Microsoft VM uses event types and unique identifiers (UniqueIDs) for notification. These identifiers or handles are specific to the Microsoft VM. In contrast to the VM's debugger interfaces, the profiler interfaces use UniqueIDs rather than COM objects to speed up event notification callbacks, which pass these UniqueIDs as parameters.
The profiler interfaces implemented by the Microsoft VM contain methods that query and set event masks for event notification. These methods return method, class, and object information based on UniqueIDs. The COM objects and interfaces implemented by a profiler use similar methods that notify the profiler of various events, such as class loading and unloading and method entry and exit.
To use the profiler interfaces, you must enable profiling in the Microsoft VM before the Java application or applet begins its execution. You enable profiling by setting environment variables or by creating specific Win32 registry keys before the Java application or applet begins.
A profiler program or event monitor must register itself on the local computer so it can be started by the Microsoft VM when a Java process begins execution.
Using Distributed COM (DCOM) to support remote profiling is not suggested for the following reasons:
Because the profiler interfaces are based on COM, some general considerations apply when calling the interfaces that are implemented by the Microsoft VM.
When a profiler receives [out] parameters from a method that are pointers to non-primitive data types, the profiler needs to call the CoTaskMemFree function when done with these pointers to free the memory allocated for them by the Microsoft VM.
If the profiler continues to use any COM objects that are created as parameters to a method, the reference count for that object may need to be incremented to ensure that the object remains viable for the duration of the method call. This can be accomplished by calling the AddRef method on the COM interface. The profiler decrements the reference count on the object using the Release method when this object is no longer needed.
The profiler COM interfaces implemented by the Microsoft VM use the free-threading model. Events are dispatched from within the VM or on a thread that is making a profiler method call. Interface methods implemented by the VM can be called any time from any thread that has been CoInitialized.
The examples in this section illustrate the use of the profiler interfaces. They are written in C++ and use local COM objects.
The Microsoft SDK for Java includes samples that illustrate how to use these profiler interfaces. The samples are in C++, and are installed under the %SDKDIR%\Samples\Profiler subdirectory of the Microsoft SDK for Java. For more information, see the Profiler Samples Overview. For information about other samples in this SDK, see the Samples Overview.
Debugging and Profiling Java Applications