Uređivanje

Dijeli putem

ICorProfilerInfo3::RequestProfilerDetach Method

  • Članak

Instructs the runtime to detach the profiler.

Syntax

HRESULT RequestProfilerDetach(
   [in] DWORD    dwExpectedCompletionMilliseconds);

Parameters

dwExpectedCompletionMilliseconds [in] The length of time, in milliseconds, the common language runtime (CLR) should wait before checking to see whether it is safe to unload the profiler.

Return Value

This method returns the following specific HRESULTs as well as HRESULT errors that indicate method failure.

HRESULT Description
S_OK The detach request is valid, and the detach procedure is now continuing on another thread. When the detach is fully complete, a ProfilerDetachSucceeded event is issued.
E_CORPROF_E_CALLBACK3_REQUIRED The profiler failed an IUnknown::QueryInterface attempt for the ICorProfilerCallback3 interface, which it must implement to support the detach operation. Detach was not attempted.
CORPROF_E_IMMUTABLE_FLAGS_SET Detachment is impossible because the profiler set immutable flags at startup. Detachment was not attempted; the profiler is still fully attached.
CORPROF_E_IRREVERSIBLE_INSTRUMENTATION_PRESENT Detachment is impossible because the profiler used instrumented common intermediate language (CIL) code, or inserted enter/leave hooks. Detachment was not attempted; the profiler is still fully attached.

Note Instrumented CIL is code is code that is provided by the profiler using the SetILFunctionBody method.
CORPROF_E_RUNTIME_UNINITIALIZED The runtime has not been initialized yet in the managed application. (That is, the runtime has not been fully loaded.) This error code may be returned when detachment is requested inside the profiler callback's ICorProfilerCallback::Initialize method.
CORPROF_E_UNSUPPORTED_CALL_SEQUENCE RequestProfilerDetach was called at an unsupported time. This occurs if the method is called on a managed thread but not from within an ICorProfilerCallback method or from within an ICorProfilerCallback method that cannot tolerate a garbage collection. For more information, see CORPROF_E_UNSUPPORTED_CALL_SEQUENCE HRESULT.

Remarks

During the detach procedure, the detach thread (the thread created specifically for detaching the profiler) occasionally checks whether all threads have exited the profiler’s code. The profiler should provide an estimate of how long this should take through the dwExpectedCompletionMilliseconds parameter. A good value to use is the typical amount of time the profiler spends inside any given ICorProfilerCallback* method; this value should not be less than half of the maximum amount of time the profiler expects to spend.

The detach thread uses dwExpectedCompletionMilliseconds to decide how long to sleep before checking whether profiler callback code has been popped off all stacks. Although the details of the following algorithm may change in future releases of the CLR, it illustrates one way dwExpectedCompletionMilliseconds can be used when determining when it is safe to unload the profiler. The detach thread first sleeps for dwExpectedCompletionMilliseconds milliseconds. If, after awakening from the sleep, the CLR finds that profiler callback code is still present, the detach thread sleeps again, this time for two times dwExpectedCompletionMilliseconds milliseconds. If, after awakening from this second sleep, the detach thread finds that profiler callback code is still present, it sleeps for 10 minutes before checking again. The detach thread continues to recheck every 10 minutes.

If the profiler specifies dwExpectedCompletionMilliseconds as 0 (zero), the CLR uses a default value of 5000, which means that it will perform a check after 5 seconds, again after 10 seconds, and then every 10 minutes thereafter.

Requirements

Platforms: See System Requirements.

Header: CorProf.idl, CorProf.h

Library: CorGuids.lib

.NET Framework Versions: Available since 4

See also