Package: groovy.concurrent

## [Java] Class DataflowVariable<T>

- groovy.concurrent.DataflowVariable

- All Implemented Interfaces and Traits:
    Awaitable

      public class DataflowVariable<T>
      extends Object
      implements Awaitable

  A single-assignment variable for dataflow-style programming.

  A `DataflowVariable` starts unbound. It can be written to exactly once via bind(Object) (or the `<<` operator in Groovy). Any thread that reads the variable before it is bound will block until a value becomes available. Once bound, all subsequent reads return the same value immediately.

  `DataflowVariable` implements Awaitable, so it works naturally with `await`:

      def x = new DataflowVariable()
       def y = new DataflowVariable()

       def z = Awaitable.go { await(x) + await(y)

       async { x << 10 }
       async { y << 5 }

       println "Result: ${await(z)}"  // 15
       }

  Inspired by GPars' `DataflowVariable`, modernised to integrate with Groovy's `async`/`await` and Awaitable API.

  Type Parameters:
    `T` - the value type
  See Also:
    Awaitable
    Dataflows
  Since:
    6.0.0

- - ### Constructor Summary

    Constructors
    Constructor and description
    `DataflowVariable()` Creates an unbound dataflow variable.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public void` | `bind(T value)` Binds this variable to the given value.
    `` | `public void` | `bindError(Throwable error)` Binds this variable to an error.
    `` | `public boolean` | `cancel()` Attempts to cancel the computation. If the computation has not yet started or is still running, it will be cancelled with a CancellationException. Returns: `true` if the computation was successfully cancelled
    `` | `public Awaitable<T>` | `exceptionally(Function<Throwable, ? extends T> fn)` Returns a new `Awaitable` that, if this one completes exceptionally, applies the given function to the exception to produce a recovery value. The throwable passed to the function is deeply unwrapped to strip JDK wrapper layers. Parameters: `fn` - the recovery function Returns: a new awaitable that recovers from failures
    `` | `public T` | `get()` Blocks until the computation completes and returns the result. throws: InterruptedException if the calling thread is interrupted while waiting throws: ExecutionException if the computation completed exceptionally Returns: the computed result
    `` | `public T` | `get(long timeout, TimeUnit unit)` Blocks until the computation completes or the timeout expires. throws: InterruptedException if the calling thread is interrupted while waiting throws: ExecutionException if the computation completed exceptionally throws: TimeoutException if the wait timed out Parameters: `timeout` - the maximum time to wait `unit` - the time unit of the timeout argument Returns: the computed result
    `` | `public boolean` | `isBound()` Returns `true` if this variable has been bound to a value or an error.
    `` | `public boolean` | `isCancelled()` Returns `true` if the computation was cancelled before completing normally. Returns: `true` if cancelled
    `` | `public boolean` | `isCompletedExceptionally()` Returns `true` if this computation completed exceptionally (including cancellation). Returns: `true` if completed with an error or cancellation
    `` | `public boolean` | `isDone()` Returns `true` if the computation has completed (normally, exceptionally, or via cancellation). Returns: `true` if complete
    `` | `public DataflowVariable<T>` | `leftShift(T value)` Groovy operator overload: `variable << value` binds the value.
    `<U>` | `public Awaitable<U>` | `then(Function<? super T, ? extends U> fn)` Returns a new `Awaitable` whose result is obtained by applying the given function to this awaitable's result when it completes. Parameters: `fn` - the mapping function Type Parameters: `U` - the type of the mapped result Returns: a new awaitable holding the mapped result
    `<U>` | `public Awaitable<U>` | `thenCompose(Function<? super T, ? extends Awaitable<U>> fn)` Returns a new `Awaitable` produced by applying the given async function to this awaitable's result, flattening the nested `Awaitable`. This is the monadic `flatMap` operation for awaitables. Parameters: `fn` - the async mapping function that returns an `Awaitable` Type Parameters: `U` - the type of the inner awaitable's result Returns: a new awaitable holding the inner result
    `` | `public CompletableFuture<T>` | `toCompletableFuture()` Converts this `Awaitable` to a JDK CompletableFuture for interoperability with APIs that require it. Returns: a `CompletableFuture` representing this computation
    `` | `public String` | `toString()` Returns the current bound state 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`

- - ### Constructor Detail

    - #### public DataflowVariable()

      Creates an unbound dataflow variable.

  - ### Method Detail

    - #### public void bind(T value)

      Binds this variable to the given value. Can only be called once; subsequent calls throw IllegalStateException.

      throws:
        IllegalStateException if already bound
      Parameters:
        `value` - the value to bind (may be `null`)

    - #### public void bindError(Throwable error)

      Binds this variable to an error. Any thread awaiting the value will receive the exception.

      throws:
        IllegalStateException if already bound
      Parameters:
        `error` - the error to bind

    - #### public boolean cancel()

      Attempts to cancel the computation. If the computation has not yet started or is still running, it will be cancelled with a CancellationException.

      Returns:
        `true` if the computation was successfully cancelled

    - #### public Awaitable<T> exceptionally(Function<Throwable, ? extends T> fn)

      Returns a new `Awaitable` that, if this one completes exceptionally, applies the given function to the exception to produce a recovery value. The throwable passed to the function is deeply unwrapped to strip JDK wrapper layers.

      Parameters:
        `fn` - the recovery function
      Returns:
        a new awaitable that recovers from failures

    - #### public T get()

      Blocks until the computation completes and returns the result.

      throws:
        InterruptedException if the calling thread is interrupted while waiting
      throws:
        ExecutionException if the computation completed exceptionally
      Returns:
        the computed result

    - #### public T get(long timeout, TimeUnit unit)

      Blocks until the computation completes or the timeout expires.

      throws:
        InterruptedException if the calling thread is interrupted while waiting
      throws:
        ExecutionException if the computation completed exceptionally
      throws:
        TimeoutException if the wait timed out
      Parameters:
        `timeout` - the maximum time to wait
        `unit` - the time unit of the timeout argument
      Returns:
        the computed result

    - #### public boolean isBound()

      Returns `true` if this variable has been bound to a value or an error.

    - #### public boolean isCancelled()

      Returns `true` if the computation was cancelled before completing normally.

      Returns:
        `true` if cancelled

    - #### public boolean isCompletedExceptionally()

      Returns `true` if this computation completed exceptionally (including cancellation).

      Returns:
        `true` if completed with an error or cancellation

    - #### public boolean isDone()

      Returns `true` if the computation has completed (normally, exceptionally, or via cancellation).

      Returns:
        `true` if complete

    - #### public DataflowVariable<T> leftShift(T value)

      Groovy operator overload: `variable << value` binds the value.

      Parameters:
        `value` - the value to bind
      Returns:
        this variable (for chaining)

    - #### <U> public Awaitable<U> then(Function<? super T, ? extends U> fn)

      Returns a new `Awaitable` whose result is obtained by applying the given function to this awaitable's result when it completes.

      Parameters:
        `fn` - the mapping function
      Type Parameters:
        `U` - the type of the mapped result
      Returns:
        a new awaitable holding the mapped result

    - #### <U> public Awaitable<U> thenCompose(Function<? super T, ? extends Awaitable<U>> fn)

      Returns a new `Awaitable` produced by applying the given async function to this awaitable's result, flattening the nested `Awaitable`. This is the monadic `flatMap` operation for awaitables.

      Parameters:
        `fn` - the async mapping function that returns an `Awaitable`
      Type Parameters:
        `U` - the type of the inner awaitable's result
      Returns:
        a new awaitable holding the inner result

    - #### public CompletableFuture<T> toCompletableFuture()

      Converts this `Awaitable` to a JDK CompletableFuture for interoperability with APIs that require it.

      Returns:
        a `CompletableFuture` representing this computation

    - #### public String toString()

      Returns the current bound state in a diagnostic form.

      Returns:
        the current state description