FunctionIDMapper 関数

2011-08-09

関数の特定の識別子が、その関数の FunctionEnter2、FunctionLeave2、および FunctionTailcall2 の各コールバックで使用される代替 ID に再割り当てされる可能性があることをプロファイラーに通知します。また FunctionIDMapper により、プロファイラーはその関数のコールバックを受信するかどうかを示すことができます。

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

パラメーター

funcId
[入力] 再割り当てされる関数識別子。
pbHookFunction
[出力] プロファイラーが FunctionEnter2、FunctionLeave2、および FunctionTailcall2 の各コールバックを受信する場合は true に設定される値へのポインター。それ以外の場合、この値は false に設定されます。

戻り値

プロファイラーは、実行エンジンが代替関数識別子として使用する値を返します。 pbHookFunction で false を返さない限り、戻り値を null にすることはできません。そのようにしないで戻り値を null にすると、プロセスの中止など、予測できない結果が発生します。

解説

FunctionIDMapper 関数はコールバックです。この関数は、プロファイラーにとっていっそう役に立つ他の何らかの識別子に関数 ID を再割り当てするために、プロファイラーによって実装されます。 FunctionIDMapper は、特定の関数に使用される代替 ID を返します。その後、実行エンジンは、プロファイラーの要求を尊重し、従来の関数 ID に加えてこの代替 ID を、FunctionEnter2、FunctionLeave2、および FunctionTailcall2 の各フックの clientData パラメーターでプロファイラーに戻し、フックが呼び出されている関数を示します。

ICorProfilerInfo::SetFunctionIDMapper メソッドを使用して、FunctionIDMapper 関数の実装を指定できます。 ICorProfilerInfo::SetFunctionIDMapper メソッドは 1 回しか呼び出すことができないため、ICorProfilerCallback::Initialize コールバックで呼び出すことをお勧めします。

既定では、ICorProfilerInfo::SetEventMask を使用して COR_PRF_MONITOR_ENTERLEAVE フラグを設定し、ICorProfilerInfo::SetEnterLeaveFunctionHooks または ICorProfilerInfo2::SetEnterLeaveFunctionHooks2 によりフックを設定するプロファイラーは、すべての関数に対して FunctionEnter2、FunctionLeave2、および FunctionTailcall2 の各コールバックを受け取る必要があるものと想定されます。ただし、プロファイラーは、pbHookFunction を false に設定することで、特定の関数についてはこれらのコールバックを受け取らないようにするために、FunctionIDMapper を実装することがあります。

プロファイラーは、プロファイリングされたアプリケーションの複数のスレッドが、同じメソッド/関数を同時に呼び出す場合を許容する必要があります。このような場合、プロファイラーは、同じ FunctionID に対して複数の FunctionIDMapper コールバックを受け取ることがあります。プロファイラーは、同じ FunctionID で複数回呼び出されたときは、このコールバックからの同じ値を必ず返す必要があります。