ICorProfilerInfo3::RequestProfilerDetach メソッド

[アーティクル]
08/09/2011

プロファイラーをデタッチするようにランタイムに指示します。

HRESULT RequestProfilerDetach(
   [in] DWORD    dwExpectedCompletionMilliseconds);

パラメーター

dwExpectedCompletionMilliseconds
[入力] プロファイラーをアンロードするのが安全かどうかを確認するチェックを行うまでに共通言語ランタイム (CLR: Common Language Runtime) が待機する時間 (ミリ秒) (このパラメーターの詳細については、「解説」と「プロファイラーのアタッチとデタッチ」を参照してください)。

戻り値

このメソッドは、次の特定の HRESULT と、メソッドの失敗を示す HRESULT エラーも返します。

HRESULT	説明
S_OK	デタッチ要求は有効です。またデタッチプロシージャは別のスレッドで継続しています。デタッチが完了すると、ProfilerDetachSucceeded イベントが発行されます。
E_ CORPROF_E_CALLBACK3_REQUIRED	プロファイラーは、デタッチ操作をサポートするために実装する必要がある ICorProfilerCallback3 インターフェイスに対する IUnknown::QueryInterface に失敗しました。デタッチは試行されませんでした。
CORPROF_E_IMMUTABLE_FLAGS_SET	プロファイラーが起動時に変更できないフラグを設定しているため、デタッチを実行できません。デタッチは試行されませんでした。プロファイラーは完全にアタッチされたままです。
CORPROF_E_IRREVERSIBLE_INSTRUMENTATION_PRESENT	プロファイラーで、インストルメント化した Microsoft Intermediate Language (MSIL) コードが使用されているか、enter/leave フックが挿入されているため、デタッチを実行できません。デタッチは試行されませんでした。プロファイラーは完全にアタッチされたままです。メモインストルメント化した MSIL とは、SetILFunctionBody メソッドを使用してプロファイラーが提示するコードです。
CORPROF_E_RUNTIME_UNINITIALIZED	マネージアプリケーションでランタイムがまだ、初期化されていません (つまり、ランタイムは完全には読み込まれていません)。このエラーコードは、プロファイラーコールバックの ICorProfilerCallback::Initialize メソッド内でデタッチが要求されたときに返されることがあります。
CORPROF_E_UNSUPPORTED_CALL_SEQUENCE	サポートされていないタイミングで RequestProfilerDetach が呼び出されました。このような状況になるのは、ガベージコレクションを許容できない ICorProfilerCallback メソッドまたは ICorProfilerCallback メソッド内からではなく、マネージスレッドでメソッドが呼び出された場合です。詳細については、「CORPROF_E_UNSUPPORTED_CALL_SEQUENCE HRESULT」を参照してください。

解説

デタッチプロシージャ中に、デタッチスレッド (プロファイラーのデタッチのために作成されたスレッド) は、すべてのスレッドがプロファイラーのコードを終了したかどうかをときどきチェックします。プロファイラーは、退避が終了するまでの予想時間を、dwExpectedCompletionMilliseconds パラメーターを介して提供する必要があります。使用に適した値は、特定の ICorProfilerCallback* メソッド内でプロファイラーが使う通常の時間です。この値は、プロファイラーが使うと想定される最大時間の半分未満にしないでください。

デタッチスレッドでは dwExpectedCompletionMilliseconds を使用して、プロファイラーのコールバックコードがすべてのスタックからポップされたかどうかをチェックする前にスリープする時間の長さを指定します。次のアルゴリズムの詳細は今後の CLR のリリースで変更される可能性がありますが、これはプロファイラーをアンロードしても安全なタイミングを決定するために dwExpectedCompletionMilliseconds を利用する一例です。デタッチスレッドはまず dwExpectedCompletionMilliseconds ミリ秒間、スリープ状態になります。スリープから復帰した後に、プロファイラーのコールバックコードがまだ存在することが CLR で検出された場合、今回は 2 倍の dwExpectedCompletionMilliseconds ミリ秒間、デタッチスレッドが再度スリープ状態になります。この 2 回目のスリープから復帰した後に、プロファイラーのコールバックコードがまだ存在することが CLR で検出された場合、再チェックが行われる前に CLR のデタッチスレッドが 10 分間、スリープ状態になります。デタッチスレッドは継続して 10 分ごとに再チェックします。

プロファイラーが dwExpectedCompletionMilliseconds を 0 (ゼロ) に指定している場合、CLR は既定値 5000 を使用します。この設定では、チェックが 5 秒後に行われ、その次は 10 秒後に、それ以降は 10 分ごとに再チェックが行われます。

プロファイラーのデタッチの詳細については、「プロファイラーのアタッチとデタッチ」を参照してください。