Add run-time GC settings

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

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<br/>`true` - server | .NET Core 1.0 |
+| **Environment variable** | `COMPlus_gcServer` | 0 - workstation<br/>1 - server | .NET Core 1.0 |
+| **app.config for .NET Framework** | [GCServer](../../framework/configure-apps/file-schema/runtime/gcserver-element.md) | `false` - workstation<br/>`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<br/>`false` - non-concurrent GC | .NET Core 1.0 |
+| **Environment variable** | `COMPlus_gcConcurrent` | `true` - background GC<br/>`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<br/>`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.<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 |
+| **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 |
+| **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<br/>1 - enabled | .NET Core 1.0 |
+| **app.config for .NET Framework** | [GCCpuGroup](../../framework/configure-apps/file-schema/runtime/gccpugroup-element.md) | `false` - disabled<br/>`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<br/>`true` - don't affinitize | .NET Core 3.0 |
+| **Environment variable** | `COMPlus_GCNoAffinitize` | 0 - affinitize<br/>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<br/>`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<br/>`true` - put on standby| .NET Core 1.0 |
+| **Environment variable** | `COMPlus_GCRetainVM` | 0 - release to OS<br/>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<br/>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<br/> 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 |

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 <xref:System.AppContext.SetSwitch%2A?displayProperty=nameWithType> 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 <xref:System.Environment.SetEnvironmentVariable(System.String,System.String)?displayProperty=nameWithType> 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
+```

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