次の方法で共有

API メソッド規則のプロファイリング

  • [アーティクル]

このトピックでは、プロファイラーのコールバックの戻り値と、呼び出し元によって割り当てられるバッファーについて説明します。

コールバックの戻り値

プロファイラーは、共通言語ランタイム (CLR: Common Language Runtime) から生成された各通知に対して、ステータス値を HRESULT として返します。 このステータスの値は S_OK または E_FAIL です。 現在のランタイムでは、ICorProfilerCallback::ObjectReferences メソッドを除き、すべてのコールバックでこのステータス値は無視されます。

呼び出し元によって割り当てられるバッファー

GetAppDomainInfo メソッドなどの呼び出し元によって割り当てられるバッファーを受け取る ICorProfilerInfo のメソッドは、通常、次のシグネチャに準拠します。

HRESULT GetBuffer
(
    [in]  /* Some query information (for example, a name).*/,
    [in]  ULONG32 cBufferSizeStart,
    [out] ULONG32 *pcBufferMax,
    [out] /* TYPE */ InfoBuffer[] 
);

これらのメソッドは、常に次のように動作します。

  • cBufferSizeStart パラメーターには、バッファーに割り当てられている要素の数を指定します。 この値はバッファーのサイズを表し、これはこのメソッドの呼び出し元によって割り当てられます。

  • pcBufferMax パラメーターには、使用可能な要素の総数を設定します。 メソッドから返った時点では、pcBufferMax には、実際に返された要素の数ではなく、返される可能性のあった要素の最大数が設定されています。 したがって、pcBufferMax は呼び出し元が割り当てたバッファーの実際のサイズとは関係ありません。

  • InfoBuffer パラメーターでは、呼び出し元が割り当てたバッファーを指定します。 バッファーは、このメソッドの呼び出し元が作成します。 バッファーのサイズは、cBufferSizeStart で指定します。 メソッドから返った後、このバッファーには可能な限り多くの要素が格納されています。 バッファーに格納できるより多くの要素が使用できる場合があります。 InfoBuffer が null の場合、cBufferSizeStart は 0 である必要があります。 要素が返された場合、メソッドは S_OK を返し、使用可能な要素の総数を pcBufferMax に設定します。

呼び出し元が割り当てるバッファーを使用するには、次の 2 つの方法があります。

  • 1 回引き渡し方式 : 返されるすべての要素を格納するのに十分な大きさであると予想されるバッファーを割り当てます。 バッファーが小さすぎる場合にバッファーを再割り当てできるようにしておく必要があります。 そのようにしないと、データが切り捨てられる場合があります。

  • 2 回引き渡し方式 : この方法では、メソッドを 2 回呼び出します。 最初の呼び出しでは長さ 0 の InfoBuffer パラメーターを渡して、適切なバッファーのサイズを取得します。 その後、バッファーのサイズを pcBufferMax で返された値に設定し、関数を再度呼び出します。

最初の方式の方が高速で、動的な割り当てが行われません。 ただし、バッファーが情報を格納するのに十分な大きさでない場合は、バッファーの再割り当てが必要になることがあります。

2 番目の方式は、2 回の呼び出しと動的な割り当てが伴うので遅くなります。 たとえば、アプリケーションのドメイン名に関するクエリ情報が要求されたものとします。 このメソッドから制御が戻った後で、InfoBuffer がアプリケーション ドメインの完全名を格納できるサイズであることを確認する必要があります。 これを行うには、pcBufferMax が指している値を cBufferSizeStart パラメーターの値と比較します。 pcBufferMax の指す値が cBufferSizeStart の値より大きい場合は、InfoBuffer バッファーの割り当てを増やし、cBufferSizeStart を新しい大きいサイズに更新して、メソッドを再度呼び出します。

省略可能な出力パラメーター

プロファイル API では、メソッドが 1 つの出力パラメーター (メソッドの構文で [out] と指定されているもの) しか持っていない場合を除き、すべての出力パラメーターは省略可能です。 プロファイラーは、関係のないすべての出力パラメーターについて null を渡します。 また、プロファイラーは、出力パラメーターに関連付けられているすべての入力パラメーターについて、一貫した値を渡す必要があります。 たとえば、null の出力パラメーターがデータを格納するバッファーを表す場合、バッファーのサイズを指定する入力パラメーターには、0 を設定する必要があります。

参照

概念

プロファイリングの概要