EVENT_DATA 結構

EVENT_DATA 結構描述來自分析或重新記錄工作階段的事件。 Analyze、AnalyzeA、AnalyzeW、Relog、RelogA 或 RelogW 函式階可啟動這些工作階段。

語法

typedef struct EVENT_DATA_TAG
{
    unsigned short          EventId;
    unsigned long long      EventInstanceId;

    long long               TickFrequency;
    long long               StartTimestamp;
    long long               StopTimestamp;
    long long               ExclusiveDurationTicks;
    long long               CPUTicks;
    long long               ExclusiveCPUTicks;
    long long               WallClockTimeResponsibilityTicks;
    long long               ExclusiveWallClockTimeResponsibilityTicks;

    const void*             Data;

    unsigned long           ProcessId;
    unsigned long           ThreadId;
    unsigned short          ProcessorIndex;

    const char*             EventName;
    const wchar_t*          EventWideName;

} EVENT_DATA;

成員

名稱	描述
EventId	此編號可識別事件。 如需事件識別碼清單，請參閱 EVENT_ID。
EventInstanceId	此編號可唯一識別目前在追蹤記錄內的事件。 分析或重新記錄相同的追蹤多次，這個值都不會變更。 使用此欄位來識別相同追蹤傳遞的多個分析或重新記錄中的相同事件。
TickFrequency	評估按刻度測量的持續時間時，每秒使用的刻度數。
StartTimestamp	當事件是活動時，此欄位是該活動開始時所擷取的刻度值。 如果此事件是簡單事件，則此欄位是該事件發生時所擷取的刻度值。
StopTimestamp	當事件是活動時，此欄位是該活動停止時所擷取的刻度值。 如果尚未收到此活動的停止事件，則此欄位為零。 如果此事件是簡單事件，則此欄位為零。
ExclusiveDurationTicks	如果此事件是活動，此欄位是直接在此活動中發生的刻度數目。 但不包括在子活動中發生的刻度數目。 若為簡單事件，此欄位為零。
CPUTicks	如果此事件是活動，此欄位是此活動期間發生的 CPU 刻度數目。 CPU 刻度與一般刻度不同。 只有當 CPU 在活動中執行程式碼時，才會計算 CPU 刻度數。 與該活動相關聯的執行緒處於休眠中時，不會計算 CPU 刻度數。 若為簡單事件，此欄位為零。
ExclusiveCPUTicks	此欄位的意義與 CPUTicks 相同，不同之處在於不包含子活動中發生的 CPU 刻度。 若為簡單事件，此欄位為零。
WallClockTimeResponsibilityTicks	如果此事件是活動，則此欄位是刻度計數，代表此活動對整體時鐘時間的貢獻。 時鐘時間責任刻度與一般刻度不同。 時鐘時間責任會考慮活動之間的平行處理原則。 例如，兩個平行活動可能會有 50 個刻度的持續時間，以及相同的開始和停止時間。 在此情況下，兩者都會獲指派 25 個刻度的時鐘時間責任。 若為簡單事件，此欄位為零。
ExclusiveWallClockTimeResponsibilityTicks	此欄位的意義與 WallClockTimeResponsibilityTicks 相同，不同之處在於不包含子活動的時鐘時間責任刻度。 若為簡單事件，此欄位為零。
Data	指向儲存在事件中的其他資料。 指向的資料類型不同，視 EventId 欄位而定。
ProcessId	發生事件的處理識別碼。
ThreadId	發生事件的執行緒識別碼。
ProcessorIndex	發生事件的 CPU 號碼 (從零開始編製索引)。
EventName	ANSI 字串，其中包含 EventId 識別的實體名稱。
EventWideName	寬字串，其中包含 EventId 識別的實體名稱。

備註

EVENT_DATA 中的許多欄位都包含刻度計數。 C++ Build Insights 使用 Windows 效能計數器作為刻度來源。 刻度計數必須與 TickFrequency 欄位搭配使用，才能轉換成適當的時間單位，例如秒。 請參閱下面的刻度轉換範例。

EVENT_DATA 不包含活動中一般刻度計數的欄位。 若要取得此值，請從 StopTimestamp 減去 StartTimestamp。

EVENT_DATA 是 C API 使用者要使用的一種結構。 對於 C++ API 使用者，事件等類別會自動執行時間轉換。

EVENT_DATA Data 欄位的值取決於其 EventId 欄位的值。 下表說明 Data 的值。 下表可能會遺漏某些實體識別碼。 在此情況下，Data 欄位會設定為 nullptr 或零。

EventId 值	Data 指向的類型
EVENT_ID_BACK_END_PASS	CL_PASS_DATA
EVENT_ID_COMMAND_LINE	const wchar_t
EVENT_ID_COMPILER	INVOCATION_DATA
EVENT_ID_ENVIRONMENT_VARIABLE	NAME_VALUE_PAIR_DATA
EVENT_ID_EXECUTABLE_IMAGE_OUTPUT	FILE_DATA
EVENT_ID_EXP_OUTPUT	FILE_DATA
EVENT_ID_FILE_INPUT	FILE_DATA
EVENT_ID_FORCE_INLINE	FUNCTION_FORCE_INLINEE_DATA
EVENT_ID_FRONT_END_FILE	FRONT_END_FILE_DATA
EVENT_ID_FRONT_END_PASS	CL_PASS_DATA
EVENT_ID_FUNCTION	FUNCTION_DATA
EVENT_ID_IMP_LIB_OUTPUT	FILE_DATA
EVENT_ID_LIB_OUTPUT	FILE_DATA
EVENT_ID_LINKER	INVOCATION_DATA
EVENT_ID_OBJ_OUTPUT	FILE_DATA
EVENT_ID_SYMBOL_NAME	SYMBOL_NAME_DATA
EVENT_ID_TEMPLATE_INSTANTIATION	TEMPLATE_INSTANTIATION_DATA

刻度轉換範例

//
// We have the elapsed number of ticks, along with the
// number of ticks per second. We use these values
// to convert to the number of elapsed microseconds.
// To guard against loss-of-precision, we convert
// to microseconds *before* dividing by ticks-per-second.
//

long long ConvertDurationToMicroseconds(const sruct EVENT_DATA& eventData)
{
    long long duration = eventData.StopTimestamp - eventData.StartTimestamp;
    long long duration *= 1000000;
    return duration / eventData.TickFrequency;
}