Conventions de méthode de l'API de profilage
Cette rubrique décrit les valeurs de retour du rappel du profileur et les mémoires tampons allouées par l'appelant.
Valeurs de retour du rappel
Un profileur retourne une valeur d'état en tant que HRESULT pour chaque notification que le Common Language Runtime (CLR) déclenche. Cette valeur d'état peut être S_OK ou E_FAIL. Actuellement, le runtime ignore la valeur d'état dans chaque rappel, à l'exception de la méthode ICorProfilerCallback::ObjectReferences.
Mémoires tampons allouées par l'appelant
Les méthodes ICorProfilerInfo qui prennent des mémoires tampons allouées par l'appelant, telles que la méthode GetAppDomainInfo, concordent généralement avec la signature suivante :
HRESULT GetBuffer
(
[in] /* Some query information (for example, a name).*/,
[in] ULONG32 cBufferSizeStart,
[out] ULONG32 *pcBufferMax,
[out] /* TYPE */ InfoBuffer[]
);
Ces méthodes se comportent toujours de la manière suivante :
Le paramètre cBufferSizeStart spécifie le nombre d'éléments alloués dans la mémoire tampon. Cette valeur représente la taille de la mémoire tampon qui est allouée par l'appelant de cette méthode.
Le paramètre pcBufferMax a pour valeur le nombre total d'éléments disponibles. Une fois que la méthode a retourné une valeur, pcBufferMax a pour valeur le nombre maximal d'éléments qui auraient pu être retournés à la place du nombre d'éléments qui ont réellement été retournés. pcBufferMax est par conséquent indépendant de la grandeur réelle de la mémoire tampon allouée par l'appelant.
Le paramètre InfoBuffer spécifie la mémoire tampon allouée par l'appelant. Il est créé par l'appelant de cette méthode. Sa taille est spécifiée par cBufferSizeStart. Une fois que la méthode a retourné une valeur, cette mémoire tampon est remplie avec autant d'éléments que possible. Le nombre d'éléments disponibles peut être supérieur à celui pouvant figurer dans la mémoire tampon. Si InfoBuffer a la valeur null, cBufferSizeStart doit être égal à 0. Si des éléments sont retournés, la méthode retourne S_OK et affecte pcBufferMax au nombre total d'éléments disponibles.
Vous pouvez utiliser des mémoires tampon allouées par l'appelant de deux façons :
Méthode en une seule étape : allouez une mémoire tampon qui est censée être suffisamment grande pour contenir tous les éléments retournés. Attendez-vous à réallouer de la mémoire tampon si celle-ci s'avère être trop petite. Sinon, une troncation de données risque de se produire.
Méthode en deux étapes : vous avez également la possibilité d'appeler la méthode à deux reprises. Appelez une première fois la fonction avec un paramètre InfoBuffer de longueur nulle pour obtenir la taille de la mémoire tampon correcte. Affectez ensuite la valeur retournée dans pcBufferMax à la taille de la mémoire tampon et appelez de nouveau la fonction.
La première méthode est plus rapide et évite l'allocation dynamique. Vous pouvez toutefois être amené à réaffecter de la mémoire tampon si celle-ci n'est pas suffisamment grande pour contenir les informations.
La seconde méthode est plus lente, car elle nécessite deux appels et une allocation dynamique. Par exemple, supposons que les informations de requête demandées concernent le nom d'un domaine d'application. Une fois que cette méthode a retourné une valeur, vous devez vérifier qu'InfoBuffer était suffisamment grand pour contenir le nom complet du domaine d'application. Pour ce faire, comparez la valeur pointée par pcBufferMax avec celle du paramètre cBufferSizeStart. Si pcBufferMax pointe vers une valeur supérieure à cBufferSizeStart, allouez une mémoire tampon InfoBuffer plus grande, mettez à jour cBufferSizeStart avec la nouvelle taille plus grande et appelez de nouveau la méthode.
Paramètres de sortie optionnels
Dans l'API de profilage, tous les paramètres de sortie (spécifiés par [out] dans la syntaxe de méthode) sont facultatifs, à moins qu'une méthode ait un seul paramètre de sortie. Un profileur passe la valeur null pour tous les paramètres de sortie qui ne l'intéressent pas. Le profileur doit également passer des valeurs cohérentes pour tous les paramètres d'entrée qui sont associés au paramètre de sortie. Par exemple, si un paramètre de sortie null représente une mémoire tampon à remplir avec des données, le paramètre d'entrée qui spécifie la taille de la mémoire tampon doit avoir la valeur 0.