EVENT_DATA 構造体

  • [アーティクル]

C++ Build Insights SDK は、Visual Studio 2017 以降と互換性があります。 これらのバージョンのドキュメントを表示するには、この記事の Visual Studio バージョン セレクター コントロールを Visual Studio 2017 以降に設定します。 このページの目次の一番上にあります。

この構造体は 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 ティック単位で計測された期間を評価するときに使用する、1 秒あたりのティック数。
StartTimestamp イベントが アクティビティの場合、このフィールドはアクティビティの開始時にキャプチャされたティック値です。 このイベントが 単純イベントの場合、このフィールドはイベントが発生した時点でキャプチャされたティック値です。
StopTimestamp イベントが アクティビティの場合、このフィールドはアクティビティが停止したときにキャプチャされたティック値です。 このアクティビティの停止イベントがまだ受信されていない場合、このフィールドは 0 です。 このイベントが 単純イベントの場合、このフィールドは 0 です。
ExclusiveDurationTicks このイベントが アクティビティの場合、このフィールドは、このアクティビティで直接発生したティック数です。 子アクティビティで発生したティック数は除外されます。 このフィールドは、 単純イベントの場合は 0 です。
CPUTicks このイベントが アクティビティの場合、このフィールドは、このアクティビティ中に発生した CPU ティックの数です。 CPU ティックは、通常のティックとは異なります。 CPU ティックは、アクティビティ内のコードが CPU によって実行されている場合にのみカウントされます。 アクティビティに関連付けられているスレッドがスリープ状態のときには、CPU ティックはカウントされません。 このフィールドは、 単純イベントの場合は 0 です。
ExclusiveCPUTicks このフィールドは CPUTicks と同じ意味を持ちますが、子アクティビティで発生した CPU ティックは含まれません。 このフィールドは、 単純イベントの場合は 0 です。
WallClockTimeResponsibilityTicks このイベントが アクティビティの場合、このフィールドは、このアクティビティの全体的な壁時計時間への寄与を表すティック数です。 実時間の責任ティックは、通常のティックとは異なります。 実時間の責任ティックでは、アクティビティ間の並列処理が考慮されます。 たとえば、2 つの並列アクティビティが 50 ティックの期間を持ち、開始時刻と終了時刻が同じであるとします。 この場合、両方に 25 ティックの実時間の責任が割り当てられます。 このフィールドは、 単純イベントの場合は 0 です。
ExclusiveWallClockTimeResponsibilityTicks このフィールドは WallClockTimeResponsibilityTicks と同じ意味を持ちます。ただし、子アクティビティの実時間の責任ティックは含まれません。 このフィールドは、 単純イベントの場合は 0 です。
Data イベントに格納されている他のデータを指します。 示されているデータの型は、EventId フィールドによって異なります。
ProcessId イベントが発生したプロセスの識別子。
ThreadId イベントが発生したスレッドの識別子。
ProcessorIndex イベントが発生した (インデックスが 0 から始まる) CPU 番号。
EventName EventId によって識別されるエンティティの名前を含む ANSI 文字列。
EventWideName EventId によって識別されるエンティティの名前を含むワイド文字列。

Remarks

EVENT_DATA の多くのフィールドには、ティック数が含まれています。 C++ ビルド インサイトでは、Windows パフォーマンス カウンターがティックのソースとして使用されます。 ティック数は TickFrequency フィールドと共に使用して、秒などの適切な時間単位に変換する必要があります。 以下の ティック変換の例を参照してください。

EVENT_DATA には、アクティビティの通常のティック数を表すフィールドは含まれていません。 この値を取得するには、StopTimestamp から StartTimestamp を減算します。

EVENT_DATA は、C API ユーザーが使用することを意図した構造体です。 C++ API ユーザーの場合、Event などのクラスによって、時間の変換が自動的に実行されます。

EVENT_DATA の Data フィールドの値は、その EventId フィールドの値によって異なります。 Data の値について、次の表で説明します。 次の表では、エンティティ識別子の一部が不足している場合があります。 その場合、Data フィールドは nullptr または 0 に設定されます。

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;
}