The SampleThreadLocation method of the IJavaEventMonitorIDInfo2 interface obtains sample profiling information. This method is called by a profiler program. The profiler must pass the ThreadID it is interested in.
The SampleThreadLocation method is implemented only by the IJavaEventMonitorIDInfo2 and IJavaEventMonitorIDInfo3 interfaces.
HRESULT SampleThreadLocation(ThreadID thread_id, JVM_METHOD_SAMPLE *psample);
A sampling structure filled in with current information at that precise moment.
[in] thread_id | The ThreadID that the profiler is interested in sampling data on. |
[in, out] *psample | The sampling structure filled in with the current information. Note that the first member of this structure (flags) is used upon entry to pass a list of fields that the profiler is interested in getting filled in. Upon exit, this first structure member (flags) indicates which fields contain valid information. |
This method samples the current method for the given thread. If the method is not known, a "guess" (a recent caller, nearest native caller, and so on) might be returned, along with an estimate of the accuracy. A precise sample can always be obtained using the GetStackTrace method. This method is slower, however, and might require code to be executed before reporting stack frames. The JVM_MONITOR_SAMPLING event notification category is not required to be enabled, but its use will improve the ability to provide accurate samples at the expense of some overhead on non—JIT-compiled method calls.
To collect sample data, a profiler must arrange a way to call the SampleThreadLocation method of the IJavaEventMonitorIDInfo2 interface at periodic intervals. A profiler application is free to use a variety of methods to make periodic calls to SampleThreadLocation. The profiler can call this method in a loop followed by Win32 Sleep function calls. The profiler can set a short timer and call this method when the timer expires. The profiler can use other schemes (waiting for other events) to trigger when to call this method.
To call the SampleThreadLocation method, a profiler must pass in a JVM_METHOD_SAMPLE structure that will receive the sample data. The fields in this structure are defined as shown in the following table.
Variable Type | Structure Member | Comments |
DWORD | Flags | Upon entry, this field represents a bitmask of flags from the JVM_METHOD_SAMPLE_FLAGS enumeration indicating which structure fields that the Microsoft VM should fill in. Upon return, this field represents a bitmask of flags indicating which structure fields contain valid data. |
JVM_METHOD_SAMPLE_ACCURACY | Accuracy | An estimate of the relative accuracy of the information in this structure. |
StackID | stack_id | The stack frame for the currently executing location. |
MethodID | Method_id | The method for which the code is executing. |
JVM_METHOD_SAMPLE_LOCATION | Location_type | The type (activity) of the code at the location, if known. |
DWORD | Ip | The instruction pointer at the time of the sample. |
DWORD | Sp | The stack pointer at the time of the sample. |
DWORD | pc_offset | The bytecode offset at the time of the sample if the method is currently interpreted. |
Upon entry, the flag's DWORD in the JVM_METHOD_SAMPLE structure indicates which fields in the structure are to be filled in by the Microsoft VM. Upon exit, the flag's member indicates which structure members were filled in with data. The allowable value for the JVM_METHOD_SAMPLE_FLAGS can be a combination of the enumeration constants or one of the predefined combinations.
Constant | Value | Description |
JVM_SAMPLE_STACK_ID | 0x1 | On entry to SampleThreadLocation, this value indicates that the StackID should be included in the sampled data. As a returned value from this method, this value indicates that the StackID is valid. |
JVM_SAMPLE_METHOD_ID | 0x2 | On entry to SampleThreadLocation, this value indicates that the MethodID should be included the sampled data. As a returned value from this method, this value indicates that the MethodID is valid. |
JVM_SAMPLE_LOCATION | 0x4 | On entry to SampleThreadLocation, this value indicates that the JVM_METHOD_SAMPLE_LOCATION (location_type) should be included in the sampled data. As a returned value from this method, this value indicates that the location_type is valid. |
JVM_SAMPLE_GENERATED_CODE | 0x8 | This value is only used as a return value to indicate that the sampled ip was in VM-generated code. If possible, the ip field in the JVM_METHOD_SAMPLE structure will be filled in with the caller of the generated code, which can also be generated code. |
JVM_SAMPLE_PC | 0x10 | On entry to SampleThreadLocation, this value indicates that the pc_offset (bytecode offset for an interpreted method) should be included in the sampled data. As a returned value from this method, this value indicates that the pc_offset is valid. |
ALL_JVM_SAMPLE_FIELDS | 0x17 | This value is a combination of JVM_SAMPLE_STACK_ID, JVM_SAMPLE_METHOD_ID, JVM_SAMPLE_LOCATION, and JVM_SAMPLE_PC. |
ALL_JVM_SAMPLE_FLAGS | 0x1F | This value is a combination of JVM_SAMPLE_STACK_ID, JVM_SAMPLE_METHOD_ID, JVM_SAMPLE_LOCATION, JVM_SAMPLE_PC, and JVM_SAMPLE_GENERATED_CODE. |
The accuracy member indicates an estimate of the relative accuracy of the information returned into this structure by the Microsoft VM. The accuracy member can be one of the enumeration constants in the following table.
Enumeration | Value | Description |
JVM_SAMPLE_NONE | 0 | A sample could not be obtained. |
JVM_SAMPLE_POOR | 1 | The sample is not very accurate. |
JVM_SAMPLE_EXACT | 100 | The sample is 100% accurate. |
The location_type indicates where the Java process was executing when the Microsoft VM captured the sampled data. It may be one of the enumeration constants in JVM_METHOD_SAMPLE_LOCATION_TYPES.
Constant | Value | Description |
JVM_LOCATION_UNKNOWN | 0 | The sampled location could not be determined. |
JVM_LOCATION_JIT | 1 | The sampled location is in JIT-compiled code. |
JVM_LOCATION_NATIVE | 2 | The sampled location is in miscellaneous native code (VM, DLL, OS, and so on). |
JVM_LOCATION_GC | 3 | The sampled location is performing a garbage collection. |
JVM_LOCATION_COMPILER | 4 | The sampled location is compiling a method or performing on-first-call tasks for a method. |
JVM_LOCATION_LOADER | 5 | The sampled location is performing a VM class loader-related task. |
JVM_LOCATION_DEBUGGER | 6 | The sampled location is performing a VM debugger-related task. |
JVM_LOCATION_SECURITY | 7 | The sampled location is performing a VM security-related task. |
JVM_LOCATION_PROFILER | 8 | The sampled location is performing a VM profiler-related task. |
JVM_LOCATION_BLOCKING | 9 | The sampled location is in a wait state. |