DataflowVariable (Groovy 6.0.0-alpha-1)

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)
 - public Awaitable 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
 - public Awaitable thenCompose(Function<? super T, ? extends Awaitable> 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

Summary:
Constructor
Method

| Detail:
Constructor
Method

[Java] Class DataflowVariable<T>

Constructor Summary

Methods Summary

Inherited Methods Summary

Constructor Detail

public DataflowVariable()

Method Detail

public void bind(T value)

public void bindError(Throwable error)

public boolean cancel()

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

public T get()

public T get(long timeout, TimeUnit unit)

public boolean isBound()

public boolean isCancelled()

public boolean isCompletedExceptionally()

public boolean isDone()

public DataflowVariable<T> leftShift(T value)

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

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

public CompletableFuture<T> toCompletableFuture()

public String toString()