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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `ActorOptions.Overflow`
  Policy applied when `Actor.send(Object)` is called on an actor whose bounded mailbox is full.
  `static enum`
  `ActorOptions.StashOverflow`
  Policy applied when `ActorContext.stash()` is called and the actor's bounded stash is already at capacity.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final ActorOptions`
  `DEFAULTS`
  Default options: unbounded mailbox, unbounded stash, default async executor, no thread-local current-self.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `currentSelfEnabled()`
  Returns the value of the `currentSelfEnabled` record component.
  `final boolean`
  `equals(Object o)`
  Indicates whether some other object is "equal to" this one.
  `Executor`
  `executor()`
  Returns the value of the `executor` record component.
  `final int`
  `hashCode()`
  Returns a hash code value for this object.
  `boolean`
  `isBounded()`
  Returns `true` if the mailbox is bounded.
  `boolean`
  `isStashBounded()`
  Returns `true` if the stash buffer is bounded.
  `int`
  `mailboxCapacity()`
  Returns the value of the `mailboxCapacity` record component.
  `ActorOptions.Overflow`
  `overflow()`
  Returns the value of the `overflow` record component.
  `int`
  `stashCapacity()`
  Returns the value of the `stashCapacity` record component.
  `ActorOptions.StashOverflow`
  `stashOverflow()`
  Returns the value of the `stashOverflow` record component.
  `final String`
  `toString()`
  Returns a string representation of this record class.
  `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.
  `ActorOptions`
  `withCurrentSelf(boolean enabled)`
  Returns a copy of these options with thread-local `currentSelf` support toggled.
  `ActorOptions`
  `withExecutor(Executor executor)`
  Returns a copy of these options configured to use the given executor for the actor's processing loop.
  `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.

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### DEFAULTS

    public static final ActorOptions DEFAULTS
    Default options: unbounded mailbox, unbounded stash, default async executor, no thread-local current-self.

    Note: the `overflow` and `stashOverflow` values carried by `DEFAULTS` are placeholders, used only when the corresponding capacity is later raised above zero via `withBoundedMailbox(int, Overflow)` or `withStashBound(int, StashOverflow)`. Read `isBounded()` / `isStashBounded()` before treating `overflow()` / `stashOverflow()` as meaningful.

- ## 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