FunctionIDMapper 関数

2008-09-17

更新 : 2007 年 11 月

関数の特定の識別子が、その関数の enter2/leave2/tailcall2 コールバックで使用される代替 ID に再割り当てされることをプロファイラに通知します。このメソッドは、その関数のコールバックを受信するかどうかをプロファイラに通知するために使用することもできます。

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

パラメータ

funcId
[入力] 再割り当てされる関数識別子。
pbHookFunction
[出力] プロファイラが enter(2)/leave(2)/tailcall(2) コールバックを受け取ることを望む場合は、プロファイラが true に設定した値へのポインタ。それ以外の場合、プロファイラはこの値を false に設定します。

戻り値

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

解説

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

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

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

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