Skip to content

Commit 35e6af6

Browse files
gewarrenBillWagnermairaw
authored
Add run-time GC settings (#15844)
* add run-time config knobs for GC * Apply suggestions from maira and bill Co-Authored-By: Bill Wagner <[email protected]> Co-Authored-By: Maira Wenzel <[email protected]>
1 parent 801ea86 commit 35e6af6

File tree

11 files changed

+339
-70
lines changed

11 files changed

+339
-70
lines changed

‎docs/breadcrumb/toc.yml‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -115,12 +115,15 @@
115115
tocHref: /dotnet/core/
116116
topicHref: /dotnet/core/index
117117
items:
118-
- name: Tools
119-
tocHref: /dotnet/core/tools/
120-
topicHref: /dotnet/core/tools/index
121118
- name: Compatibility
122119
tocHref: /dotnet/core/compatibility/
123120
topicHref: /dotnet/core/compatibility/index
121+
- name: Run-time configuration
122+
tocHref: /dotnet/core/run-time-config/
123+
topicHref: /dotnet/core/run-time-config/index
124+
- name: Tools
125+
tocHref: /dotnet/core/tools/
126+
topicHref: /dotnet/core/tools/index
124127
- name: .NET Framework
125128
tocHref: /dotnet/framework/
126129
topicHref: /dotnet/framework/index

‎docs/core/run-time-config/garbage-collector.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
---
2+
title: Garbage collector config settings
3+
description: Learn about run-time settings for configuring how the garbage collector manages memory.
4+
ms.date: 11/13/2019
5+
ms.topic: reference
6+
---
7+
# Run-time configuration options for garbage collection
8+
9+
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.
10+
11+
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.
12+
13+
> [!NOTE]
14+
>
15+
> - These settings can also be changed dynamically by the app as it's running, so any run-time settings you set may be overridden.
16+
> - 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.
17+
18+
## Flavors of garbage collection
19+
20+
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).
21+
22+
The subflavors of garbage collection are background and non-concurrent.
23+
24+
Use the following settings to select flavors of garbage collection:
25+
26+
### System.GC.Server/COMPlus_gcServer
27+
28+
- Configures whether the application uses workstation garbage collection or server garbage collection.
29+
- Default: Workstation garbage collection (`false`).
30+
- For more information, see [Configure garbage collection](../../standard/garbage-collection/fundamentals.md#configuring-garbage-collection).
31+
32+
| | Setting name | Values | Version introduced |
33+
| - | - | - | - |
34+
| **runtimeconfig.json** | `System.GC.Server` | `false` - workstation<br/>`true` - server | .NET Core 1.0 |
35+
| **Environment variable** | `COMPlus_gcServer` | 0 - workstation<br/>1 - server | .NET Core 1.0 |
36+
| **app.config for .NET Framework** | [GCServer](../../framework/configure-apps/file-schema/runtime/gcserver-element.md) | `false` - workstation<br/>`true` - server | |
37+
38+
### System.GC.Concurrent/COMPlus_gcConcurrent
39+
40+
- Configures whether background (concurrent) garbage collection is enabled.
41+
- Default: Enabled (`true`).
42+
- 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).
43+
44+
| | Setting name | Values | Version introduced |
45+
| - | - | - | - |
46+
| **runtimeconfig.json** | `System.GC.Concurrent` | `true` - background GC<br/>`false` - non-concurrent GC | .NET Core 1.0 |
47+
| **Environment variable** | `COMPlus_gcConcurrent` | `true` - background GC<br/>`false` - non-concurrent GC | .NET Core 1.0 |
48+
| **app.config for .NET Framework** | [gcConcurrent](../../framework/configure-apps/file-schema/runtime/gcconcurrent-element.md) | `true` - background GC<br/>`false` - non-concurrent GC | |
49+
50+
## Manage resource usage
51+
52+
Use the settings described in this section to manage the garbage collector's memory and processor usage.
53+
54+
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.
55+
56+
### System.GC.HeapCount/COMPlus_GCHeapCount
57+
58+
- Limits the number of heaps created by the garbage collector.
59+
- Applies to server garbage collection (GC) only.
60+
- 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.)
61+
- If GC thread/processor affinity is disabled, this setting limits the number of GC heaps.
62+
- For more information, see the [GCHeapCount remarks](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md#remarks).
63+
64+
| | Setting name | Values | Version introduced |
65+
| - | - | - | - |
66+
| **runtimeconfig.json** | `System.GC.HeapCount` | *number* | .NET Core 3.0 |
67+
| **Environment variable** | `COMPlus_GCHeapCount` | *number* | .NET Core 3.0 |
68+
| **app.config for .NET Framework** | [GCHeapCount](../../framework/configure-apps/file-schema/runtime/gcheapcount-element.md) | *number* | 4.6.2 |
69+
70+
### System.GC.HeapAffinitizeMask/COMPlus_GCHeapAffinitizeMask
71+
72+
- Specifies the exact processors that garbage collector threads should use.
73+
- If processor affinity is disabled by setting `System.GC.NoAffinitize` to `true`, this setting is ignored.
74+
- Applies to server garbage collection (GC) only.
75+
- 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.
76+
77+
| | Setting name | Values | Version introduced |
78+
| - | - | - | - |
79+
| **runtimeconfig.json** | `System.GC.HeapAffinitizeMask` | *decimal value* | .NET Core 3.0 |
80+
| **Environment variable** | `COMPlus_GCHeapAffinitizeMask` | *decimal value* | .NET Core 3.0 |
81+
| **app.config for .NET Framework** | [GCHeapAffinitizeMask](../../framework/configure-apps/file-schema/runtime/gcheapaffinitizemask-element.md) | *decimal value* | 4.6.2 |
82+
83+
### System.GC.GCHeapAffinitizeRanges/COMPlus_GCHeapAffinitizeRanges
84+
85+
- Specifies the list of processors to use for garbage collector threads.
86+
- This setting is similar to `System.GC.HeapAffinitizeMask`, except it allows you to specify more than 64 processors.
87+
- 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".
88+
- If processor affinity is disabled by setting `System.GC.NoAffinitize` to `true`, this setting is ignored.
89+
- Applies to server garbage collection (GC) only.
90+
- 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.
91+
92+
| | Setting name | Values | Version introduced |
93+
| - | - | - | - |
94+
| **runtimeconfig.json** | `System.GC.GCHeapAffinitizeRanges` | Comma-separated list of processor numbers or ranges of processor numbers.<br/>Unix example: "1-10,12,50-52,70"<br/>Windows example: "0:1-10,0:12,1:50-52,1:70" | .NET Core 1.0 |
95+
| **Environment variable** | `COMPlus_GCHeapAffinitizeRanges` | Comma-separated list of processor numbers or ranges of processor numbers.<br/>Unix example: "1-10,12,50-52,70"<br/>Windows example: "0:1-10,0:12,1:50-52,1:70" | .NET Core 1.0 |
96+
| **app.config for .NET Framework** | N/A | N/A | N/A |
97+
98+
### COMPlus_GCCpuGroup
99+
100+
- Configures whether the garbage collector uses [CPU groups](/windows/win32/procthread/processor-groups) or not.
101+
102+
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.
103+
104+
- Applies to server garbage collection (GC) on 64-bit Windows operation systems only.
105+
- Default: Disabled (0).
106+
- For more information, see [Maoni Stephens' blog entry](https://devblogs.microsoft.com/dotnet/making-cpu-configuration-better-for-gc-on-machines-with-64-cpus/).
107+
108+
| | Setting name | Values | Version introduced |
109+
| - | - | - | - |
110+
| **runtimeconfig.json** | N/A | N/A | N/A |
111+
| **Environment variable** | `COMPlus_GCCpuGroup` | 0 - disabled<br/>1 - enabled | .NET Core 1.0 |
112+
| **app.config for .NET Framework** | [GCCpuGroup](../../framework/configure-apps/file-schema/runtime/gccpugroup-element.md) | `false` - disabled<br/>`true` - enabled | |
113+
114+
### System.GC.NoAffinitize/COMPlus_GCNoAffinitize
115+
116+
- 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.
117+
- Applies to server garbage collection (GC) only.
118+
- Default: Affinitize garbage collection threads with processors (`false`).
119+
120+
| | Setting name | Values | Version introduced |
121+
| - | - | - | - |
122+
| **runtimeconfig.json** | `System.GC.NoAffinitize` | `false` - affinitize<br/>`true` - don't affinitize | .NET Core 3.0 |
123+
| **Environment variable** | `COMPlus_GCNoAffinitize` | 0 - affinitize<br/>1 - don't affinitize | .NET Core 3.0 |
124+
| **app.config for .NET Framework** | [GCNoAffinitize](../../framework/configure-apps/file-schema/runtime/gcnoaffinitize-element.md) | `false` - affinitize<br/>`true` - don't affinitize | 4.6.2 |
125+
126+
### System.GC.HeapHardLimit/COMPlus_GCHeapHardLimit
127+
128+
- Specifies the maximum commit size, in bytes, for the GC heap.
129+
- The value can range from 0 to 18,446,744,073,709,551,615.
130+
131+
| | Setting name | Values | Version introduced |
132+
| - | - | - | - |
133+
| **runtimeconfig.json** | `System.GC.HeapHardLimit` | *decimal value* | .NET Core 3.0 |
134+
| **Environment variable** | `COMPlus_GCHeapHardLimit` | *decimal value* | .NET Core 3.0 |
135+
136+
### System.GC.HeapHardLimitPercent/COMPlus_GCHeapHardLimitPercent
137+
138+
- Specifies the GC heap usage as a percentage of the total memory.
139+
- Example value: 25
140+
141+
| | Setting name | Values | Version introduced |
142+
| - | - | - | - |
143+
| **runtimeconfig.json** | `System.GC.HeapHardLimitPercent` | *percentage* | .NET Core 3.0 |
144+
| **Environment variable** | `COMPlus_GCHeapHardLimitPercent` | *percentage* | .NET Core 3.0 |
145+
146+
### System.GC.RetainVM/COMPlus_GCRetainVM
147+
148+
- 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).
149+
- Default: Release segments back to the operating system (`false`).
150+
151+
| | Setting name | Values | Version introduced |
152+
| - | - | - | - |
153+
| **runtimeconfig.json** | `System.GC.RetainVM` | `false` - release to OS<br/>`true` - put on standby| .NET Core 1.0 |
154+
| **Environment variable** | `COMPlus_GCRetainVM` | 0 - release to OS<br/>1 - put on standby | .NET Core 1.0 |
155+
156+
## Large pages
157+
158+
### COMPlus_GCLargePages
159+
160+
- Specifies whether large pages should be used when a heap hard limit is set.
161+
- Default: Disabled (0).
162+
- This is an experimental setting.
163+
164+
| | Setting name | Values | Version introduced |
165+
| - | - | - | - |
166+
| **runtimeconfig.json** | N/A | N/A | N/A |
167+
| **Environment variable** | `COMPlus_GCLargePages` | 0 - disabled<br/>1 - enabled | .NET Core 1.0 |
168+
| **app.config for .NET Framework** | N/A | N/A | N/A |
169+
170+
## Large objects
171+
172+
### COMPlus_gcAllowVeryLargeObjects
173+
174+
- Configures garbage collector support on 64-bit platforms for arrays that are greater than 2 gigabytes (GB) in total size.
175+
- Default: Enabled (1).
176+
- This option may become obsolete in a future version of .NET.
177+
178+
| | Setting name | Values | Version introduced |
179+
| - | - | - | - |
180+
| **runtimeconfig.json** | N/A | N/A | N/A |
181+
| **Environment variable** | `COMPlus_gcAllowVeryLargeObjects` | 1 - enabled<br/> 0 - disabled | .NET Core 1.0 |
182+
183+
## Large object heap threshold
184+
185+
### System.GC.LOHThreshold/COMPlus_GCLOHThreshold
186+
187+
- Specifies the threshold size, in bytes, that causes objects to go on the large object heap (LOH).
188+
189+
| | Setting name | Values | Version introduced |
190+
| - | - | - | - |
191+
| **runtimeconfig.json** | `System.GC.LOHThreshold` | *size in bytes* | .NET Core 1.0 |
192+
| **Environment variable** | `COMPlus_GCLOHThreshold` | *size in bytes* | .NET Core 1.0 |
193+
194+
## Standalone GC
195+
196+
### COMPlus_GCName
197+
198+
- Specifies a path to the library containing the garbage collector that the runtime intends to load.
199+
- For more information, see [Standalone GC loader design](https://github.com/dotnet/coreclr/blob/master/Documentation/design-docs/standalone-gc-loading.md).
200+
201+
| | Setting name | Values | Version introduced |
202+
| - | - | - | - |
203+
| **runtimeconfig.json** | N/A | N/A | N/A |
204+
| **Environment variable** | `COMPlus_GCName` | *string_path* | .NET Core 1.0 |

‎docs/core/run-time-config/index.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: Run-time config
3+
description: Learn how to configure .NET Core applications by using run-time configuration settings.
4+
ms.date: 11/13/2019
5+
---
6+
# .NET Core run-time configuration settings
7+
8+
.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:
9+
10+
- You don't own or control the source code for an application and therefore are unable to configure it programmatically.
11+
12+
- Multiple instances of your application run at the same time on a single system, and you want to configure each for optimum performance.
13+
14+
> [!NOTE]
15+
> 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).
16+
17+
.NET Core provides the following mechanisms for configuring applications at run time:
18+
19+
- The [runtimeconfig.json file](#runtimeconfigjson)
20+
21+
- [Environment variables](#environment-variables)
22+
23+
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.
24+
25+
## runtimeconfig.json
26+
27+
Specify run-time configuration options in the **configProperties** section of the *runtimeconfig.json* file. This section has the form:
28+
29+
```json
30+
{
31+
"runtimeOptions": {
32+
"configProperties": {
33+
"config-property-name1": "config-value1",
34+
"config-property-name2": "config-value2"
35+
}
36+
}
37+
}
38+
```
39+
40+
Here is an example file:
41+
42+
```json
43+
{
44+
"runtimeOptions": {
45+
"configProperties": {
46+
"System.GC.Concurrent": true,
47+
"System.GC.RetainVM": true,
48+
"System.Threading.ThreadPool.MinThreads": "4",
49+
"System.Threading.ThreadPool.MaxThreads": "25"
50+
}
51+
}
52+
}
53+
```
54+
55+
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.
56+
57+
Some configuration values can also be set programmatically by calling the <xref:System.AppContext.SetSwitch%2A?displayProperty=nameWithType> method.
58+
59+
## Environment variables
60+
61+
Environment variables can be used to to supply some run-time configuration information. Configuration knobs specified as environment variables generally have the prefix **COMPlus_**.
62+
63+
You can define environment variables from the Windows Control Panel, at the command line, or programmatically by calling the <xref:System.Environment.SetEnvironmentVariable(System.String,System.String)?displayProperty=nameWithType> method on both Windows and Unix-based systems.
64+
65+
The following examples show how to set an environment variable at the command line:
66+
67+
```shell
68+
# Windows
69+
set COMPlus_GCRetainVM=1
70+
71+
# Powershell
72+
$env:COMPlus_GCRetainVM="1"
73+
74+
# Unix
75+
export COMPlus_GCRetainVM=1
76+
```

‎docs/core/toc.yml‎

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -54,27 +54,33 @@
5454
href: tutorials/cli-templates-create-template-pack.md
5555
- name: Get started with .NET Core on macOS
5656
href: tutorials/using-on-macos.md
57-
- name: Get started with .NET Core on macOS using Visual Studio for Mac
57+
- name: Get started with .NET Core using Visual Studio for Mac
5858
href: tutorials/using-on-mac-vs.md
59-
- name: Building a complete .NET Core solution on macOS using Visual Studio for Mac
59+
- name: Build a complete .NET Core solution on macOS
6060
href: tutorials/using-on-mac-vs-full-solution.md
6161
- name: Get started with .NET Core using the CLI tools
6262
href: tutorials/using-with-xplat-cli.md
63-
- name: Organizing and testing projects with the .NET Core command line
63+
- name: Organize and test projects with the .NET Core CLI
6464
href: tutorials/testing-with-cli.md
65-
- name: Developing Libraries with Cross Platform Tools
65+
- name: Develop libraries with cross-platform tools
6666
href: tutorials/libraries.md
67-
- name: Create a .NET Core application with plugins
68-
href: tutorials/creating-app-with-plugin-support.md
69-
- name: Developing ASP.NET Core applications
67+
- name: Create a .NET Core app with plugins
68+
href: tutorials/creating-app-with-plugin-support.md
69+
- name: Develop ASP.NET Core apps
7070
href: tutorials/aspnet-core.md
71-
- name: Hosting .NET Core from native code
71+
- name: Host .NET Core from native code
7272
href: tutorials/netcore-hosting.md
73-
- name: Native Interoperability
73+
- name: Run-time configuration
7474
items:
75-
- name: Exposing .NET Core Components to COM
75+
- name: Settings
76+
href: run-time-config/index.md
77+
- name: Garbage collector settings
78+
href: run-time-config/garbage-collector.md
79+
- name: Native interoperability
80+
items:
81+
- name: Expose .NET Core components to COM
7682
href: native-interop/expose-components-to-com.md
77-
- name: Packages, Metapackages and Frameworks
83+
- name: Packages, Metapackages, and Frameworks
7884
href: packages.md
7985
- name: Changes in CLI overview
8086
href: tools/cli-msbuild-architecture.md

0 commit comments

Comments
 (0)