Skip to content

Add GC heap limit settings #19423

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jul 16, 2020
Merged

Add GC heap limit settings #19423

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
62c72cf
fixes #19356
gewarren Jul 11, 2020
31f054a
feedback from andrew
gewarren Jul 13, 2020
5c8be13
Update docs/core/run-time-config/garbage-collector.md
gewarren Jul 15, 2020
6c0ebfd
per object heap - all
gewarren Jul 16, 2020
3a4ed20
Apply suggestions from David
gewarren Jul 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 37 additions & 1 deletion docs/core/run-time-config/garbage-collector.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: Garbage collector config settings
description: Learn about run-time settings for configuring how the garbage collector manages memory for .NET Core apps.
ms.date: 01/09/2020
ms.date: 07/10/2020
ms.topic: reference
---
# Run-time configuration options for garbage collection
Expand Down Expand Up @@ -234,6 +234,7 @@ Example:

- Specifies the maximum commit size, in bytes, for the GC heap and GC bookkeeping.
- This setting only applies to 64-bit computers.
- This setting is ignored if the [Per-object-heap limits](#per-object-heap-limits) are configured.
- The default value, which only applies in certain cases, is the greater of 20 MB or 75% of the memory limit on the container. The default value applies if:

- The process is running inside a container that has a specified memory limit.
Expand Down Expand Up @@ -265,6 +266,7 @@ Example:
- If [System.GC.HeapHardLimit](#systemgcheaphardlimitcomplus_gcheaphardlimit) is also set, this setting is ignored.
- This setting only applies to 64-bit computers.
- If the process is running inside a container that has a specified memory limit, the percentage is calculated as a percentage of that memory limit.
- This setting is ignored if the [Per-object-heap limits](#per-object-heap-limits) are configured.
- The default value, which only applies in certain cases, is the lesser of 20 MB or 75% of the memory limit on the container. The default value applies if:

- The process is running inside a container that has a specified memory limit.
Expand All @@ -290,6 +292,40 @@ Example:
> [!TIP]
> If you're setting the option in *runtimeconfig.json*, specify a decimal value. If you're setting the option as an environment variable, specify a hexadecimal value. For example, to limit the heap usage to 30%, the values would be 30 for the JSON file and 0x1E or 1E for the environment variable.

### Per-object-heap limits

You can specify the GC's allowable heap usage on a per-object-heap basis. The different heaps are the large object heap (LOH), small object heap (SOH), and pinned object heap (POH).

#### COMPLUS_GCHeapHardLimitSOH, COMPLUS_GCHeapHardLimitLOH, COMPLUS_GCHeapHardLimitPOH

- If you specify a value for any of the `COMPLUS_GCHeapHardLimitSOH`, `COMPLUS_GCHeapHardLimitLOH`, or `COMPLUS_GCHeapHardLimitPOH` settings, you must also specify a value for `COMPLUS_GCHeapHardLimitSOH` and `COMPLUS_GCHeapHardLimitLOH`. If you don't, the runtime will fail to initialize.
- The default value for `COMPLUS_GCHeapHardLimitPOH` is 0. `COMPLUS_GCHeapHardLimitSOH` and `COMPLUS_GCHeapHardLimitLOH` don't have default values.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- The default value for `COMPLUS_GCHeapHardLimitPOH` is 0. `COMPLUS_GCHeapHardLimitSOH` and `COMPLUS_GCHeapHardLimitLOH` don't have default values.
- The default value for `COMPLUS_GCHeapHardLimitPOH` is `0`. `COMPLUS_GCHeapHardLimitSOH` and `COMPLUS_GCHeapHardLimitLOH` don't have default values.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have not typically put numeric values in code fencing since they don't get localized. I would also need to make this change throughout this article.


| | Setting name | Values | Version introduced |
| - | - | - | - |
| **Environment variable** | `COMPLUS_GCHeapHardLimitSOH` | *hexadecimal value* | .NET 5.0 |
| **Environment variable** | `COMPLUS_GCHeapHardLimitLOH` | *hexadecimal value* | .NET 5.0 |
| **Environment variable** | `COMPLUS_GCHeapHardLimitPOH` | *hexadecimal value* | .NET 5.0 |

> [!TIP]
> If you're setting the option as an environment variable, specify a hexadecimal value. For example, to specify a heap hard limit of 200 mebibytes (MiB), the value would be 0xC800000 or C800000.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> If you're setting the option as an environment variable, specify a hexadecimal value. For example, to specify a heap hard limit of 200 mebibytes (MiB), the value would be 0xC800000 or C800000.
> If you're setting the option as an environment variable, specify a hexadecimal value. For example, to specify a heap hard limit of 200 mebibytes (MiB), the value would be `0xC800000` or `C800000`.


#### COMPLUS_GCHeapHardLimitSOHPercent, COMPLUS_GCHeapHardLimitLOHPercent, COMPLUS_GCHeapHardLimitPOHPercent

- If you specify a value for any of the `COMPLUS_GCHeapHardLimitSOHPercent`, `COMPLUS_GCHeapHardLimitLOHPercent`, or `COMPLUS_GCHeapHardLimitPOHPercent` settings, you must also specify a value for `COMPLUS_GCHeapHardLimitSOHPercent` and `COMPLUS_GCHeapHardLimitLOHPercent`. If you don't, the runtime will fail to initialize.
- These settings are ignored if `COMPLUS_GCHeapHardLimitSOH`, `COMPLUS_GCHeapHardLimitLOH`, and `COMPLUS_GCHeapHardLimitPOH` are specified.
- A value of 1 means that GC uses 1% of total physical memory for that object heap.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- A value of 1 means that GC uses 1% of total physical memory for that object heap.
- A value of `1` means that GC uses 1% of total physical memory for that object heap.

- Each value must be greater than zero and less than 100. Additionally, the sum of the three percentage values must be less than 100. Otherwise, the runtime will fail to initialize.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Each value must be greater than zero and less than 100. Additionally, the sum of the three percentage values must be less than 100. Otherwise, the runtime will fail to initialize.
- Each value must be greater than zero and less than `100`. Additionally, the sum of the three percentage values must be less than `100`. Otherwise, the runtime will fail to initialize.


| | Setting name | Values | Version introduced |
| - | - | - | - |
| **Environment variable** | `COMPLUS_GCHeapHardLimitSOHPercent` | *hexadecimal value* | .NET 5.0 |
| **Environment variable** | `COMPLUS_GCHeapHardLimitLOHPercent` | *hexadecimal value* | .NET 5.0 |
| **Environment variable** | `COMPLUS_GCHeapHardLimitPOHPercent` | *hexadecimal value* | .NET 5.0 |

> [!TIP]
> If you're setting the option as an environment variable, specify a hexadecimal value. For example, to limit the heap usage to 30%, the value would be 0x1E or 1E.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
> If you're setting the option as an environment variable, specify a hexadecimal value. For example, to limit the heap usage to 30%, the value would be 0x1E or 1E.
> If you're setting the option as an environment variable, specify a hexadecimal value. For example, to limit the heap usage to 30%, the value would be `0x1E` or `1E`.


### 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).
Expand Down