From da59a7d42f3fb3b76fa8eb2a5386fa39a72e1293 Mon Sep 17 00:00:00 2001 From: Reuben Bond <203839+ReubenBond@users.noreply.github.com> Date: Thu, 15 Feb 2024 09:01:06 -0800 Subject: [PATCH] Remove inaccurate references to "garbage", fix default for Orleans 7.x+ (#39452) * Remove inaccurate references to "garbage", fix default for Orleans 7.x+ * lint fix * clarify version * Rename article * Add redirect * review feedback --- .openpublishing.redirection.orleans.json | 6 +- ...collection.md => activation-collection.md} | 61 ++++++++++++------- docs/orleans/toc.yml | 4 +- 3 files changed, 47 insertions(+), 24 deletions(-) rename docs/orleans/host/configuration-guide/{activation-garbage-collection.md => activation-collection.md} (50%) diff --git a/.openpublishing.redirection.orleans.json b/.openpublishing.redirection.orleans.json index 63c60d045b319..976f95f94b66e 100644 --- a/.openpublishing.redirection.orleans.json +++ b/.openpublishing.redirection.orleans.json @@ -35,6 +35,10 @@ { "source_path_from_root": "/docs/orleans/tutorials-and-samples/testing.md", "redirect_url": "/dotnet/orleans/implementation/testing" + }, + { + "source_path_from_root": "/docs/orleans/host/configuration-guide/activation-garbage-collection.md", + "redirect_url": "/dotnet/orleans/host/configuration-guide/activation-collection" } ] -} \ No newline at end of file +} diff --git a/docs/orleans/host/configuration-guide/activation-garbage-collection.md b/docs/orleans/host/configuration-guide/activation-collection.md similarity index 50% rename from docs/orleans/host/configuration-guide/activation-garbage-collection.md rename to docs/orleans/host/configuration-guide/activation-collection.md index e0ef347441a9c..e67de9a5a5427 100644 --- a/docs/orleans/host/configuration-guide/activation-garbage-collection.md +++ b/docs/orleans/host/configuration-guide/activation-collection.md @@ -1,20 +1,30 @@ --- -title: Activation garbage collection -description: Learn about activation garbage collection in .NET Orleans. -ms.date: 08/25/2023 +title: Activation collection +description: Learn about activation collection in .NET Orleans. +ms.date: 02/07/2024 +zone_pivot_groups: orleans-version --- -# Activation garbage collection +# Activation collection + +:::zone target="docs" pivot="orleans-7-0" + +This article applies to: ✔️ Orleans 7.x and later versions +:::zone-end + +:::zone target="docs" pivot="orleans-3-x" + This article applies to: ✔️ Orleans 3.x and earlier versions +:::zone-end A *grain activation* is an in-memory instance of a grain class that gets automatically created by the Orleans runtime on an as-needed basis as a temporary physical embodiment of a grain. -Activation Garbage Collection (Activation GC) is the process of removal from memory of unused grain activations. It's conceptually similar to how garbage collection of memory works in .NET. However, Activation GC only takes into consideration how long a particular grain activation has been idle. Memory usage isn't used as a factor. +Activation collection is the process of removal from memory of unused grain activations. It's conceptually similar to how garbage collection of memory works in .NET. However, activation collection only takes into consideration how long a particular grain activation has been idle. Memory usage isn't used as a factor. -## How activation GC works +## How activation collection works -The general process of Activation GC involves Orleans runtime in a silo periodically scanning for grain activations that haven't been used at all for the configured period (Collection Age Limit). Once a grain activation has been idle for that long, it gets deactivated. The deactivation process begins by the runtime calling the grain's method, and completes by removing references to the grain activation object from all data structures of the silo, so that the memory is reclaimed by the .NET GC. +The general process of activation collection involves Orleans runtime in a silo periodically scanning for grain activations that haven't been used at all for the configured period (Collection Age Limit). Once a grain activation has been idle for that long, it gets deactivated. The deactivation process begins by the runtime calling the grain's method, and completes by removing references to the grain activation object from all data structures of the silo, so that the memory is reclaimed by the .NET GC. As a result, with no burden put on the application code, only recently used grain activations stay in memory while activations that aren't used anymore get automatically removed, and system resources used by them get reclaimed by the runtime. @@ -32,37 +42,46 @@ As a result, with no burden put on the application code, only recently used grai **Collection Age Limit** -This time after which an idle grain activation becomes subject to Activation GC is called Collection Age Limit. The default Collection Age Limit is 2 hours, but it can be changed globally or for individual grain classes. + +:::zone target="docs" pivot="orleans-7-0" + +This time after which an idle grain activation becomes subject to collection is called Collection Age Limit. The default Collection Age Limit is 15 minutes, but it can be changed globally or for individual grain classes. +:::zone-end + +:::zone target="docs" pivot="orleans-3-x" + +This time after which an idle grain activation becomes subject to collection is called Collection Age Limit. The default Collection Age Limit is 2 hours, but it can be changed globally or for individual grain classes. +:::zone-end -## Explicit control of activation garbage collection +## Explicit control of activation collection -### Delay activation GC +### Delay activation collection -A grain activation can delay its own Activation GC, by calling method: +A grain activation can delay its own collection, by calling method: ```csharp protected void DelayDeactivation(TimeSpan timeSpan) ``` -This call ensures that this activation isn't deactivated for at least the specified time duration. It takes priority over Activation Garbage Collection settings specified in the config, but doesn't cancel them. Therefore, this call provides another hook to **delay the deactivation beyond what is specified in the Activation Garbage Collection settings**. This call can't be used to expedite Activation Garbage Collection. +This call ensures that this activation isn't deactivated for at least the specified time duration. It takes priority over activation collection settings specified in the config, but doesn't cancel them. Therefore, this call provides another hook to **delay the deactivation beyond what is specified in the activation collection settings**. This call can't be used to expedite activation collection. -A positive `timeSpan` value means "prevent GC of this activation for that time." +A positive `timeSpan` value means "prevent collection of this activation for that time." -A negative `timeSpan` value means "cancel the previous setting of the `DelayDeactivation` call and make this activation behave based on the regular Activation Garbage Collection settings." +A negative `timeSpan` value means "cancel the previous setting of the `DelayDeactivation` call and make this activation behave based on the regular activation collection settings." **Scenarios:** -1. Activation Garbage Collection settings specify an age limit of 10 minutes and the grain is making a call to `DelayDeactivation(TimeSpan.FromMinutes(20))`, which causes this activation to not be collected for at least 20 min. +1. Activation collection settings specify an age limit of 10 minutes and the grain is making a call to `DelayDeactivation(TimeSpan.FromMinutes(20))`, which causes this activation to not be collected for at least 20 min. -1. Activation Garbage Collection settings specify an age limit of 10 minutes and the grain is making a call to `DelayDeactivation(TimeSpan.FromMinutes(5))`, the activation will be collected after 10 min, if no extra calls were made. +1. Activation collection settings specify an age limit of 10 minutes and the grain is making a call to `DelayDeactivation(TimeSpan.FromMinutes(5))`, the activation will be collected after 10 min, if no extra calls were made. -1. Activation Garbage Collection settings specify an age limit of 10 minutes and the grain is making a call to `DelayDeactivation(TimeSpan.FromMinutes(5))`, and after 7 minutes there's another call on this grain, the activation will be collected after 17 min from time zero if no extra calls were made. +1. Activation collection settings specify an age limit of 10 minutes and the grain is making a call to `DelayDeactivation(TimeSpan.FromMinutes(5))`, and after 7 minutes there's another call on this grain, the activation will be collected after 17 min from time zero if no extra calls were made. -1. Activation Garbage Collection settings specify an age limit of 10 minutes and the grain is making a call to `DelayDeactivation(TimeSpan.FromMinutes(20))`, and after 7 minutes there's another call on this grain, the activation will be collected after 20 min from time zero if no extra calls were made. +1. Activation collection settings specify an age limit of 10 minutes and the grain is making a call to `DelayDeactivation(TimeSpan.FromMinutes(20))`, and after 7 minutes there's another call on this grain, the activation will be collected after 20 min from time zero if no extra calls were made. The `DelayDeactivation` doesn't 100% guarantee that the grain activation won't be deactivated before the specified time expires. Certain failure cases may cause 'premature' deactivation of grains. That means that `DelayDeactivation` **can not be used as a means to 'pin' a grain activation in memory forever or to a specific silo**. `DelayDeactivation` is merely an optimization mechanism that can help reduce the aggregate cost of a grain getting deactivated and reactivated over time. In most cases, there should be no need to use `DelayDeactivation` at all. -### Expedite activation GC +### Expedite activation collection A grain activation can also instruct the runtime to deactivate it the next time it becomes idle by calling method: @@ -72,14 +91,14 @@ protected void DeactivateOnIdle() A grain activation is considered idle if it isn't processing any message at the moment. If you call `DeactivateOnIdle` while a grain is processing a message, it gets deactivated as soon as the processing of the current message is finished. If there are any requests queued for the grain, they'll be forwarded to the next activation. -`DeactivateOnIdle` takes priority over any Activation Garbage Collection settings specified in the config or `DelayDeactivation`. +`DeactivateOnIdle` takes priority over any activation collection settings specified in the config or `DelayDeactivation`. > [!NOTE] > Setting only applies to the grain activation from which it has been called and it does not apply to other grain activation of this type. ## Configuration -Grain garbage collection can be configured using the : +Activation collection can be configured using the : ```csharp mySiloHostBuilder.Configure(options => diff --git a/docs/orleans/toc.yml b/docs/orleans/toc.yml index 8819e1dd49dfa..bd72065ba0298 100644 --- a/docs/orleans/toc.yml +++ b/docs/orleans/toc.yml @@ -138,8 +138,8 @@ items: href: host/configuration-guide/typical-configurations.md - name: Options classes href: host/configuration-guide/list-of-options-classes.md - - name: Activation garbage collection - href: host/configuration-guide/activation-garbage-collection.md + - name: Activation collection + href: host/configuration-guide/activation-collection.md - name: Configure .NET garbage collection href: host/configuration-guide/configuring-garbage-collection.md - name: Configure ADO.NET providers