You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Documented additional GC switches
* Updated TOC
* Update docs/core/runtime-config/envvars.md
Co-Authored-By: Maira Wenzel <mairaw@microsoft.com>
* Update docs/core/runtime-config/index.md
Co-Authored-By: Maira Wenzel <mairaw@microsoft.com>
* remove changes that are taken care of by prs #15760 and #15761
* add new elements to index file and parent element table; toc improvements
Prior to the .NET Framework 4, workstation garbage collection supported concurrent garbage collection, which performed garbage collection in the background on a separate thread. In the .NET Framework 4, concurrent garbage collection was replaced by background GC, which also performs garbage collection in the background on a separate thread. Starting with the .NET Framework 4.5, background collection became available in server garbage collection. The `<gcConcurrent>` element controls whether the runtime performs either concurrent or background garbage collection, if it's available, or whether it performs garbage collection in the foreground.
58
+
Prior to .NET Framework 4, workstation garbage collection supported concurrent garbage collection, which performed garbage collection in the background on a separate thread. In .NET Framework 4, concurrent garbage collection was replaced by background GC, which also performs garbage collection in the background on a separate thread. Starting with .NET Framework 4.5, background collection became available in server garbage collection. The **gcConcurrent** element controls whether the runtime performs either concurrent or background garbage collection, if it's available, or whether it performs garbage collection in the foreground.
59
59
60
60
### To disable background garbage collection
61
61
62
62
> [!WARNING]
63
-
> Starting with the .NET Framework 4, concurrent garbage collection is replaced by background garbage collection. The terms *concurrent* and *background* are used interchangeably in the .NET Framework documentation. To disable background garbage collection, use the `<gcConcurrent>` element, as discussed in this article.
63
+
> Starting with .NET Framework 4, concurrent garbage collection is replaced by background garbage collection. The terms *concurrent* and *background* are used interchangeably in the .NET Framework documentation. To disable background garbage collection, use the **gcConcurrent** element, as discussed in this article.
64
64
65
-
By default, the runtime uses concurrent or background garbage collection, which is optimized for latency. If your application involves heavy user interaction, leave concurrent garbage collection enabled to minimize the application's pause time to perform garbage collection. If you set the `enabled` attribute of the `<gcConcurrent>` element to `false`, the runtime uses non-concurrent garbage collection, which is optimized for throughput. The following configuration file disables background garbage collection.
65
+
By default, the runtime uses concurrent or background garbage collection, which is optimized for latency. If your application involves heavy user interaction, leave concurrent garbage collection enabled to minimize the application's pause time to perform garbage collection. If you set the `enabled` attribute of the **gcConcurrent** element to `false`, the runtime uses non-concurrent garbage collection, which is optimized for throughput.
66
+
67
+
The following configuration file disables background garbage collection:
66
68
67
69
```xml
68
70
<configuration>
@@ -72,13 +74,13 @@ By default, the runtime uses concurrent or background garbage collection, which
72
74
</configuration>
73
75
```
74
76
75
-
If there's a `<gcConcurrentSetting>` setting in the machine configuration file, it defines the default value for all .NET Framework applications. The machine configuration file setting overrides the application configuration file setting.
77
+
If there's a **gcConcurrentSetting** setting in the machine configuration file, it defines the default value for all .NET Framework applications. The machine configuration file setting overrides the application configuration file setting.
76
78
77
-
For more information on concurrent and background garbage collection, see the [Concurrent garbage collection](../../../../standard/garbage-collection/fundamentals.md#concurrent-garbage-collection) section in the [Fundamentals of Garbage Collection](../../../../standard/garbage-collection/fundamentals.md) article.
79
+
For more information on concurrent and background garbage collection, see the [Concurrent garbage collection](../../../../standard/garbage-collection/fundamentals.md#concurrent-garbage-collection), [Background workstation 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) sections in the [Fundamentals of Garbage Collection](../../../../standard/garbage-collection/fundamentals.md) article.
78
80
79
81
## Example
80
82
81
-
The following example enables concurrent garbage collection:
83
+
The following example enables background garbage collection:
Defines the affinity between GC heaps and individual processors.
11
+
12
+
\<configuration>\
13
+
\<runtime>\
14
+
\<GCHeapAffinitizeMask>
15
+
16
+
## Syntax
17
+
18
+
```xml
19
+
<GCHeapAffinitizeMask
20
+
enabled="nnnn"/>
21
+
```
22
+
23
+
## Attributes and elements
24
+
25
+
The following sections describe attributes, child elements, and parent elements.
26
+
27
+
### Attributes
28
+
29
+
|Attribute|Description|
30
+
|---------------|-----------------|
31
+
|`enabled`|Required attribute.<br /><br />Specifies the affinity between GC heaps and individual processors. |
32
+
33
+
#### enabled attribute
34
+
35
+
|Value|Description|
36
+
|-----------|-----------------|
37
+
|`nnnn`|A decimal value that forms a bitmask defining the affinity between server GC heaps and individual processors. |
38
+
39
+
### Child elements
40
+
41
+
None.
42
+
43
+
### Parent elements
44
+
45
+
|Element|Description|
46
+
|-------------|-----------------|
47
+
|`configuration`|The root element in every configuration file used by the common language runtime and .NET Framework applications.|
48
+
|`runtime`|Contains information about assembly binding and garbage collection.|
49
+
50
+
## Remarks
51
+
52
+
By default, server GC threads are hard-affinitized with their respective CPU so that there is one GC heap, one server GC thread, and one background server GC thread for each processor. Starting with .NET Framework 4.6.2, you can use the **GCHeapAffinitizeMask** element to control the affinity between server GC heaps and processors when the number of heaps is limited by the **GCHeapCount** element.
53
+
54
+
**GCHeapAffinitizeMask** is typically used along with two other flags:
55
+
56
+
-[GCNoAffinitize](gcnoaffinitize-element.md), which controls whether server GC threads/heaps are affinitized with CPUs. The `enabled` attribute of the [GCNoAffinitize](gcnoaffinitize-element.md) element must be `false` (its default value) for the **GCHeapAffinitizeMask** setting to be used.
57
+
58
+
-[GCHeapCount](gcheapcount-element.md), which limits the number of heaps used by the process for server GC. By default, there is one heap for each processor.
59
+
60
+
**nnnn** is a bit mask expressed as a decimal value. Bit 0 of byte 0 represents processor 0, bit 1 of byte 0 represents processor 1, and so on. For example:
61
+
62
+
```xml
63
+
<GCHeapAffinitizeMaskenabled="1023"/>
64
+
```
65
+
66
+
A value of 1023 is 0x3FF or 0011 1111 1111b. The process uses 10 processors, from processor 0 through processor 9.
67
+
68
+
## Example
69
+
70
+
The following example indicates that an application uses server GC with 10 heaps/threads. Since you don't want those heaps to overlap with heaps from other applications running on the system, use **GCHeapAffinitizeMask** to specify that the process should use CPUs 0 through 9.
Specifies the number of heaps/threads to use for server garbage collection.
11
+
12
+
\<configuration>\
13
+
\<runtime>\
14
+
\<GCHeapCount>
15
+
16
+
## Syntax
17
+
18
+
```xml
19
+
<GCHeapCount
20
+
enabled="nn"/>
21
+
```
22
+
23
+
## Attributes and elements
24
+
25
+
The following sections describe attributes, child elements, and parent elements.
26
+
27
+
### Attributes
28
+
29
+
|Attribute|Description|
30
+
|---------------|-----------------|
31
+
|`enabled`|Required attribute.<br /><br />Specifies the number of heaps to use for server garbage collection. The actual number of heaps is the minimum of the number of heaps you specify and the number of processors your process is allowed to use. |
32
+
33
+
#### enabled attribute
34
+
35
+
|Value|Description|
36
+
|-----------|-----------------|
37
+
|`nn`|The number of heaps to use for server GC.|
38
+
39
+
### Child elements
40
+
41
+
None.
42
+
43
+
### Parent elements
44
+
45
+
|Element|Description|
46
+
|-------------|-----------------|
47
+
|`configuration`|The root element in every configuration file used by the common language runtime and .NET Framework applications.|
48
+
|`runtime`|Contains information about assembly binding and garbage collection.|
49
+
50
+
## Remarks
51
+
52
+
By default, server GC threads are hard-affinitized with their respective CPU so that there is one GC heap, one server GC thread, and one background server GC thread for each processor. Starting with .NET Framework 4.6.2, you can use the **GCHeapCount** element to limit the number of heaps used by your application for server GC. Limiting the number of heaps used for server GC is particularly useful for systems that run multiple instances of a server application.
53
+
54
+
**GCHeapCount** is typically used along with two other flags:
55
+
56
+
-[GCNoAffinitize](gcnoaffinitize-element.md), which controls whether server GC threads/heaps are affinitized with CPUs.
57
+
58
+
-[GCHeapAffinitizeMask](gcheapaffinitizemask-element.md), which controls the affinity of GC threads/heaps with CPUs.
59
+
60
+
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.
61
+
62
+
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.
63
+
64
+
## Example
65
+
66
+
The following example indicates that an application uses server GC with 10 heaps/threads. Since you don't want those heaps to overlap with heaps from other applications running on the system, you use the **GCHeapAffinitizeMask** to specify that the process should use CPUs 0 through 9.
67
+
68
+
```xml
69
+
<configuration>
70
+
<runtime>
71
+
<gcServerenabled="true"/>
72
+
<GCHeapCountenabled="10"/>
73
+
<GCHeapAffinitizeMaskenabled="1023"/>
74
+
</runtime>
75
+
</configuration>
76
+
```
77
+
78
+
The following example does not affinitize server GC threads and limits the number of GC heaps/threads to 10.
Specifies whether or not to affinitize server GC threads with CPUs.
11
+
12
+
\<configuration>\
13
+
\<runtime>\
14
+
\<GCNoAffinitize>
15
+
16
+
## Syntax
17
+
18
+
```xml
19
+
<GCNoAffinitize
20
+
enabled="true|false"/>
21
+
```
22
+
23
+
## Attributes and elements
24
+
25
+
The following sections describe attributes, child elements, and parent elements.
26
+
27
+
### Attributes
28
+
29
+
|Attribute|Description|
30
+
|---------------|-----------------|
31
+
|`enabled`|Required attribute.<br /><br />Specifies whether server GC threads/heaps are affinitized with the processors available on the machine.|
32
+
33
+
#### enabled attribute
34
+
35
+
|Value|Description|
36
+
|-----------|-----------------|
37
+
|`false`|Affinitizes server GC threads with CPUs. This is the default.|
38
+
|`true`|Does not affinitize server GC threads with CPUs.|
39
+
40
+
### Child elements
41
+
42
+
None.
43
+
44
+
### Parent elements
45
+
46
+
|Element|Description|
47
+
|-------------|-----------------|
48
+
|`configuration`|The root element in every configuration file used by the common language runtime and .NET Framework applications.|
49
+
|`runtime`|Contains information about assembly binding and garbage collection.|
50
+
51
+
## Remarks
52
+
53
+
By default, server GC threads are hard-affinitized with their respective CPUs. Each of the system's available processors has its own GC heap and thread. This is typically the preferred setting since it optimizes cache usage. Starting with .NET Framework 4.6.2, by setting the **GCNoAffinitize** element's `enabled` attribute to `false`, you can specify that server GC threads and CPUs should not be tightly coupled.
54
+
55
+
You can specify the **GCNoAffinitize** configuration element alone to not affinitize server GC threads with CPUs. You can also use it along with the [GCHeapCount](gcheapcount-element.md) element to control the number of GC heaps and threads used by an application.
56
+
57
+
If the `enabled` attribute of the **GCNoAffinitize** element is `false` (its default value), you can also use the [GCHeapCount](gcheapcount-element.md) element to specify the number of GC threads and heaps, along with the [GCHeapAffinitizeMask](gcheapaffinitizemask-element.md) element to specify the processors to which the GC threads and heaps are affinitized.
58
+
59
+
## Example
60
+
61
+
The following example does not hard-affinitize server GC threads:
62
+
63
+
```xml
64
+
<configuration>
65
+
<runtime>
66
+
<gcServerenabled="true"/>
67
+
<GCNoAffinitizeenabled="true"/>
68
+
</runtime>
69
+
</configuration>
70
+
```
71
+
72
+
The following example does not affinitize server GC threads and limits the number of GC heaps/threads to 10:
0 commit comments