Package groovy.concurrent

Record Class ActorOptions

java.lang.Object
java.lang.Record
groovy.concurrent.ActorOptions
Record Components:
mailboxCapacity - the maximum mailbox (queue) size; 0 for unbounded
overflow - the policy when a bounded mailbox is full; ignored when mailboxCapacity is 0
stashCapacity - the maximum stash buffer size; 0 for unbounded (the back-compat default)
stashOverflow - the policy when a bounded stash is full; ignored when stashCapacity is 0
executor - the executor used to run the actor's processing loop; null selects the default async executor
currentSelfEnabled - when true, the actor publishes itself via a thread-local during handler dispatch so that Actor.currentSelf() can be used from inside handlers. Off by default to avoid paying for a mechanism the actor doesn't use.
public record ActorOptions(int mailboxCapacity, ActorOptions.Overflow overflow, int stashCapacity, ActorOptions.StashOverflow stashOverflow, Executor executor, boolean currentSelfEnabled) extends Record
Construction-time configuration for an Actor.

Carries the mailbox capacity / overflow policy, the optional stash capacity / overflow policy, the executor, and the opt-in flag for Actor.currentSelf() thread-local support. Pass to the Actor.reactor(java.util.function.Function, ActorOptions) or Actor.stateful(Object, java.util.function.BiFunction, ActorOptions) factory variants. Settings that can be changed after construction (currently: the error handler) are not carried here — see Actor.onError(java.util.function.BiConsumer). 


 var actor = Actor.reactor(handler,
     ActorOptions.DEFAULTS
         .withBoundedMailbox(1000, ActorOptions.Overflow.BLOCK)
         .withStashBound(64, ActorOptions.StashOverflow.REJECT)
         .withExecutor(Pool.cpu()));
Since:
6.0.0

  • Field Details

  • Constructor Details

    • ActorOptions

      public ActorOptions(int mailboxCapacity, ActorOptions.Overflow overflow, int stashCapacity, ActorOptions.StashOverflow stashOverflow, Executor executor, boolean currentSelfEnabled)
      Canonical constructor — validates that capacities are non-negative and that the overflow policies are non-null. The executor may be null (meaning "use the default").

  • Method Details

    • withBoundedMailbox

      public ActorOptions withBoundedMailbox(int capacity, ActorOptions.Overflow strategy)
      Returns a copy of these options configured with a bounded mailbox of the given capacity and overflow strategy.

      Note: capacity == 0 is rejected here even though the canonical constructor accepts it. The constructor's 0 means "explicitly unbounded"; passing 0 to this builder almost always indicates a missing real capacity, so it fails fast. To revert a bounded actor to unbounded, build a new options instance from DEFAULTS.

      Parameters:
      capacity - the mailbox capacity (must be positive)
      strategy - the overflow policy
      Returns:
      a new ActorOptions with the bounded mailbox applied
      Throws:
      IllegalArgumentException - if capacity is not positive

    • withStashBound

      public ActorOptions withStashBound(int capacity, ActorOptions.StashOverflow strategy)
      Returns a copy of these options configured with a bounded stash buffer of the given capacity and overflow strategy. Unbounded by default — set a bound when the actor accepts messages from a source whose volume you do not control and the actor may stay in a stashing phase indefinitely.
      Parameters:
      capacity - the stash capacity (must be positive)
      strategy - the overflow policy
      Returns:
      a new ActorOptions with the bounded stash applied
      Throws:
      IllegalArgumentException - if capacity is not positive
      Since:
      6.0.0

    • withExecutor

      public ActorOptions withExecutor(Executor executor)
      Returns a copy of these options configured to use the given executor for the actor's processing loop. Pass null to revert to the default async executor.
      Parameters:
      executor - the executor to use, or null for the default
      Returns:
      a new ActorOptions with the executor applied

    • withCurrentSelf

      public ActorOptions withCurrentSelf(boolean enabled)
      Returns a copy of these options with thread-local currentSelf support toggled. When enabled, the actor publishes itself into a thread-local for the duration of each handler dispatch so that Actor.currentSelf() returns the executing actor.

      Off by default. Prefer the context-aware StatefulHandler / ReactorHandler factories where possible; this knob exists for callers who want self-stop without restructuring to the context-aware handler shape.

      Parameters:
      enabled - true to enable Actor.currentSelf() support; false to disable
      Returns:
      a new ActorOptions with the flag applied
      Since:
      6.0.0

    • isBounded

      public boolean isBounded()
      Returns true if the mailbox is bounded.

    • isStashBounded

      public boolean isStashBounded()
      Returns true if the stash buffer is bounded.

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • mailboxCapacity

      public int mailboxCapacity()
      Returns the value of the mailboxCapacity record component.
      Returns:
      the value of the mailboxCapacity record component

    • overflow

      public ActorOptions.Overflow overflow()
      Returns the value of the overflow record component.
      Returns:
      the value of the overflow record component

    • stashCapacity

      public int stashCapacity()
      Returns the value of the stashCapacity record component.
      Returns:
      the value of the stashCapacity record component

    • stashOverflow

      public ActorOptions.StashOverflow stashOverflow()
      Returns the value of the stashOverflow record component.
      Returns:
      the value of the stashOverflow record component

    • executor

      public Executor executor()
      Returns the value of the executor record component.
      Returns:
      the value of the executor record component

    • currentSelfEnabled

      public boolean currentSelfEnabled()
      Returns the value of the currentSelfEnabled record component.
      Returns:
      the value of the currentSelfEnabled record component