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