diff --git a/docs/breadcrumb/toc.yml b/docs/breadcrumb/toc.yml index 31f62bc4824a7..e4b1b762c4599 100644 --- a/docs/breadcrumb/toc.yml +++ b/docs/breadcrumb/toc.yml @@ -115,12 +115,15 @@ tocHref: /dotnet/core/ topicHref: /dotnet/core/index items: - - name: Tools - tocHref: /dotnet/core/tools/ - topicHref: /dotnet/core/tools/index - name: Compatibility tocHref: /dotnet/core/compatibility/ topicHref: /dotnet/core/compatibility/index + - name: Run-time configuration + tocHref: /dotnet/core/run-time-config/ + topicHref: /dotnet/core/run-time-config/index + - name: Tools + tocHref: /dotnet/core/tools/ + topicHref: /dotnet/core/tools/index - name: .NET Framework tocHref: /dotnet/framework/ topicHref: /dotnet/framework/index diff --git a/docs/core/run-time-config/garbage-collector.md b/docs/core/run-time-config/garbage-collector.md new file mode 100644 index 0000000000000..0b7f0db75eff7 --- /dev/null +++ b/docs/core/run-time-config/garbage-collector.md @@ -0,0 +1,204 @@ +--- +title: Garbage collector config settings +description: Learn about run-time settings for configuring how the garbage collector manages memory. +ms.date: 11/13/2019 +ms.topic: reference +--- +# Run-time configuration options for garbage collection + +This page contains information about garbage collector (GC) settings that can be changed at run time. If you're trying to achieve peak performance of a running app, consider using these settings. However, the defaults provide optimum performance for most applications in typical situations. + +Settings are arranged into groups on this page. The settings within each group are commonly used in conjunction with each other to achieve a specific result. + +> [!NOTE] +> +> - These settings can also be changed dynamically by the app as it's running, so any run-time settings you set may be overridden. +> - Some settings, such as [latency level](../../standard/garbage-collection/latency.md), are typically set only through the API at design time. Such settings are omitted from this page. + +## Flavors of garbage collection + +The two main flavors of garbage collection are workstation GC and server GC. For more information about differences between the two, see [Fundamentals of garbage collection](../../standard/garbage-collection/fundamentals.md#workstation-and-server-garbage-collection). + +The subflavors of garbage collection are background and non-concurrent. + +Use the following settings to select flavors of garbage collection: + +### System.GC.Server/COMPlus_gcServer + +- Configures whether the application uses workstation garbage collection or server garbage collection. +- Default: Workstation garbage collection (`false`). +- For more information, see [Configure garbage collection](../../standard/garbage-collection/fundamentals.md#configuring-garbage-collection). + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.Server` | `false` - workstation
`true` - server | .NET Core 1.0 | +| **Environment variable** | `COMPlus_gcServer` | 0 - workstation
1 - server | .NET Core 1.0 | +| **app.config for .NET Framework** | [GCServer](../../framework/configure-apps/file-schema/runtime/gcserver-element.md) | `false` - workstation
`true` - server | | + +### System.GC.Concurrent/COMPlus_gcConcurrent + +- Configures whether background (concurrent) garbage collection is enabled. +- Default: Enabled (`true`). +- For more information, see [Background garbage collection](../../standard/garbage-collection/fundamentals.md#background-workstation-garbage-collection) and [Background server garbage collection](../../standard/garbage-collection/fundamentals.md#background-server-garbage-collection). + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.Concurrent` | `true` - background GC
`false` - non-concurrent GC | .NET Core 1.0 | +| **Environment variable** | `COMPlus_gcConcurrent` | `true` - background GC
`false` - non-concurrent GC | .NET Core 1.0 | +| **app.config for .NET Framework** | [gcConcurrent](../../framework/configure-apps/file-schema/runtime/gcconcurrent-element.md) | `true` - background GC
`false` - non-concurrent GC | | + +## Manage resource usage + +Use the settings described in this section to manage the garbage collector's memory and processor usage. + +For more information about some of these settings, see the [Middle ground between workstation and server GC](https://devblogs.microsoft.com/dotnet/middle-ground-between-server-and-workstation-gc/) blog entry. + +### System.GC.HeapCount/COMPlus_GCHeapCount + +- Limits the number of heaps created by the garbage collector. +- Applies to server garbage collection (GC) only. +- If GC thread/processor affinity is enabled, which is the default, the heap count setting affinitizes *number* GC heaps/threads to the first *number* processors. (Use the affinitize mask or affinitize ranges settings to specify exactly which processors to affinitize.) +- If GC thread/processor affinity is disabled, this setting limits the number of GC heaps. +- For more information, see the [GCHeapCount remarks](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md#remarks). + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.HeapCount` | *number* | .NET Core 3.0 | +| **Environment variable** | `COMPlus_GCHeapCount` | *number* | .NET Core 3.0 | +| **app.config for .NET Framework** | [GCHeapCount](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md) | *number* | 4.6.2 | + +### System.GC.HeapAffinitizeMask/COMPlus_GCHeapAffinitizeMask + +- Specifies the exact processors that garbage collector threads should use. +- If processor affinity is disabled by setting `System.GC.NoAffinitize` to `true`, this setting is ignored. +- Applies to server garbage collection (GC) only. +- The decimal value is a bit mask that defines the processors that are available to the process. For example, a decimal value of 1023 is equivalent to 0x3FF in hexadecimal notation and 0011 1111 1111 in binary notation. This specifies that the first 10 processors are to be used. To specify the next 10 processors, that is, processors 10-19, specify a decimal value of 1047552, which is equivalent to 0xFFC00 in hexadecimal and 1111 1111 1100 0000 0000 in binary. + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.HeapAffinitizeMask` | *decimal value* | .NET Core 3.0 | +| **Environment variable** | `COMPlus_GCHeapAffinitizeMask` | *decimal value* | .NET Core 3.0 | +| **app.config for .NET Framework** | [GCHeapAffinitizeMask](../../framework/configure-apps/file-schema/runtime/gcheapaffinitizemask-element.md) | *decimal value* | 4.6.2 | + +### System.GC.GCHeapAffinitizeRanges/COMPlus_GCHeapAffinitizeRanges + +- Specifies the list of processors to use for garbage collector threads. +- This setting is similar to `System.GC.HeapAffinitizeMask`, except it allows you to specify more than 64 processors. +- For Windows operating systems, prefix the processor number or range with the corresponding [CPU group](/windows/win32/procthread/processor-groups), for example, "0:1-10,0:12,1:50-52,1:70". +- If processor affinity is disabled by setting `System.GC.NoAffinitize` to `true`, this setting is ignored. +- Applies to server garbage collection (GC) only. +- For more information, see [Making CPU configuration better for GC on machines with > 64 CPUs](https://devblogs.microsoft.com/dotnet/making-cpu-configuration-better-for-gc-on-machines-with-64-cpus/) on Maoni Stephens' blog. + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.GCHeapAffinitizeRanges` | Comma-separated list of processor numbers or ranges of processor numbers.
Unix example: "1-10,12,50-52,70"
Windows example: "0:1-10,0:12,1:50-52,1:70" | .NET Core 1.0 | +| **Environment variable** | `COMPlus_GCHeapAffinitizeRanges` | Comma-separated list of processor numbers or ranges of processor numbers.
Unix example: "1-10,12,50-52,70"
Windows example: "0:1-10,0:12,1:50-52,1:70" | .NET Core 1.0 | +| **app.config for .NET Framework** | N/A | N/A | N/A | + +### COMPlus_GCCpuGroup + +- Configures whether the garbage collector uses [CPU groups](/windows/win32/procthread/processor-groups) or not. + + When a 64-bit Windows computer has multiple CPU groups, that is, there are more than 64 processors, enabling this element extends garbage collection across all CPU groups. The garbage collector uses all cores to create and balance heaps. + +- Applies to server garbage collection (GC) on 64-bit Windows operation systems only. +- Default: Disabled (0). +- For more information, see [Maoni Stephens' blog entry](https://devblogs.microsoft.com/dotnet/making-cpu-configuration-better-for-gc-on-machines-with-64-cpus/). + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | N/A | N/A | N/A | +| **Environment variable** | `COMPlus_GCCpuGroup` | 0 - disabled
1 - enabled | .NET Core 1.0 | +| **app.config for .NET Framework** | [GCCpuGroup](../../framework/configure-apps/file-schema/runtime/gccpugroup-element.md) | `false` - disabled
`true` - enabled | | + +### System.GC.NoAffinitize/COMPlus_GCNoAffinitize + +- Specifies whether to affinitize garbage collection threads with processors. That is, whether to create a dedicated heap, GC thread, and background GC thread (if background garbage collection is enabled) for each processor. +- Applies to server garbage collection (GC) only. +- Default: Affinitize garbage collection threads with processors (`false`). + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.NoAffinitize` | `false` - affinitize
`true` - don't affinitize | .NET Core 3.0 | +| **Environment variable** | `COMPlus_GCNoAffinitize` | 0 - affinitize
1 - don't affinitize | .NET Core 3.0 | +| **app.config for .NET Framework** | [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md) | `false` - affinitize
`true` - don't affinitize | 4.6.2 | + +### System.GC.HeapHardLimit/COMPlus_GCHeapHardLimit + +- Specifies the maximum commit size, in bytes, for the GC heap. +- The value can range from 0 to 18,446,744,073,709,551,615. + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.HeapHardLimit` | *decimal value* | .NET Core 3.0 | +| **Environment variable** | `COMPlus_GCHeapHardLimit` | *decimal value* | .NET Core 3.0 | + +### System.GC.HeapHardLimitPercent/COMPlus_GCHeapHardLimitPercent + +- Specifies the GC heap usage as a percentage of the total memory. +- Example value: 25 + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.HeapHardLimitPercent` | *percentage* | .NET Core 3.0 | +| **Environment variable** | `COMPlus_GCHeapHardLimitPercent` | *percentage* | .NET Core 3.0 | + +### System.GC.RetainVM/COMPlus_GCRetainVM + +- Configures whether segments that should be deleted are put on a standby list for future use or are released back to the operating system (OS). +- Default: Release segments back to the operating system (`false`). + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.RetainVM` | `false` - release to OS
`true` - put on standby| .NET Core 1.0 | +| **Environment variable** | `COMPlus_GCRetainVM` | 0 - release to OS
1 - put on standby | .NET Core 1.0 | + +## Large pages + +### COMPlus_GCLargePages + +- Specifies whether large pages should be used when a heap hard limit is set. +- Default: Disabled (0). +- This is an experimental setting. + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | N/A | N/A | N/A | +| **Environment variable** | `COMPlus_GCLargePages` | 0 - disabled
1 - enabled | .NET Core 1.0 | +| **app.config for .NET Framework** | N/A | N/A | N/A | + +## Large objects + +### COMPlus_gcAllowVeryLargeObjects + +- Configures garbage collector support on 64-bit platforms for arrays that are greater than 2 gigabytes (GB) in total size. +- Default: Enabled (1). +- This option may become obsolete in a future version of .NET. + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | N/A | N/A | N/A | +| **Environment variable** | `COMPlus_gcAllowVeryLargeObjects` | 1 - enabled
0 - disabled | .NET Core 1.0 | + +## Large object heap threshold + +### System.GC.LOHThreshold/COMPlus_GCLOHThreshold + +- Specifies the threshold size, in bytes, that causes objects to go on the large object heap (LOH). + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | `System.GC.LOHThreshold` | *size in bytes* | .NET Core 1.0 | +| **Environment variable** | `COMPlus_GCLOHThreshold` | *size in bytes* | .NET Core 1.0 | + +## Standalone GC + +### COMPlus_GCName + +- Specifies a path to the library containing the garbage collector that the runtime intends to load. +- For more information, see [Standalone GC loader design](https://github.com/dotnet/coreclr/blob/master/Documentation/design-docs/standalone-gc-loading.md). + +| | Setting name | Values | Version introduced | +| - | - | - | - | +| **runtimeconfig.json** | N/A | N/A | N/A | +| **Environment variable** | `COMPlus_GCName` | *string_path* | .NET Core 1.0 | diff --git a/docs/core/run-time-config/index.md b/docs/core/run-time-config/index.md new file mode 100644 index 0000000000000..e531ed7cd6586 --- /dev/null +++ b/docs/core/run-time-config/index.md @@ -0,0 +1,76 @@ +--- +title: Run-time config +description: Learn how to configure .NET Core applications by using run-time configuration settings. +ms.date: 11/13/2019 +--- +# .NET Core run-time configuration settings + +.NET Core supports the use of configuration files and environment variables to configure the behavior of .NET Core applications at run time. Run-time configuration is an attractive option if: + +- You don't own or control the source code for an application and therefore are unable to configure it programmatically. + +- Multiple instances of your application run at the same time on a single system, and you want to configure each for optimum performance. + +> [!NOTE] +> This documentation is a work in progress. If you notice that the information presented here is either incomplete or inaccurate, either [open an issue](https://github.com/dotnet/docs/issues) to let us know about it, or [submit a pull request](https://github.com/dotnet/docs/pulls) to address the issue. For information on submitting pull requests for the dotnet/docs repository, see the [contributor's guide](https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md). + +.NET Core provides the following mechanisms for configuring applications at run time: + +- The [runtimeconfig.json file](#runtimeconfigjson) + +- [Environment variables](#environment-variables) + +The articles in this section of the documentation include are organized by category, for example, debugging and garbage collection. Available configuration options are shown for *runtimeconfig.json* (.NET Core only), *app.config* (.NET Framework only), and environment variables. + +## runtimeconfig.json + +Specify run-time configuration options in the **configProperties** section of the *runtimeconfig.json* file. This section has the form: + +```json +{ + "runtimeOptions": { + "configProperties": { + "config-property-name1": "config-value1", + "config-property-name2": "config-value2" + } + } +} +``` + +Here is an example file: + +```json +{ + "runtimeOptions": { + "configProperties": { + "System.GC.Concurrent": true, + "System.GC.RetainVM": true, + "System.Threading.ThreadPool.MinThreads": "4", + "System.Threading.ThreadPool.MaxThreads": "25" + } + } +} +``` + +The *runtimeconfig.json* file is automatically created in the build directory by the [dotnet build](../tools/dotnet-build.md) command. It's also created when you select the **Build** menu option in Visual Studio. You can then edit the file once it's created. + +Some configuration values can also be set programmatically by calling the method. + +## Environment variables + +Environment variables can be used to to supply some run-time configuration information. Configuration knobs specified as environment variables generally have the prefix **COMPlus_**. + +You can define environment variables from the Windows Control Panel, at the command line, or programmatically by calling the method on both Windows and Unix-based systems. + +The following examples show how to set an environment variable at the command line: + +```shell +# Windows +set COMPlus_GCRetainVM=1 + +# Powershell +$env:COMPlus_GCRetainVM="1" + +# Unix +export COMPlus_GCRetainVM=1 +``` diff --git a/docs/core/toc.yml b/docs/core/toc.yml index 02cce242e49df..bdd26ed1d5b89 100644 --- a/docs/core/toc.yml +++ b/docs/core/toc.yml @@ -54,27 +54,33 @@ href: tutorials/cli-templates-create-template-pack.md - name: Get started with .NET Core on macOS href: tutorials/using-on-macos.md - - name: Get started with .NET Core on macOS using Visual Studio for Mac + - name: Get started with .NET Core using Visual Studio for Mac href: tutorials/using-on-mac-vs.md - - name: Building a complete .NET Core solution on macOS using Visual Studio for Mac + - name: Build a complete .NET Core solution on macOS href: tutorials/using-on-mac-vs-full-solution.md - name: Get started with .NET Core using the CLI tools href: tutorials/using-with-xplat-cli.md - - name: Organizing and testing projects with the .NET Core command line + - name: Organize and test projects with the .NET Core CLI href: tutorials/testing-with-cli.md - - name: Developing Libraries with Cross Platform Tools + - name: Develop libraries with cross-platform tools href: tutorials/libraries.md - - name: Create a .NET Core application with plugins - href: tutorials/creating-app-with-plugin-support.md - - name: Developing ASP.NET Core applications + - name: Create a .NET Core app with plugins + href: tutorials/creating-app-with-plugin-support.md + - name: Develop ASP.NET Core apps href: tutorials/aspnet-core.md - - name: Hosting .NET Core from native code + - name: Host .NET Core from native code href: tutorials/netcore-hosting.md -- name: Native Interoperability +- name: Run-time configuration items: - - name: Exposing .NET Core Components to COM + - name: Settings + href: run-time-config/index.md + - name: Garbage collector settings + href: run-time-config/garbage-collector.md +- name: Native interoperability + items: + - name: Expose .NET Core components to COM href: native-interop/expose-components-to-com.md -- name: Packages, Metapackages and Frameworks +- name: Packages, Metapackages, and Frameworks href: packages.md - name: Changes in CLI overview href: tools/cli-msbuild-architecture.md diff --git a/docs/framework/configure-apps/file-schema/network/performancecounter-element-network-settings.md b/docs/framework/configure-apps/file-schema/network/performancecounter-element-network-settings.md index 64316b1d4a461..a564bc02e80fc 100644 --- a/docs/framework/configure-apps/file-schema/network/performancecounter-element-network-settings.md +++ b/docs/framework/configure-apps/file-schema/network/performancecounter-element-network-settings.md @@ -46,7 +46,7 @@ Enables or disables networking performance counters. ## Remarks This element can be used in the application configuration file or the machine configuration file (Machine.config). - Networking performance counters need to be enabled in the configuration file to be used. All networking performance counters are enabled or disabled with a single setting in the configuration file. Individual networking performance counters cannot be enabled or disabled. For more information on the specific networking performance counters, see [Networking Performance Counters](../../../debug-trace-profile/performance-counters.md#networking). + Networking performance counters need to be enabled in the configuration file to be used. All networking performance counters are enabled or disabled with a single setting in the configuration file. Individual networking performance counters cannot be enabled or disabled. For more information on the specific networking performance counters, see [Networking performance counters](../../../debug-trace-profile/performance-counters.md#networking-performance-counters). The default value is that networking performance counters are disabled. @@ -72,4 +72,4 @@ Enables or disables networking performance counters. - - - [Network Settings Schema](index.md) -- [Networking Performance Counters](../../../debug-trace-profile/performance-counters.md#networking) +- [Networking Performance Counters](../../../debug-trace-profile/performance-counters.md#networking-performance-counters) diff --git a/docs/framework/configure-apps/file-schema/runtime/gcheapcount-element.md b/docs/framework/configure-apps/file-schema/runtime/gcheapcount-element.md index 7487991de5aa3..7ae0faf4cd36f 100644 --- a/docs/framework/configure-apps/file-schema/runtime/gcheapcount-element.md +++ b/docs/framework/configure-apps/file-schema/runtime/gcheapcount-element.md @@ -57,7 +57,7 @@ By default, server GC threads are hard-affinitized with their respective CPU so - [GCHeapAffinitizeMask](gcheapaffinitizemask-element.md), which controls the affinity of GC threads/heaps with CPUs. -If **GCHeapCount** is set and **GCNoAffinitize** is disabled (its default setting), there is an affinity between the *nn* GC threads/heaps and the first *nn* processors. You can use the **GCHeapAffinitizeMask** element to specify which processors are used by the process' server GC heaps. Otherwise, if multiple server processes are running on a system, their processor usage will overlap. +If **GCHeapCount** is set and **GCNoAffinitize** is disabled (its default setting), there is an affinity between the *nn* GC threads/heaps and the first *nn* processors. You can use the **GCHeapAffinitizeMask** element to specify which processors are used by the process's server GC heaps. Otherwise, if multiple server processes are running on a system, their processor usage will overlap. If **GCHeapCount** is set and **GCNoAffinitize** is enabled, the garbage collector limits the number of processors used for server GC but does not affinitize GC heaps and processors. diff --git a/docs/framework/debug-trace-profile/performance-counters.md b/docs/framework/debug-trace-profile/performance-counters.md index eff35b768a193..bba3ed886c4c5 100644 --- a/docs/framework/debug-trace-profile/performance-counters.md +++ b/docs/framework/debug-trace-profile/performance-counters.md @@ -7,26 +7,10 @@ helpviewer_keywords: - "performance monitoring, counters" ms.assetid: 06a4ae8c-eeb2-4d5a-817e-b1b95c0653e1 --- -# Performance Counters in the .NET Framework +# Performance counters in the .NET Framework + This topic provides a list of performance counters you can find in the [Windows Performance Monitor](https://docs.microsoft.com/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc749249%28v=ws.11%29). - -- [Exception performance counters](#exception) - -- [Interop performance counters](#interop) - -- [JIT performance counters](#jit) - -- [Loading performance counters](#loading) - -- [Lock and thread performance counters](#lockthread) - -- [Memory performance counters](#memory) - -- [Networking performance counters](#networking) - -- [Security performance counters](#security) - - + ## Exception performance counters The Performance console .NET CLR Exceptions category includes counters that provide information about the exceptions thrown by an application. The following table describes these performance counters. @@ -37,8 +21,7 @@ This topic provides a list of performance counters you can find in the [Windows |**# of Filters / Sec**|Displays the number of .NET exception filters executed per second. An exception filter evaluates regardless of whether an exception is handled.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| |**# of Finallys / Sec**|Displays the number of finally blocks executed per second. A finally block is guaranteed to be executed regardless of how the try block was exited. Only the finally blocks executed for an exception are counted; finally blocks on normal code paths are not counted by this counter.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| |**Throw to Catch Depth / Sec**|Displays the number of stack frames traversed, from the frame that threw the exception to the frame that handled the exception, per second. This counter resets to zero when an exception handler is entered, so nested exceptions show the handler-to-handler stack depth.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| - - + ## Interop performance counters The Performance console .NET CLR Interop category includes counters that provide information about an application's interaction with COM components, COM+ services, and external type libraries. The following table describes these performance counters. @@ -49,8 +32,7 @@ This topic provides a list of performance counters you can find in the [Windows |**# of Stubs**|Displays the current number of stubs created by the common language runtime. Stubs are responsible for marshaling arguments and return values from managed to unmanaged code, and vice versa, during a COM interop call or a platform invoke call.| |**# of TLB exports / sec**|Reserved for future use.| |**# of TLB imports / sec**|Reserved for future use.| - - + ## JIT performance counters The Performance console .NET CLR JIT category includes counters that provide information about code that has been JIT-compiled. The following table describes these performance counters. @@ -62,8 +44,7 @@ This topic provides a list of performance counters you can find in the [Windows |**IL Bytes Jitted / sec**|Displays the number of MSIL bytes that are JIT-compiled per second. This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| |**Standard Jit Failures**|Displays the peak number of methods the JIT compiler has failed to compile since the application started. This failure can occur if the MSIL cannot be verified or if there is an internal error in the JIT compiler.| |**Total # of IL Bytes Jitted**|Displays the total MSIL bytes JIT-compiled since the application started. This counter is equivalent to the **# of IL Bytes Jitted** counter.| - - + ## Loading performance counters The Performance console .NET CLR Loading category includes counters that provide information about assemblies, classes, and application domains that are loaded. The following table describes these performance counters. @@ -85,8 +66,7 @@ This topic provides a list of performance counters you can find in the [Windows |**Total appdomains unloaded**|Displays the total number of application domains unloaded since the application started. If an application domain is loaded and unloaded multiple times, this counter increments each time the application domain is unloaded.| |**Total Assemblies**|Displays the total number of assemblies loaded since the application started. If the assembly is loaded as domain-neutral from multiple application domains, this counter is incremented only once.| |**Total Classes Loaded**|Displays the cumulative number of classes loaded in all assemblies since the application started.| - - + ## Lock and thread performance counters The Performance console .NET CLR LocksAndThreads category includes counters that provide information about managed locks and threads that an application uses. The following table describes these performance counters. @@ -102,8 +82,7 @@ This topic provides a list of performance counters you can find in the [Windows |**Queue Length Peak**|Displays the total number of threads that waited to acquire a managed lock since the application started.| |**rate of recognized threads / sec**|Displays the number of threads per second that have been recognized by the runtime. These threads are associated with a corresponding managed thread object. The runtime does not create these threads, but they have run inside the runtime at least once.

Only unique threads are tracked; threads with the same thread ID that reenter the runtime or are recreated after the thread exits are not counted twice.

This counter is not an average over time; it displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| |**Total # of Contentions**|Displays the total number of times that threads in the runtime have attempted to acquire a managed lock unsuccessfully.| - - + ## Memory performance counters The Performance console .NET CLR Memory category includes counters that provide information about the garbage collector. The following table describes these performance counters. @@ -127,15 +106,15 @@ This topic provides a list of performance counters you can find in the [Windows |**Gen 1 heap size**|Displays the current number of bytes in generation 1; this counter does not display the maximum size of generation 1. Objects are not directly allocated in this generation; they are promoted from previous generation 0 garbage collections. This counter is updated at the end of a garbage collection, not at each allocation.| |**Gen 1 Promoted Bytes/Sec**|Displays the bytes per second that are promoted from generation 1 to generation 2. Objects that are promoted only because they are waiting to be finalized are not included in this counter.

Memory is promoted when it survives a garbage collection. Nothing is promoted from generation 2 because it is the oldest generation. This counter is an indicator of very long-lived objects being created per second.

This counter displays the difference between the values observed in the last two samples divided by the duration of the sample interval.| |**Gen 2 heap size**|Displays the current number of bytes in generation 2. Objects are not directly allocated in this generation; they are promoted from generation 1 during previous generation 1 garbage collections. This counter is updated at the end of a garbage collection, not at each allocation.| -|**Large Object Heap size**|Displays the current size, in bytes, of the Large Object Heap. Objects that are greater than approximately 85,000 bytes are treated as large objects by the garbage collector and are directly allocated in a special heap; they are not promoted through the generations. This counter is updated at the end of a garbage collection, not at each allocation.| +|**Large Object Heap size**|Displays the current size, in bytes, of the large object heap. Objects that are greater than approximately 85,000 bytes are treated as large objects by the garbage collector and are directly allocated in a special heap. They are not promoted through the generations. This counter is updated at the end of a garbage collection, not at each allocation.| |**Process ID**|Displays the process ID of the CLR process instance that is being monitored.| |**Promoted Finalization-Memory from Gen 0**|Displays the bytes of memory that are promoted from generation 0 to generation 1 only because they are waiting to be finalized. This counter is not cumulative; it displays the value observed at the end of the last garbage collection.| |**Promoted Memory from Gen 0**|Displays the bytes of memory that survive garbage collection and are promoted from generation 0 to generation 1. Objects that are promoted only because they are waiting to be finalized are not included in this counter. This counter is not cumulative; it displays the value observed at the end of the last garbage collection.| |**Promoted Memory from Gen 1**|Displays the bytes of memory that survive garbage collection and are promoted from generation 1 to generation 2. Objects that are promoted only because they are waiting to be finalized are not included in this counter. This counter is not cumulative; it displays the value observed at the end of the last garbage collection. This counter is reset to 0 if the last garbage collection was a generation 0 collection only.| - - + ## Networking performance counters - The Performance console .NET CLR Networking category includes counters that provide information about data that an application sends and receives over the network. The following table describes these performance counters. + +The Performance console .NET CLR Networking category includes counters that provide information about data that an application sends and receives over the network. The following table describes these performance counters. |Performance counter|Description| |-------------------------|-----------------| @@ -161,7 +140,7 @@ This topic provides a list of performance counters you can find in the [Windows - Per-Interval counters that measure the number of objects that are making a particular transition per interval (normally per second). - The networking performance counters for events include the following: +The networking performance counters for events include the following: - **Connections Established** @@ -230,8 +209,7 @@ for (int i = 0; i < Array.Length; i++) - ".NET CLR Networking 4.0.0.0" - All of the above socket counters plus the new performance counters supported on .NET Framework Version 4 and later. These new counters provide performance information on objects. For more information on accessing and managing performance counters in an application, see [Performance Counters](performance-counters.md). - - + ## Security performance counters The Performance console .NET CLR Security category includes counters that provide information about the security checks that the common language runtime performs for an application. The following table describes these performance counters. diff --git a/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md b/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md index 34657c43ae4de..74a06e6058547 100644 --- a/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md +++ b/docs/framework/unmanaged-api/profiling/cor-prf-high-monitor-enumeration.md @@ -4,9 +4,10 @@ ms.date: "04/10/2018" ms.assetid: 3ba543d8-15e5-4322-b6e7-1ebfc92ed7dd --- # COR_PRF_HIGH_MONITOR Enumeration + [Supported in the .NET Framework 4.5.2 and later versions] - Provides flags in addition to those found in the [COR_PRF_MONITOR](../../../../docs/framework/unmanaged-api/profiling/cor-prf-monitor-enumeration.md) enumeration that the profiler can specify to the [ICorProfilerInfo5::SetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-seteventmask2-method.md) method when it is loading. +Provides flags in addition to those found in the [COR_PRF_MONITOR](../../../../docs/framework/unmanaged-api/profiling/cor-prf-monitor-enumeration.md) enumeration that the profiler can specify to the [ICorProfilerInfo5::SetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-seteventmask2-method.md) method when it is loading. ## Syntax @@ -41,26 +42,28 @@ typedef enum { |`COR_PRF_HIGH_DISABLE_TIERED_COMPILATION`|.NET Core 3.0 and later versions only: Disables [tiered compilation](../../../core/whats-new/dotnet-core-3-0.md) for profilers.| |`COR_PRF_HIGH_BASIC_GC`|.NET Core 3.0 and later versions only: Provides a lightweight GC profiling option compared to [`COR_PRF_MONITOR_GC`](cor-prf-monitor-enumeration.md). Controls only the [GarbageCollectionStarted](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback2-garbagecollectionstarted-method.md), [GarbageCollectionFinished](../../../../docs/framework/unmanaged-api/profiling/icorprofilercallback2-garbagecollectionfinished-method.md), and [GetGenerationBounds](icorprofilerinfo2-getgenerationbounds-method.md) callbacks. Unlike the `COR_PRF_MONITOR_GC` flag, `COR_PRF_HIGH_BASIC_GC` does not disable concurrent garbage collection.| |`COR_PRF_HIGH_MONITOR_GC_MOVED_OBJECTS`|.NET Core 3.0 and later versions only: Enables the [MovedReferences](icorprofilercallback-movedreferences-method.md) and [MovedReferences2](icorprofilercallback4-movedreferences2-method.md) callbacks for compacting GCs only.| -|`COR_PRF_HIGH_MONITOR_LARGEOBJECT_ALLOCATED`|.NET Core 3.0 and later versions only: Similar to [`COR_PRF_MONITOR_OBJECT_ALLOCATED`](cor-prf-monitor-enumeration.md), but provides information on object allocations for the Large Object Heap (LOH) only.| +|`COR_PRF_HIGH_MONITOR_LARGEOBJECT_ALLOCATED`|.NET Core 3.0 and later versions only: Similar to [`COR_PRF_MONITOR_OBJECT_ALLOCATED`](cor-prf-monitor-enumeration.md), but provides information on object allocations for the large object heap (LOH) only.| |`COR_PRF_HIGH_REQUIRE_PROFILE_IMAGE`|Represents all `COR_PRF_HIGH_MONITOR` flags that require profile-enhanced images. It corresponds to the `COR_PRF_REQUIRE_PROFILE_IMAGE` flag in the [COR_PRF_MONITOR](../../../../docs/framework/unmanaged-api/profiling/cor-prf-monitor-enumeration.md) enumeration.| |`COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH`|Represents all `COR_PRF_HIGH_MONITOR` flags that can be set after the profiler is attached to a running app.| |`COR_PRF_HIGH_MONITOR_IMMUTABLE`|Represents all `COR_PRF_HIGH_MONITOR` flags that can be set only during initialization. Trying to change any of these flags elsewhere results in an `HRESULT` value that indicates failure.| -## Remarks - The `COR_PRF_HIGH_MONITOR` flags are used with the `pdwEventsHigh` parameter of the [ICorProfilerInfo5::GetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-geteventmask2-method.md) and [ICorProfilerInfo5::SetEventMask2](../../../../docs/framework/unmanaged-api/profiling/icorprofilerinfo5-seteventmask2-method.md) methods. +## Remarks + +The `COR_PRF_HIGH_MONITOR` flags are used with the `pdwEventsHigh` parameter of the [ICorProfilerInfo5::GetEventMask2](icorprofilerinfo5-geteventmask2-method.md) and [ICorProfilerInfo5::SetEventMask2](icorprofilerinfo5-seteventmask2-method.md) methods. Starting with the .NET Framework 4.6.1, the value of the `COR_PRF_HIGH_ALLOWABLE_AFTER_ATTACH` changed from 0 to `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED` (0x00000002). Starting with the .NET Framework 4.7.2, its value changed from `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED` to `COR_PRF_HIGH_IN_MEMORY_SYMBOLS_UPDATED | COR_PRF_HIGH_MONITOR_DYNAMIC_FUNCTION_UNLOADS`. `COR_PRF_HIGH_MONITOR_IMMUTABLE` is intended to be a bitmask that represents all flags that can only be set during initialization. Trying to change any of these flags elsewhere results in a failed `HRESULT`. -## Requirements - **Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). +## Requirements + +**Platforms:** See [System Requirements](../../../../docs/framework/get-started/system-requirements.md). - **Header:** CorProf.idl, CorProf.h +**Header:** CorProf.idl, CorProf.h - **Library:** CorGuids.lib +**Library:** CorGuids.lib - **.NET Framework Versions:** [!INCLUDE[net_current_v452plus](../../../../includes/net-current-v452plus-md.md)] +**.NET Framework Versions:** [!INCLUDE[net_current_v452plus](../../../../includes/net-current-v452plus-md.md)] ## See also diff --git a/docs/framework/whats-new/index.md b/docs/framework/whats-new/index.md index 97ed270ec13b7..59171d4760d61 100644 --- a/docs/framework/whats-new/index.md +++ b/docs/framework/whats-new/index.md @@ -621,7 +621,7 @@ Starting with .NET Framework 4.7.1, diff --git a/docs/standard/garbage-collection/large-object-heap.md b/docs/standard/garbage-collection/large-object-heap.md index 18c2afdeb6780..ef138836977de 100644 --- a/docs/standard/garbage-collection/large-object-heap.md +++ b/docs/standard/garbage-collection/large-object-heap.md @@ -1,5 +1,5 @@ --- -title: "The large object heap on Windows systems" +title: LOH on Windows - .NET ms.date: "05/02/2018" helpviewer_keywords: - large object heap (LOH)" @@ -7,7 +7,6 @@ helpviewer_keywords: - "garbage collection, large object heap" - "GC [.NET ], large object heap" --- - # The large object heap on Windows systems The .NET Garbage Collector (GC) divides objects up into small and large objects. When an object is large, some of its attributes become more significant than if the object is small. For instance, compacting it -- that is, copying it in memory elsewhere on the heap -- can be expensive. Because of this, the .NET Garbage Collector places large objects on the large object heap (LOH). In this topic, we'll look at the large object heap in depth. We'll discuss what qualifies an object as a large object, how these large objects are collected, and what kind of performance implications large objects impose. @@ -17,7 +16,7 @@ The .NET Garbage Collector (GC) divides objects up into small and large objects. ## How an object ends up on the large object heap and how GC handles them -If an object is greater than or equal to 85,000 bytes, it’s considered a large object. This number was determined by performance tuning. When an object allocation request is for 85,000 or more bytes, the runtime allocates it on the large object heap. +If an object is greater than or equal to 85,000 bytes in size, it’s considered a large object. This number was determined by performance tuning. When an object allocation request is for 85,000 or more bytes, the runtime allocates it on the large object heap. To understand what this means, it's useful to examine some fundamentals about the .NET GC. @@ -27,7 +26,7 @@ Small objects are always allocated in generation 0 and, depending on their lifet Large objects belong to generation 2 because they are collected only during a generation 2 collection. When a generation is collected, all its younger generation(s) are also collected. For example, when a generation 1 GC happens, both generation 1 and 0 are collected. And when a generation 2 GC happens, the whole heap is collected. For this reason, a generation 2 GC is also called a *full GC*. This article refers to generation 2 GC instead of full GC, but the terms are interchangeable. -Generations provide a logical view of the GC heap. Physically, objects live in managed heap segments. A *managed heap segment* is a chunk of memory that the GC reserves from the OS by calling the [VirtualAlloc function](/windows/desktop/api/memoryapi/nf-memoryapi-virtualalloc) on behalf of managed code. When the CLR is loaded, the GC allocates two initial heap segments: one for small objects (the Small Object Heap, or SOH), and one for large objects (the Large Object Heap). +Generations provide a logical view of the GC heap. Physically, objects live in managed heap segments. A *managed heap segment* is a chunk of memory that the GC reserves from the OS by calling the [VirtualAlloc function](/windows/desktop/api/memoryapi/nf-memoryapi-virtualalloc) on behalf of managed code. When the CLR is loaded, the GC allocates two initial heap segments: one for small objects (the small object heap, or SOH), and one for large objects (the large object heap). The allocation requests are then satisfied by putting managed objects on these managed heap segments. If the object is less than 85,000 bytes, it is put on the segment for the SOH; otherwise, it is put on an LOH segment. Segments are committed (in smaller chunks) as more and more objects are allocated onto them. For the SOH, objects that survive a GC are promoted to the next generation. Objects that survive a generation 0 collection are now considered generation 1 objects, and so on. However, objects that survive the oldest generation are still considered to be in the oldest generation. In other words, survivors from generation 2 are generation 2 objects; and survivors from the LOH are LOH objects (which are collected with gen2). @@ -149,7 +148,7 @@ These performance counters are usually a good first step in investigating perfor A common way to look at performance counters is with Performance Monitor (perfmon.exe). Use “Add Counters” to add the interesting counter for processes that you care about. You can save the performance counter data to a log file, as Figure 4 shows: -![Screenshow that shows adding performance counters.](media/large-object-heap/add-performance-counter.png) +![Screenshot that shows adding performance counters.](media/large-object-heap/add-performance-counter.png) Figure 4: The LOH after a generation 2 GC Performance counters can also be queried programmatically. Many people collect them this way as part of their routine testing process. When they spot counters with values that are out of the ordinary, they use other means to get more detailed data to help with the investigation. @@ -301,7 +300,7 @@ To verify whether the LOH is causing VM fragmentation, you can set a breakpoint bp kernel32!virtualalloc "j (dwo(@esp+8)>800000) 'kb';'g'" ``` -This command breaks into the debugger and shows the callstack only if [VirtualAlloc](/windows/desktop/api/memoryapi/nf-memoryapi-virtualalloc) is called with an allocation size greater than 8MB (0x800000). +This command breaks into the debugger and shows the call stack only if [VirtualAlloc](/windows/desktop/api/memoryapi/nf-memoryapi-virtualalloc) is called with an allocation size greater than 8MB (0x800000). CLR 2.0 added a feature called *VM Hoarding* that can be useful for scenarios where segments (including on the large and small object heaps) are frequently acquired and released. To specify VM Hoarding, you specify a startup flag called `STARTUP_HOARD_GC_VM` via the hosting API. Instead of releasing empty segments back to the OS, the CLR decommits the memory on these segments and puts them on a standby list. (Note that the CLR doesn't do this for segments that are too large.) The CLR later uses those segments to satisfy new segment requests. The next time that your app needs a new segment, the CLR uses one from this standby list if it can find one that’s big enough. diff --git a/docs/standard/garbage-collection/latency.md b/docs/standard/garbage-collection/latency.md index 7001250cff7f2..12afaeb3dee6d 100644 --- a/docs/standard/garbage-collection/latency.md +++ b/docs/standard/garbage-collection/latency.md @@ -48,7 +48,7 @@ When you use [GCLatencyMode.LowLatency](xref:System.Runtime.GCLatencyMode.LowLat - Avoid allocating high amounts of memory during low latency periods. Low memory notifications can occur because garbage collection reclaims fewer objects. -- While in the low latency mode, minimize the number of new allocations, in particular allocations onto the Large Object Heap and pinned objects. +- While in the low latency mode, minimize the number of new allocations, in particular allocations onto the large object heap and pinned objects. - Be aware of threads that could be allocating. Because the property setting is process-wide, exceptions can be generated on any thread that is allocating.