FunctionIDMapper-Funktion

Artikel
08/10/2011

Benachrichtigt den Profiler, dass der angegebene Bezeichner einer Funktion einer alternativen ID zugeordnet werden kann, um in den Rückrufen FunctionEnter2, FunctionLeave2 und FunctionTailcall2 dieser Funktion verwendet zu werden. FunctionIDMapper ermöglicht dem Profiler auch anzugeben, ob er Rückrufe für diese Funktion empfangen will.

UINT_PTR __stdcall FunctionIDMapper (
    [in]  FunctionID  funcId, 
    [out] BOOL       *pbHookFunction
);

Parameter

funcId
[in] Der Funktionsbezeichner, der neu zugeordnet werden soll.
pbHookFunction
[out] Ein Zeiger auf einen Wert, den der Profiler auf true festlegt, wenn er die Rückrufe FunctionEnter2, FunctionLeave2 und FunctionTailcall2 empfangen möchte. Andernfalls wird der Wert auf false festgelegt.

Rückgabewert

Der Profiler gibt einen Wert zurück, den das Ausführungsmodul als alternativen Funktionsbezeichner verwendet. Der Rückgabewert darf nicht NULL sein, es sei denn, in pbHookFunction wird false zurückgegeben. Andernfalls führt ein Rückgabewert von NULL zu unvorhersehbaren Ergebnissen, einschließlich des möglichen Anhaltens des Prozesses.

Hinweise

Die FunctionIDMapper-Funktion ist ein Rückruf. Sie wird vom Profiler implementiert, um eine Funktions-ID einem anderen Bezeichner neu zuzuordnen, der für den Profiler nützlicher ist. Der FunctionIDMapper gibt die alternative ID zurück, die für jede gegebene Funktion verwendet werden sollte. Das Ausführungsmodul berücksichtigt dann die Anforderung des Profilers, indem diese alternative ID zusätzlich zur herkömmlichen Funktions-ID an den Profiler im clientData-Parameter der FunctionEnter2-, FunctionLeave2- und FunctionTailcall2-Hooks zurück übergeben wird, um die Funktion zu identifizieren, für die der Hook aufgerufen wird.

Mit der ICorProfilerInfo::SetFunctionIDMapper-Methode können Sie die Implementierung der FunctionIDMapper-Funktion festlegen. Sie können die ICorProfilerInfo::SetFunctionIDMapper-Methode nur einmal aufrufen, und es wird empfohlen, dies im ICorProfilerCallback::Initialize-Rückruf durchzuführen.

Es wird standardmäßig davon ausgegangen, dass ein Profiler, der das COR_PRF_MONITOR_ENTERLEAVE-Flag durch Verwendung von ICorProfilerInfo::SetEventMask und Hooks über ICorProfilerInfo::SetEnterLeaveFunctionHooks oder ICorProfilerInfo2::SetEnterLeaveFunctionHooks2 festlegt, die FunctionEnter2-, FunctionLeave2- und FunctionTailcall2-Rückrufe für jede Funktion erhalten sollte. Profiler können jedoch FunctionIDMapper implementieren, um den Erhalt dieser Rückrufe in ausgewählten Fällen für bestimmte Funktionen zu vermeiden, indem pbHookFunction auf false gesetzt wird.

Profiler sollten tolerant auf Fälle reagieren, bei denen mehrere Threads einer Anwendung mit Profil dieselbe Methode/Funktion gleichzeitig aufrufen. In diesen Fällen erhält der Profiler möglicherweise mehrere FunctionIDMapper-Rückrufe für die gleiche FunctionID. Es sollte sichergestellt sein, dass der Profiler die gleichen Werte von diesem Rückruf zurückgibt, wenn er mehrere Male mit der gleichen FunctionID aufgerufen wird.