Package groovy.concurrent

# Class AwaitResult<T>

java.lang.Object
groovy.concurrent.AwaitResult<T>

Type Parameters:
  `T` - the value type

public final class AwaitResult<T> extends Object
Represents the outcome of an asynchronous computation that may have succeeded or failed. Returned by `Awaitable.allSettled()` to report each individual task's result without short-circuiting on failure.

An `AwaitResult` is either a success carrying a value, or a failure carrying a `Throwable`.

This type follows the value object pattern: two instances are equal if and only if they have the same success/failure state and carry equal values or errors. Immutability is enforced — all fields are final and no mutating methods are exposed.

Functional composition is supported via `map(Function)`, enabling transformation chains without unwrapping:

     AwaitResult<Integer> length = AwaitResult.success("hello").map(String::length)

Inspired by Kotlin's `Result`, Rust's `Result<T, E>`, and C#'s pattern of structured success/error responses.

Since:
  6.0.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object o)`
  Compares this result to another object for equality.
  `static <T> AwaitResult<T>`
  `failure(Throwable error)`
  Creates a failure result with the given exception.
  `Throwable`
  `getError()`
  Returns the exception if failed.
  `T`
  `getOrElse(Function<Throwable,? extends T> fallback)`
  Returns the value if successful, or applies the given function to the error to produce a fallback value.
  `T`
  `getValue()`
  Returns the value if successful.
  `int`
  `hashCode()`
  Returns a hash code consistent with `equals(Object)`.
  `boolean`
  `isFailure()`
  Returns `true` if this result represents a failed completion.
  `boolean`
  `isSuccess()`
  Returns `true` if this result represents a successful completion.
  `<U> AwaitResult<U>`
  `map(Function<? super T,? extends U> fn)`
  Transforms a successful result's value using the given function.
  `static <T> AwaitResult<T>`
  `success(T value)`
  Creates a successful result with the given value.
  `String`
  `toString()`
  Returns a human-readable representation of this result: `AwaitResult.Success[value]` or `AwaitResult.Failure[error]`.

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Method Details

  - ### success

    public static <T> AwaitResult<T> success(T value)
    Creates a successful result with the given value.
    Type Parameters:
      `T` - the value type
    Parameters:
      `value` - the computation result (may be `null`)
    Returns:
      a success result wrapping the value

  - ### failure

    public static <T> AwaitResult<T> failure(Throwable error)
    Creates a failure result with the given exception.
    Type Parameters:
      `T` - the value type (never actually used, since the result is a failure)
    Parameters:
      `error` - the exception that caused the failure; must not be `null`
    Returns:
      a failure result wrapping the exception
    Throws:
      `NullPointerException` - if `error` is `null`

  - ### isSuccess

    public boolean isSuccess()
    Returns `true` if this result represents a successful completion.

  - ### isFailure

    public boolean isFailure()
    Returns `true` if this result represents a failed completion.

  - ### getValue

    public T getValue()
    Returns the value if successful.
    Returns:
      the computation result
    Throws:
      `IllegalStateException` - if this result represents a failure

  - ### getError

    public Throwable getError()
    Returns the exception if failed.
    Returns:
      the exception that caused the failure
    Throws:
      `IllegalStateException` - if this result represents a success

  - ### getOrElse

    public T getOrElse(Function<Throwable,? extends T> fallback)
    Returns the value if successful, or applies the given function to the error to produce a fallback value.
    Parameters:
      `fallback` - the function to apply to the error if this result is a failure; must not be `null`
    Returns:
      the value, or the fallback function's result

  - ### map

    public <U> AwaitResult<U> map(Function<? super T,? extends U> fn)
    Transforms a successful result's value using the given function. If this result is a failure, the error is propagated unchanged.

    This is the functor `map` operation, enabling value transformation without explicit unwrapping:

         AwaitResult<String>  name   = AwaitResult.success("Groovy")
         AwaitResult<Integer> length = name.map(String::length)
         assert length.value == 6

    Type Parameters:
      `U` - the type of the mapped value
    Parameters:
      `fn` - the mapping function; must not be `null`
    Returns:
      a new success result with the mapped value, or the original failure unchanged
    Throws:
      `NullPointerException` - if `fn` is `null`

  - ### equals

    public boolean equals(Object o)
    Compares this result to another object for equality.

    Two `AwaitResult` instances are equal if and only if they have the same success/failure state and carry equal values or errors.

    Overrides:
      `equals` in class `Object`
    Parameters:
      `o` - the object to compare with
    Returns:
      `true` if the given object is an equal `AwaitResult`

  - ### hashCode

    public int hashCode()
    Returns a hash code consistent with `equals(Object)`.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      the hash code

  - ### toString

    public String toString()
    Returns a human-readable representation of this result: `AwaitResult.Success[value]` or `AwaitResult.Failure[error]`.
    Overrides:
      `toString` in class `Object`