ICorProfilerCallback2::RootReferences2-Methode

Artikel
08/10/2011

Benachrichtigt den Profiler über Stammverweise, nachdem eine Garbage Collection erfolgt ist. Diese Methode ist eine Erweiterung der ICorProfilerCallback::RootReferences-Methode.

HRESULT RootReferences2(
    [in] ULONG  cRootRefs,
    [in, size_is(cRootRefs)] ObjectID rootRefIds[],
    [in, size_is(cRootRefs)] COR_PRF_GC_ROOT_KIND rootKinds[],
    [in, size_is(cRootRefs)] COR_PRF_GC_ROOT_FLAGS rootFlags[],
    [in, size_is(cRootRefs)] UINT_PTR rootIds[]);

Parameter

cRootRefs
[in] Die Anzahl der Elemente in den Arrays rootRefIds, rootKinds, rootFlags und rootIds.
rootRefIds
[in] Ein Array von Objekt-IDs, die entweder auf ein statisches Objekt oder auf ein Objekt im Stapel verweisen. Elemente im rootKinds-Array stellen Informationen bereit, um entsprechende Elemente im rootRefIds-Array zu klassifizieren.
rootKinds
[in] Ein Array von COR_PRF_GC_ROOT_KIND-Werten, die den Typ des Garbage Collection-Stammverweises angeben.
rootFlags
[in] Ein Array von COR_PRF_GC_ROOT_FLAGS-Werten, die die Eigenschaften des Garbage Collection-Stammverweises beschreiben.
rootIds
[in] Ein Array von UINT_PTR-Werten, die auf eine ganze Zahl verweisen, die je nach Wert des rootKinds-Parameters zusätzliche Informationen zum Garbage Collection-Stammverweis enthalten.

Wenn es sich beim Typ des Stammverweises um einen Stapel handelt, ist die Stamm-ID für die Funktion bestimmt, die die Variable enthält. Wenn diese Stamm-ID gleich 0 (null) ist, handelt es sich bei der Funktion um eine unbenannte CLR-interne Funktion. Wenn es sich beim Typ des Stammverweises um ein Handle handelt, ist die Stamm-ID für das Garbage Collection-Handle bestimmt. Für die anderen Stammreferenztypen ist die ID ein nicht transparenter Wert und sollte ignoriert werden.

Hinweise

Die Arrays rootRefIds, rootKinds, rootFlags und rootIds sind parallele Arrays. Das heißt, rootRefIds[i], rootKinds[i], rootFlags[i] und rootIds[i] betreffen alle denselben Stammverweis.

Sowohl RootReferences als auch RootReferences2 werden aufgerufen, um den Profiler zu benachrichtigen. Profiler implementieren normalerweise die eine oder die andere Methode, aber nicht beide. Der Grund dafür ist, dass die in RootReferences2 übergebenen Informationen eine Obermenge der in RootReferences übergebenen Informationen sind.

Einträge in rootRefIds können 0 (null) sein, was darauf hinweist, dass der entsprechende Stammverweis NULL ist und nicht auf ein Objekt im verwalteten Heap verweist.

Die von RootReferences2 zurückgegebenen Objekt-IDs sind während des Rückrufs selbst nicht gültig, weil die Garbage Collection zu diesem Zeitpunkt unter Umständen noch Objekte von alten Adressen an neue Adressen verschiebt. Deshalb dürfen Profiler nicht versuchen, Objekte während eines RootReferences2-Aufrufs zu überprüfen. Wenn ICorProfilerCallback2::GarbageCollectionFinished aufgerufen wird, wurden alle Objekte an die neuen Speicherorte verschoben und können sicher überprüft werden.