Repo sync for protected CLA branch

docs/build-insights/get-started-with-cpp-build-insights.md

@@ -48,4 +48,12 @@ Read these articles from the official C++ team blog for more information on C++
 
 [Faster builds with PCH suggestions from C++ Build Insights](https://devblogs.microsoft.com/cppblog/faster-builds-with-pch-suggestions-from-c-build-insights/)
 
+[Profiling template metaprograms with C++ Build Insights](https://devblogs.microsoft.com/cppblog/profiling-template-metaprograms-with-cpp-build-insights/)
+
+[Improving code generation time with C++ Build Insights](https://devblogs.microsoft.com/cppblog/improving-code-generation-time-with-cpp-build-insights/)
+
+[Introducing vcperf /timetrace for C++ build time analysis](https://devblogs.microsoft.com/cppblog/introducing-vcperf-timetrace-for-cpp-build-time-analysis/)
+
+[Faster C++ builds, simplified: a new metric for time](https://devblogs.microsoft.com/cppblog/faster-cpp-builds-simplified-a-new-metric-for-time/)
+
 ::: moniker-end

docs/build-insights/reference/sdk/c-event-data-types/translation-unit-type-data.md

@@ -0,0 +1,38 @@
+---
+title: "TRANSLATION_UNIT_TYPE_DATA enum"
+description: "The C++ Build Insights SDK TRANSLATION_UNIT_TYPE_DATA enum reference."
+ms.date: "06/10/2021"
+helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRANSLATION_UNIT_TYPE_DATA", "throughput analysis", "build time analysis", "vcperf.exe"]
+---
+# TRANSLATION_UNIT_TYPE_DATA enum
+
+::: moniker range="<=msvc-140"
+
+The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page.
+
+::: moniker-end
+::: moniker range=">=msvc-150"
+
+The `TRANSLATION_UNIT_TYPE_DATA` structure describes the type of the translation unit in the compiler front end pass.
+
+## Syntax
+
+```cpp
+typedef struct TRANSLATION_UNIT_TYPE_DATA_TAG
+{
+    int  TranslationUnitType;
+
+}  TRANSLATION_UNIT_TYPE_DATA;
+```
+
+## Members
+
+| Name | Description |
+|--|--|
+| `TranslationUnitType` | The type of this translation unit (either modules, header unit, or precompiled header). |
+
+## Remarks
+
+Used by the C SDK functions.
+
+::: moniker-end

docs/build-insights/reference/sdk/c-event-data-types/translation-unit-type.md

@@ -0,0 +1,30 @@
+---
+title: "TRANSLATION_UNIT_TYPE enum"
+description: "The C++ Build Insights SDK TRANSLATION_UNIT_TYPE enum reference."
+ms.date: "06/10/2021"
+helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRANSLATION_UNIT_TYPE", "throughput analysis", "build time analysis", "vcperf.exe"]
+---
+# TRANSLATION_UNIT_TYPE enum
+
+::: moniker range="<=msvc-140"
+
+The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page.
+
+::: moniker-end
+::: moniker range=">=msvc-150"
+
+The `TRANSLATION_UNIT_TYPE` enum.
+
+## Members
+
+| Name | Value | Description |
+|--|--|--|
+| `TRANSLATION_UNIT_TYPE_MODULE` | 0 (0x00000000) | The type of this translation unit is a module interface. |
+| `TRANSLATION_UNIT_TYPE_HEADER_UNIT` | 1 (0x00000001) | The type of this translation unit is a header unit. |
+| `TRANSLATION_UNIT_TYPE_PRECOMPILED_HEADER` | 2 (0x00000002) | The type of this translation unit is a precompiled header (PCH). |
+
+## Remarks
+
+Used by the C SDK functions.
+
+::: moniker-end

docs/build-insights/reference/sdk/cpp-event-data-types/header-unit.md

@@ -0,0 +1,51 @@
+---
+title: "HeaderUnit class"
+description: "The C++ Build Insights SDK HeaderUnit class reference."
+ms.date: "06/08/2021"
+helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "HeaderUnit", "throughput analysis", "build time analysis", "vcperf.exe"]
+---
+# HeaderUnit class
+
+::: moniker range="<=msvc-140"
+
+The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page.
+
+::: moniker-end
+::: moniker range=">=msvc-150"
+
+The `HeaderUnit` class is used with the [MatchEvent](../functions/match-event.md), [MatchEventInMemberFunction](../functions/match-event-in-member-function.md), [MatchEventStack](../functions/match-event-stack.md), and [MatchEventStackInMemberFunction](../functions/match-event-stack-in-member-function.md) functions. Use it to match a [HEADER_UNIT](../event-table.md#header-unit) event.
+
+## Syntax
+
+```cpp
+class HeaderUnit : public TranslationUnitType
+{
+public:
+    HeaderUnit(const RawEvent& event);
+};
+```
+
+## Members
+
+Along with the inherited members from its [TranslationUnitType](translation-unit-type.md) base class, the `HeaderUnit` class contains the following members:
+
+### Constructors
+
+[HeaderUnit](#header-unit)
+
+### Functions
+
+None
+
+## <a name="header-unit"></a> HeaderUnit
+
+```cpp
+HeaderUnit(const RawEvent& event);
+```
+
+### Parameters
+
+*event*\
+A [HEADER_UNIT](../event-table.md#header-unit) event.
+
+::: moniker-end

docs/build-insights/reference/sdk/cpp-event-data-types/module.md

@@ -0,0 +1,51 @@
+---
+title: "Module class"
+description: "The C++ Build Insights SDK Module class reference."
+ms.date: "06/08/2021"
+helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Module", "throughput analysis", "build time analysis", "vcperf.exe"]
+---
+# Module class
+
+::: moniker range="<=msvc-140"
+
+The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page.
+
+::: moniker-end
+::: moniker range=">=msvc-150"
+
+The `Module` class is used with the [MatchEvent](../functions/match-event.md), [MatchEventInMemberFunction](../functions/match-event-in-member-function.md), [MatchEventStack](../functions/match-event-stack.md), and [MatchEventStackInMemberFunction](../functions/match-event-stack-in-member-function.md) functions. Use it to match a [MODULE](../event-table.md#module) event.
+
+## Syntax
+
+```cpp
+class Module : public TranslationUnitType
+{
+public:
+    Module(const RawEvent& event);
+};
+```
+
+## Members
+
+Along with the inherited members from its [TranslationUnitType](translation-unit-type.md) base class, the `Module` class contains the following members:
+
+### Constructors
+
+[Module](#module)
+
+### Functions
+
+None
+
+## <a name="module"></a> Module
+
+```cpp
+Module(const RawEvent& event);
+```
+
+### Parameters
+
+*event*\
+A [MODULE](../event-table.md#module) event.
+
+::: moniker-end

docs/build-insights/reference/sdk/cpp-event-data-types/precompiled-header.md

@@ -0,0 +1,51 @@
+---
+title: "PrecompiledHeader class"
+description: "The C++ Build Insights SDK PrecompiledHeader class reference."
+ms.date: "06/08/2021"
+helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "PrecompiledHeader", "throughput analysis", "build time analysis", "vcperf.exe"]
+---
+# PrecompiledHeader class
+
+::: moniker range="<=msvc-140"
+
+The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page.
+
+::: moniker-end
+::: moniker range=">=msvc-150"
+
+The `PrecompiledHeader` class is used with the [MatchEvent](../functions/match-event.md), [MatchEventInMemberFunction](../functions/match-event-in-member-function.md), [MatchEventStack](../functions/match-event-stack.md), and [MatchEventStackInMemberFunction](../functions/match-event-stack-in-member-function.md) functions. Use it to match a [PRECOMPILED_HEADER](../event-table.md#precompiled-header) event.
+
+## Syntax
+
+```cpp
+class PrecompiledHeader : public TranslationUnitType
+{
+public:
+    PrecompiledHeader(const RawEvent& event);
+};
+```
+
+## Members
+
+Along with the inherited members from its [TranslationUnitType](translation-unit-type.md) base class, the `PrecompiledHeader` class contains the following members:
+
+### Constructors
+
+[PrecompiledHeader](#precompiled-header)
+
+### Functions
+
+None
+
+## <a name="precompiled-header"></a> PrecompiledHeader
+
+```cpp
+PrecompiledHeader(const RawEvent& event);
+```
+
+### Parameters
+
+*event*\
+A [PRECOMPILED_HEADER](../event-table.md#precompiled-header) event.
+
+::: moniker-end

docs/build-insights/reference/sdk/cpp-event-data-types/translation-unit-type.md

@@ -0,0 +1,70 @@
+---
+title: "TranslationUnitType class"
+description: "The C++ Build Insights SDK TranslationUnitType class reference."
+ms.date: "06/08/2021"
+helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TranslationUnitType", "throughput analysis", "build time analysis", "vcperf.exe"]
+---
+# TranslationUnitType class
+
+::: moniker range="<=msvc-140"
+
+The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page.
+
+::: moniker-end
+::: moniker range=">=msvc-150"
+
+The `TranslationUnitType` class is used with the [MatchEvent](../functions/match-event.md), [MatchEventInMemberFunction](../functions/match-event-in-member-function.md), [MatchEventStack](../functions/match-event-stack.md), and [MatchEventStackInMemberFunction](../functions/match-event-stack-in-member-function.md) functions. Use it to match a [TRANSLATION_UNIT_TYPE](../event-table.md#translation-unit-type) event.
+
+## Syntax
+
+```cpp
+class TranslationUnitType : public SimpleEvent
+{
+public:
+    enum class Type
+    {
+        MODULE              = TRANSLATION_UNIT_TYPE_MODULE,
+        HEADER_UNIT         = TRANSLATION_UNIT_TYPE_HEADER_UNIT,
+        PCH                 = TRANSLATION_UNIT_TYPE_PRECOMPILED_HEADER
+    };
+
+    TranslationUnitType(const RawEvent& event);
+
+    Type Type() const;
+};
+```
+
+## Members
+
+Along with the inherited members from its [SimpleEvent](simple-event.md) base class, the `TranslationUnitType` class contains the following members:
+
+### Constructors
+
+[TranslationUnitType](#translation-unit-type)
+
+### Functions
+
+[Type](#type)
+
+## <a name="type"></a> Type
+
+```cpp
+Type Type() const;
+```
+
+### Return Value
+
+The type of the translation unit: either MODULE, HEADER_UNIT, or PCH.
+
+## <a name="translation-unit-type"></a> TranslationUnitType
+
+```cpp
+TranslationUnitType(const RawEvent& event);
+```
+
+### Parameters
+
+*event*\
+A [TRANSLATION_UNIT_TYPE](../event-table.md#translation-unit-type) event.
+
+::: moniker-end

docs/build-insights/reference/sdk/event-table.md

@@ -28,7 +28,10 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To s
 [C1_DLL](#c1-dll)\
 [FRONT_END_FILE](#front-end-file)\
 [TEMPLATE_INSTANTIATION](#template-instantiation)\
-[SYMBOL_NAME](#symbol-name)
+[SYMBOL_NAME](#symbol-name)\
+[MODULE](#module)\
+[HEADER_UNIT](#header-unit)\
+[PRECOMPILED_HEADER](#precompiled-header)
 
 ## Compiler back-end events
 
@@ -143,7 +146,7 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To s
 |  | Description | Occurs when the compiler front end starts and stops processing a file. This event is recursive. Recursion happens when the front end is parsing included files. |
 | <a name="front-end-pass"></a> FRONT_END_PASS | Type | Activity |
 |  | Parents | [COMPILER](#compiler) |
-|  | Children | [C1_DLL](#c1-dll) |
+|  | Children | [C1_DLL](#c1-dll)<br/>[MODULE](#module)<br/>[HEADER_UNIT](#header-unit)<br/>[PRECOMPILED_HEADER](#precompiled-header) |
 |  | Properties | - Absolute path to input source file<br/>- Absolute path to output object file |
 |  | Capture classes | [Activity](cpp-event-data-types/activity.md)<br/>[CompilerPass](cpp-event-data-types/compiler-pass.md)<br/>[FrontEndPass](cpp-event-data-types/front-end-pass.md) |
 |  | Description | Occurs at the start and stop of the compiler front-end pass. This pass is responsible for parsing C/C++ source code and converting it into intermediate language. |
@@ -153,6 +156,12 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To s
 |  | Properties | - Name of the function |
 |  | Capture classes | [Activity](cpp-event-data-types/activity.md)<br/>[Function](cpp-event-data-types/function.md) |
 |  | Description | Occurs when starting and ending generating the code for a function. |
+| <a name="header-unit"></a> HEADER_UNIT | Type | Activity |
+|  | Parents | [FRONT_END_PASS](#front-end-pass) |
+|  | Children | None |
+|  | Properties | None |
+|  | Capture classes | [SimpleEvent](cpp-event-data-types/simple-event.md)<br/>[TranslationUnitType](cpp-event-data-types/translation-unit-type.md)<br/>[HeaderUnit](cpp-event-data-types/header-unit.md) |
+|  | Description | Occurs at the start of the front-end pass and represents that a header unit translation unit is being processed. |
 | <a name="imp-lib-output"></a> IMP_LIB_OUTPUT | Type | Simple Event |
 |  | Parents | [LINKER](#linker) |
 |  | Children | None |
@@ -177,6 +186,12 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To s
 |  | Properties | None |
 |  | Capture classes | [Activity](cpp-event-data-types/activity.md)<br/>[LTCG](cpp-event-data-types/ltcg.md) |
 |  | Description | Occurs at the start and stop of link-time code generation. |
+| <a name="module"></a> MODULE | Type | Activity |
+|  | Parents | [FRONT_END_PASS](#front-end-pass) |
+|  | Children | None |
+|  | Properties | None |
+|  | Capture classes | [SimpleEvent](cpp-event-data-types/simple-event.md)<br/>[TranslationUnitType](cpp-event-data-types/translation-unit-type.md)<br/>[Module](cpp-event-data-types/module.md) |
+|  | Description | Occurs at the start of the front-end pass and represents that a module translation unit is being processed. |
 | <a name="obj-output"></a> OBJ_OUTPUT | Type | Simple Event |
 |  | Parents | [COMPILER](#compiler) |
 |  | Children | None |
@@ -213,6 +228,12 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To s
 |  | Properties | None |
 |  | Capture classes | [Activity](cpp-event-data-types/activity.md)<br/>[Pass2](cpp-event-data-types/pass2.md) |
 |  | Description | Occurs at the start and stop of the linker's pass 2. |
+| <a name="precompiled-header"></a> PRECOMPILED_HEADER | Type | Activity |
+|  | Parents | [FRONT_END_PASS](#front-end-pass) |
+|  | Children | None |
+|  | Properties | None |
+|  | Capture classes | [SimpleEvent](cpp-event-data-types/simple-event.md)<br/>[TranslationUnitType](cpp-event-data-types/translation-unit-type.md)<br/>[PrecompiledHeader](cpp-event-data-types/precompiled-header.md) |
+|  | Description | Occurs at the start of the front-end pass and represents that a precompiled header (PCH) translation unit is being processed. |
 | <a name="pre-ltcg-opt-ref"></a> PRE_LTCG_OPT_REF | Type | Activity |
 |  | Parents | [PASS1](#pass1) |
 |  | Children | None |
@@ -243,6 +264,12 @@ The C++ Build Insights SDK is compatible with Visual Studio 2017 and above. To s
 |  | Properties | None |
 |  | Capture classes | [Activity](cpp-event-data-types/activity.md)<br/>[TopDown](cpp-event-data-types/top-down.md) |
 |  | Description | Occurs at the start and stop of the whole program analysis' top-down pass. |
+| <a name="translation-unit-type"></a> TRANSLATION_UNIT_TYPE | Type | Activity |
+|  | Parents | [FRONT_END_PASS](#front-end-pass) |
+|  | Children | [MODULE](#module)<br/>[HEADER_UNIT](#header-unit)<br/>[PRECOMPILED_HEADER](#precompiled-header) |
+|  | Properties | - The type of translation unit. |
+|  | Capture classes | [SimpleEvent](cpp-event-data-types/simple-event.md)<br/>[TranslationUnitType](cpp-event-data-types/translation-unit-type.md) |
+|  | Description | Occurs at the start of the front-end pass. The type identifies whether this pass is processing a module, header unit, or precompiled header. |
 | <a name="whole-program-analysis"></a> WHOLE_PROGRAM_ANALYSIS | Type | Activity |
 |  | Parents | [C2_DLL](#c2-dll) |
 |  | Children | [BOTTOM_UP](#bottom-up)<br/>[TOP_DOWN](#top-down) |