Package: groovy.concurrent

## [Java] Class Agent<T>

- groovy.concurrent.Agent

-     public final class Agent<T>
      extends Object

  A thread-safe mutable-value container inspired by Clojure's agents and GPars' `Agent`.

  An `Agent` wraps a value that can be read by any thread but modified only through serialised update functions. Updates are queued and applied one at a time on a dedicated executor, guaranteeing that the value is never corrupted by concurrent writes.

  Reading the current value via get() is non-blocking and returns a snapshot. Sending an update via send(Function) is also non-blocking — the function is queued and applied asynchronously. Use sendAndGet(Function) to obtain an Awaitable that completes with the new value after the update is applied.

      // Groovy:
       def counter = Agent.create(0)
       counter.send { it + 1
       counter.send { it + 1 }
       assert await(counter.getAsync()) == 2

       // Java:
       Agent counter = Agent.create(0);
       counter.send(n -> n + 1);
       Awaitable result = counter.sendAndGet(n -> n + 1);
       }

  Type Parameters:
    `T` - the value type
  See Also:
    Pool
    AsyncScope
  Since:
    6.0.0

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `static int` | `DEFAULT_CHANGES_BUFFER` | Default per-subscriber buffer size for changes().

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public Flow.Publisher<T>` | `changes()` Returns a Flow.Publisher that emits the agent's value after every successful update.
    `<T>` | `public static Agent<T>` | `create(T initialValue)` Creates an agent with the given initial value, using a single-thread executor for serialised updates.
    `<T>` | `public static Agent<T>` | `create(T initialValue, Pool pool)` Creates an agent backed by the given pool for update execution.
    `` | `public T` | `get()` Returns the current value.
    `` | `public Awaitable<T>` | `getAsync()` Returns the current value as an Awaitable.
    `` | `public void` | `send(Function<T, T> updateFn)` Queues an update function to be applied to the current value.
    `` | `public Awaitable<T>` | `sendAndGet(Function<T, T> updateFn)` Queues an update function and returns an Awaitable that completes with the new value after the update is applied.
    `` | `public void` | `shutdown()` Shuts down the agent's update executor.
    `` | `public String` | `toString()` Returns the current value in a diagnostic form.

  - ### Inherited Methods Summary

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

- - ### Field Detail

    - #### public static final int DEFAULT_CHANGES_BUFFER

      Default per-subscriber buffer size for changes().

  - ### Method Detail

    - #### public Flow.Publisher<T> changes()

      Returns a Flow.Publisher that emits the agent's value after every successful update. The publisher is hot and per-subscriber:

      - Subscribers see only changes that occur after they subscribe; the current value at subscription time is not replayed.
      - Each subscriber gets an independent buffer (default {@value #DEFAULT_CHANGES_BUFFER} items).
      - Slow subscribers drop the most recent value rather than blocking the agent's update thread. Values already buffered are delivered in order; only newly-offered values that cannot fit are discarded.
      - Closes (signals `onComplete`) when shutdown() is called. If `changes()` is first called after `shutdown()`, the returned publisher is already closed and subscribers receive `onComplete` immediately.

      Typical use:

          for await (newValue in agent.changes()) {
               log.info "Agent value is now {", newValue
           }
           }

      Returns:
        a hot publisher of state transitions
      Since:
        6.0.0

    - #### <T> public static Agent<T> create(T initialValue)

      Creates an agent with the given initial value, using a single-thread executor for serialised updates.

      Parameters:
        `initialValue` - the starting value
      Type Parameters:
        `T` - the value type
      Returns:
        a new agent

    - #### <T> public static Agent<T> create(T initialValue, Pool pool)

      Creates an agent backed by the given pool for update execution. Updates are still serialised (only one at a time), but they run on the pool's threads.

      Parameters:
        `initialValue` - the starting value
        `pool` - the pool to use for updates
      Type Parameters:
        `T` - the value type
      Returns:
        a new agent

    - #### public T get()

      Returns the current value. This is a non-blocking snapshot read.

      Returns:
        the current value

    - #### public Awaitable<T> getAsync()

      Returns the current value as an Awaitable. The awaitable completes after all previously queued updates have been applied, ensuring a consistent read.

      Returns:
        an awaitable holding the value after pending updates

    - #### public void send(Function<T, T> updateFn)

      Queues an update function to be applied to the current value. The function receives the current value and returns the new value.

      Updates are applied asynchronously and serialised: only one update runs at a time.

      Parameters:
        `updateFn` - a function from current value to new value

    - #### public Awaitable<T> sendAndGet(Function<T, T> updateFn)

      Queues an update function and returns an Awaitable that completes with the new value after the update is applied.

      Parameters:
        `updateFn` - a function from current value to new value
      Returns:
        an awaitable holding the new value

    - #### public void shutdown()

      Shuts down the agent's update executor. No further updates will be accepted. Pending updates are executed before shutdown completes. The changes publisher (if any subscribers attached) is closed after pending updates drain, signalling `onComplete` to all live subscribers. Calling `shutdown()` more than once is a no-op.

    - #### public String toString()

      Returns the current value in a diagnostic form.

      Returns:
        the current value description