Akka.Actor: bounded IStash programmatic configuration
#6661
Conversation
Add APIs to track content of Stash
|
Still a work in progress - haven't gotten tests and config parsing completely working yet. |
… via HOCON or config
needed for remote deployments
| @@ -843,6 +843,38 @@ The result of this is that when an actor is restarted, any stashed messages will | |||
| > [!NOTE] | |||
| > If you want to enforce that your actor can only work with an unbounded stash, then you should use the `IWithUnboundedStash` interface instead. | |||
|
|
|||
| ### Bounded Stashes | |||
|
|
|||
| In certain scenarios, it might be helpful to put a limit on the size of the `IStash` inside your actor. You can configure a bounded stash via the following actor definition: | |||
There was a problem hiding this comment.
Documented how to configure a bounded stash with both Props and akka.actor.deployment here.
| Either of these settings will configure the `IStash` to only have a maximum capacity of 2 items. If a third item is attempted to be stashed the `IStash` will throw a `StashOverflowException`. | ||
|
|
||
| > [!TIP] | ||
| > You can always check to see if your `IStash` is approaching its capacity by checking the `IStash.IsFull`, `IStash.Capacity`, or `IStash.Count` properties. |
There was a problem hiding this comment.
Instructed users how to check whether or not the bounded stash is becoming full here.
| > [!TIP] | ||
| > You can always check to see if your `IStash` is approaching its capacity by checking the `IStash.IsFull`, `IStash.Capacity`, or `IStash.Count` properties. | ||
|
|
||
| If you attempt to apply a maximum stash capacity to an `IWithUnboundedStash` actor then the setting will be ignored. |
There was a problem hiding this comment.
Caveat about applying this setting when using IWithUnboundedStash.
| @@ -758,6 +758,38 @@ Note that the stash is part of the ephemeral actor state, unlike the mailbox. Th | |||
| > [!NOTE] | |||
| > If you want to enforce that your actor can only work with an unbounded stash, then you should use the `UntypedActorWithUnboundedStash` class instead. | |||
|
|
|||
| ### Bounded Stashes | |||
There was a problem hiding this comment.
Copy and paste from the ReceiveActor page - we should probably have a separate page on behavior-switching and stashing.
| @@ -621,6 +621,7 @@ namespace Akka.Actor | |||
| public static readonly string NoDispatcherGiven; | |||
| public static readonly string NoMailboxGiven; | |||
| public static readonly Akka.Actor.Scope NoScopeGiven; | |||
| public const int NoStashSize = -1; | |||
There was a problem hiding this comment.
This what IStash.Capacity has historically defaulted to when working with unbounded stashes - all I did was turn it into a constant.
src/core/Akka/Actor/Deployer.cs
Outdated
| @@ -122,7 +122,8 @@ public virtual Deploy ParseConfig(string key, Config config) | |||
| var router = CreateRouterConfig(routerType, deployment); | |||
| var dispatcher = deployment.GetString("dispatcher", ""); | |||
| var mailbox = deployment.GetString("mailbox", ""); | |||
| var deploy = new Deploy(key, deployment, router, Deploy.NoScopeGiven, dispatcher, mailbox); | |||
| var stashCapacity = deployment.GetInt("stash-capacity", -1); | |||
There was a problem hiding this comment.
Grab stash-capacity from HOCON
| /// </remarks> | ||
| /// <param name="stashCapacity">The stash size to use when creating the actor.</param> | ||
| /// <returns>A new <see cref="Akka.Actor.Props" /> with the provided stash size..</returns> | ||
| public Props WithStashCapacity(int stashCapacity) |
There was a problem hiding this comment.
Add overload for copying in StashCapacity without having to explicitly allocate a new Deploy each time (consistent with other settings.)
| @@ -22,6 +22,8 @@ public UnboundedStashImpl(IActorContext context) | |||
| : base(context) | |||
| { | |||
| } | |||
|
|
|||
| public override int Capacity => Deploy.NoStashSize; // stash must be unbounded | |||
There was a problem hiding this comment.
UnboundedStashImpl can't be set - it's always unbounded.
| @@ -61,6 +61,7 @@ message DeployData { | |||
| string configManifest = 9; | |||
| int32 routerConfigSerializerId = 10; | |||
| string routerConfigManifest = 11; | |||
| int32 stashCapacity = 12; | |||
There was a problem hiding this comment.
Addition to wire format - if this value is missing then the stash defaults back to being unbounded.
| # Specifies the stash capacity for an individual actor, when stashing is enabled. | ||
| # A default value of -1 is used to signify that this should be an _unbounded_ stash, | ||
| # which has no upper limit on storage capacity. | ||
| stash-capacity = -1 |
There was a problem hiding this comment.
New reference for HOCON deployments.
Changes
Other half of #6660 to address #6658 - adds the ability to configure the bounded stash size via
Deployandakka.actor.deploymentin HOCON.Checklist
For significant changes, please ensure that the following have been completed (delete if not relevant):
IStashimprovements - programmatic bounded stash configuration and stash capacity APIs #6658