Edit

FunctionIDMapper Function

  • Article

Notifies the profiler that the given identifier of a function may be remapped to an alternative ID to be used in the FunctionEnter2, FunctionLeave2, and FunctionTailcall2 callbacks for that function. FunctionIDMapper also enables the profiler to indicate whether it wants to receive callbacks for that function.

Syntax

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

Parameters

funcId [in] The function identifier to be remapped.

pbHookFunction [out] A pointer to a value that the profiler sets to true if it wants to receive FunctionEnter2, FunctionLeave2, and FunctionTailcall2 callbacks; otherwise, it sets this value to false.

Return Value

The profiler returns a value that the execution engine uses as an alternative function identifier. The return value cannot be null unless false is returned in pbHookFunction. Otherwise, a null return value will produce unpredictable results, including possibly halting the process.

Remarks

The FunctionIDMapper function is a callback. It is implemented by the profiler to remap a function ID to some other identifier that is more useful for the profiler. The FunctionIDMapper returns the alternate ID to be used for any given function. The execution engine then honors the profiler's request by passing this alternate ID, in addition to the traditional function ID, back to the profiler in the clientData parameter of the FunctionEnter2, FunctionLeave2, and FunctionTailcall2 hooks, to identify the function for which the hook is being called.

You can use the ICorProfilerInfo::SetFunctionIDMapper method to specify the implementation of the FunctionIDMapper function. You can call the ICorProfilerInfo::SetFunctionIDMapper method only once, and we recommend that you do so in the ICorProfilerCallback::Initialize callback.

By default, it is assumed that a profiler that sets the COR_PRF_MONITOR_ENTERLEAVE flag by using ICorProfilerInfo::SetEventMask, and which sets hooks via ICorProfilerInfo::SetEnterLeaveFunctionHooks or ICorProfilerInfo2::SetEnterLeaveFunctionHooks2, should receive the FunctionEnter2, FunctionLeave2, and FunctionTailcall2 callbacks for every function. However, profilers may implement FunctionIDMapper to selectively avoid receiving these callbacks for certain functions by setting pbHookFunction to false.

Profilers should be tolerant of cases where multiple threads of a profiled application are calling the same method/function simultaneously. In such cases, the profiler may receive multiple FunctionIDMapper callbacks for the same FunctionID. The profiler should be certain to return the same values from this callback when it is called multiple times with the same FunctionID.

Requirements

Platforms: See System Requirements.

Header: CorProf.idl

Library: CorGuids.lib

.NET Framework Versions: Available since 1.0

See also