UniqueIDs are opaque handles to items inside the Microsoft VM. The profiler interfaces use UniqueIDs to refer to classes (ClassIDs), class methods (MethodIDs), class fields (FieldIDs), instances of Java objects (ObjectIDs), threads (ThreadIDs), and other objects.
Note that ClassIDs and MethodIDs for a class are not valid after a class is unloaded. An expired UniqueID may be reused by the VM to identify objects of other types. Except for ObjectIDs and StackIDs, the expiration of a UniqueID is indicated by the appropriate event type. For example, a ClassID and all its MethodIDs and FieldIDs expire when a CLASS_UNLOAD event is received.
No UniqueIDs expire during profiler callbacks. All UniqueIDs except ObjectIDs are valid across event callbacks until the profiler returns from the corresponding expiration event callback.
StackIDs become invalid when the identified stack frame returns. StackIDs also become invalid when the ThreadID for the thread the StackID was executing becomes invalid, as indicated by the JVM_EVENT_TYPE_THREAD_DESTROY value of the JVM_EVENT_TYPE enumeration.
UniqueID | Expiration |
ThreadID | JVM_EVENT_TYPE_THREAD_DESTROY. |
StackID | JVM_EVENT_TYPE2_EXCEPTION_UNWIND, or MethodExit or MethodExit2 callbacks. |
ObjectID | Immediate or during heap enumeration upon receipt of the C_END container event. |
ObjectHandleID | Never. Must be explicitly freed by the profiler by using FreeHandlesToObjects, or implicitly by GetObjectsFromHandles. |
MethodID | JVM_EVENT_TYPE_CLASS_UNLOAD for containing class. |
FieldID | JVM_EVENT_TYPE_CLASS_UNLOAD for containing class. |
ClassID | JVM_EVENT_TYPE_CLASS_UNLOAD. |
ObjectIDs are only valid between garbage collections; a different ObjectID may be used for the same object after garbage collection. Consequently, ObjectIDs should only be used during the event callback in which they were provided. Persistent handles obtained using the GetHandlesToObjects method must be used for long-term tracking of objects in memory. The GetObjectFromHandles method may be used to obtain the current ObjectIDs for the objects represented by the handles. Note that owning a persistent handle to an object will not prevent the object from being garbage collected.
The Microsoft VM does not perform parameter validation of any UniqueIDs to improve performance of the profiler and reduce profiling overhead. Profilers should use only IDs that were successfully obtained through callbacks or profiler interfaces.
NULL is a valid ObjectID because it may be successfully provided by a callback method. NULL is not valid for any other type of ID, except where noted. For example, SampleThreadLocation and GetStackTrace allow NULL for an ID parameter to avoid having to always first call GetCurrentThread.