Convenzioni dei metodi dell'API di profilatura
In questo argomento vengono illustrati i valori restituiti dal callback del profiler e i buffer allocati dal chiamante.
Valori restituiti dal callback
Un profiler restituisce un valore di stato come HRESULT per ogni notifica generata da Common Language Runtime (CLR). Questo valore di stato può essere S_OK o E_FAIL. Attualmente il runtime ignora il valore di stato in ogni callback, fatta eccezione per il metodo ICorProfilerCallback::ObjectReferences.
Buffer allocati dal chiamante
I metodi ICorProfilerInfo che accettano buffer allocati dal chiamante, ad esempio il metodo GetAppDomainInfo, sono in genere conformi alla firma seguente:
HRESULT GetBuffer
(
[in] /* Some query information (for example, a name).*/,
[in] ULONG32 cBufferSizeStart,
[out] ULONG32 *pcBufferMax,
[out] /* TYPE */ InfoBuffer[]
);
Questi metodi si comportano sempre nel modo indicato di seguito:
Il parametro cBufferSizeStart specifica il numero di elementi allocati nel buffer. Questo valore rappresenta la dimensione del buffer allocata dal chiamante di questo metodo.
Il parametro pcBufferMax è impostato sul numero complessivo di elementi disponibili. Dopo il completamento del metodo, il parametro pcBufferMax viene impostato sul numero massimo di elementi che sarebbe stato possibile restituire, invece che sul numero di elementi effettivamente restituiti. Pertanto, il parametro pcBufferMax è indipendente dalla dimensione effettiva del buffer allocato dal chiamante.
Il parametro InfoBuffer specifica il buffer allocato dal chiamante e viene creato dal chiamante di questo metodo. La dimensione è specificata dal parametro cBufferSizeStart. Un volta completato il metodo, nel buffer verrà inserito il maggior numero di elementi possibile. Il numero di elementi disponibili potrebbe essere superiore a quello che è possibile inserire nel buffer. Se InfoBuffer è null, cBufferSizeStart deve essere 0. Se vengono restituiti elementi, il metodo restituisce S_OK e imposta pcBufferMax sul numero complessivo di elementi disponibili.
I buffer allocati dal chiamante possono essere utilizzati in due modi:
Metodo a passaggio singolo: consiste nell'allocare un buffer che si ritiene abbastanza grande da contenere tutti gli elementi restituiti. È necessario essere pronti a riallocare il buffer nel caso in cui fosse troppo piccolo. In caso contrario, potrebbe verificarsi il troncamento dei dati.
Metodo a passaggio doppio: in alternativa, chiamare il metodo due volte. Innanzitutto, effettuare la chiamata con un parametro InfoBuffer di lunghezza zero per ottenere la dimensione del buffer corretta. Quindi impostare la dimensione del buffer sul valore restituito nel parametro pcBufferMax e chiamare nuovamente la funzione.
Il primo metodo è più veloce ed evita l'allocazione dinamica. Tuttavia, potrebbe essere necessario necessario riallocare il buffer se non è abbastanza grande da contenere le informazioni.
Il secondo metodo è più lento perché implica due chiamate e l'allocazione dinamica. Ad esempio, si presupponga che le informazioni di query richieste fossero relative al nome di un dominio dell'applicazione. Dopo il completamento del metodo, è necessario verificare che il buffer InfoBuffer fosse abbastanza grande da contenere il nome completo del dominio dell'applicazione. A tal fine, confrontare il valore al quale punta pcBufferMax con il valore del parametro cBufferSizeStart. Se il parametro pcBufferMax punta a un valore maggiore di cBufferSizeStart, allocare un buffer InfoBuffer più grande, aggiornare il parametro cBufferSizeStart con la nuova dimensione e chiamare nuovamente il metodo.
Parametri di output facoltativi
Nell'API di analisi, tutti i parametri di output (specificati da [out] nella sintassi del metodo) sono facoltativi, a meno che un metodo non contenga un solo parametro di output. Un profiler passa un valore Null per qualsiasi parametro di output a cui non è interessato. Il profiler deve inoltre passare valori coerenti per qualsiasi parametro di input associato al parametro di output. Ad esempio, se un parametro di output null rappresenta un buffer in cui inserire i dati, il parametro di input che specifica la dimensione del buffer dovrà essere impostato su 0.