Package: groovy.concurrent

## [Java] Record ActorOptions

- groovy.concurrent.ActorOptions

-     public record ActorOptions
      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 or Actor.stateful factory variants. Settings that can be changed after construction (currently: the error handler) are not carried here — see Actor.onError.

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

  Parameters:
    `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.
  Since:
    6.0.0

- - ### Nested Class Summary

    Nested classes
    Modifiers | Name | Description
    --- | --- | ---
    `enum` | `ActorOptions.Overflow` | Policy applied when Actor.send is called on an actor whose bounded mailbox is full.
    `enum` | `ActorOptions.StashOverflow` | Policy applied when ActorContext.stash is called and the actor's bounded stash is already at capacity.

  - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `static ActorOptions` | `DEFAULTS` | Default options: unbounded mailbox, unbounded stash, default async executor, no thread-local current-self.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `ActorOptions()` Canonical constructor — validates that capacities are non-negative and that the overflow policies are non-null.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public boolean` | `isBounded()` Returns `true` if the mailbox is bounded.
    `` | `public boolean` | `isStashBounded()` Returns `true` if the stash buffer is bounded.
    `` | `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.
    `` | `public ActorOptions` | `withCurrentSelf(boolean enabled)` Returns a copy of these options with thread-local `currentSelf` support toggled.
    `` | `public ActorOptions` | `withExecutor(Executor executor)` Returns a copy of these options configured to use the given executor for the actor's processing loop.
    `` | `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.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Record` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

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

    - #### public ActorOptions()

      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 Detail

    - #### public boolean isBounded()

      Returns `true` if the mailbox is bounded.

    - #### public boolean isStashBounded()

      Returns `true` if the stash buffer is bounded.

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

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

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

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

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

      throws:
        IllegalArgumentException if `capacity` is not positive
      Parameters:
        `capacity` - the stash capacity (must be positive)
        `strategy` - the overflow policy
      Returns:
        a new `ActorOptions` with the bounded stash applied
      Since:
        6.0.0