다음을 통해 공유

프로파일링 API 메서드 규칙

  • 아티클

이 항목에서는 프로파일러 콜백 반환 값 및 호출자 할당 버퍼에 대해 설명합니다.

콜백 반환 값

프로파일러는 CLR(공용 언어 런타임)에서 발생하는 각 알림에 대해 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를 사용 가능한 총 요소 수로 설정합니다.

호출자 할당 버퍼를 사용하는 방법에는 다음과 같은 두 가지가 있습니다.

  • 단일 단계 방법: 반환되는 모든 요소를 포함할 수 있는 크기를 예상 버퍼의 크기로 할당합니다. 이 크기가 너무 작은 것으로 밝혀지는 경우 다시 할당할 수 있어야 합니다. 그렇지 않으면 데이터가 잘릴 수 있습니다.

  • 이중 단계 방법: 또는 메서드를 두 번 호출할 수도 있습니다. 먼저 길이가 0인 InfoBuffer 매개 변수와 함께 호출하여 올바른 버퍼 크기를 얻습니다. 그런 다음 버퍼 크기를 pcBufferMax에서 반환된 값으로 설정하고 함수를 다시 호출합니다.

첫째 방법은 더 빠르고 동적 할당을 방지할 수 있습니다. 그러나 버퍼 크기가 부족하여 정보를 포함할 수 없는 경우 버퍼를 다시 할당해야 합니다.

둘째 방법은 두 번 호출하고 동적 할당이 발생하기 때문에 더 느립니다. 예를 들어 요청된 쿼리 정보가 응용 프로그램 도메인 이름과 관련이 있는 경우, 이 메서드에서 반환된 후 InfoBuffer가 응용 프로그램 도메인의 전체 이름을 포함할 만큼 충분히 큰지 확인해야 합니다. 이렇게 하려면 pcBufferMax가 가리키는 값을 cBufferSizeStart 매개 변수의 값과 비교합니다. pcBufferMax가 cBufferSizeStart보다 큰 값을 가리키면 더 큰 InfoBuffer 버퍼를 할당하고 더 큰 새 값으로 cBufferSizeStart를 업데이트한 다음 메서드를 다시 호출합니다.

선택적 출력 매개 변수입니다.

프로파일링 API에서 메서드에 출력 매개 변수가 한 개만 있는 경우가 아니면 메서드 구문의 [out]에 의해 지정된 모든 출력 매개 변수는 선택적 요소입니다. 프로파일러에서는 불필요한 출력 매개 변수에 대해 null을 전달하며 출력 매개 변수와 연결된 입력 매개 변수에 대해서도 일관된 값을 전달해야 합니다. 예를 들어 null 출력 매개 변수가 데이터로 채울 버퍼를 나타내는 경우 버퍼 크기를 지정하는 입력 매개 변수를 0으로 설정해야 합니다.

참고 항목

개념

프로파일링 개요