Module org.praxislive.code
Package org.praxislive.code.userapi

Class Async<T>

java.lang.Object
org.praxislive.code.userapi.Async<T>
Type Parameters:
T - result type
public final class Async<T> extends Object
A lightweight holder for a future value, the result of an asynchronous operation such as an actor call. An Async can also reflect the failure of such an operation.

An Async can be explicitly completed, with a value or error. Completion can only happen once.

Async is not thread safe and is not designed for concurrent operation. Use from a single thread, or protect appropriately.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    Async.Queue<T>
    A queue for handling Async instances.
    static interface 
    Async.Task<T,R>
    A task intended to be run asynchronously and outside of the main component context.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Async()
    Construct an empty Async.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> void
    bind(Async<T> source, Async<? super T> target)
    Bind a target Async to complete when a source Async completes.
    boolean
    complete(T value)
    Complete the Async with the provided value.
    static <T> Async<T>
    completed(T value)
    Create an Async that is already completed with the given value.
    boolean
    done()
    Whether this Async has been completed, with or without error.
    PError
    error()
    Get the failure error or null.
    static <T> Async<T>
    extractArg(Async<Call> asyncCall, Class<T> type)
    Create an Async that will complete when the provided async call completes, by extracting the first call argument and attempting to map to the given type.
    static <T> Async<T>
    extractArg(Async<Call> asyncCall, Class<T> type, int argIdx)
    Create an Async that will complete when the provided async call completes, by extracting the indexed call argument and attempting to map to the given type.
    static Async<PArray>
    extractArgs(Async<Call> asyncCall)
    Create an Async that will complete when the provided async call completes, by extracting the call arguments.
    boolean
    fail(PError error)
    Complete the Async unsuccessfully with the provided error.
    boolean
    failed()
    Whether this Async completed with a failure.
    static <T> Async<T>
    failed(PError error)
    Create an Async that is already failed with the given error.
    T
    result()
    Get the result of this Async if completed without error, otherwise null.
    static <T> CompletableFuture<T>
    toCompletableFuture(Async<T> async)
    A utility method for linking an Async with a CompletableFuture for passing to external APIs.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Async

      public Async()
      Construct an empty Async.

  • Method Details

    • result

      public T result()
      Get the result of this Async if completed without error, otherwise null.
      Returns:
      result or null

    • error

      public PError error()
      Get the failure error or null.
      Returns:
      error or null

    • done

      public boolean done()
      Whether this Async has been completed, with or without error.
      Returns:
      true if done

    • failed

      public boolean failed()
      Whether this Async completed with a failure.
      Returns:
      true if failed

    • complete

      public boolean complete(T value)
      Complete the Async with the provided value. If this Async is already completed, with or without failure, its state remains the same and this method returns false.
      Parameters:
      value - value to complete the Async
      Returns:
      true if completed

    • fail

      public boolean fail(PError error)
      Complete the Async unsuccessfully with the provided error. If this Async is already completed, with or without failure, its state remains the same and this method returns false.
      Parameters:
      error - error to complete the Async
      Returns:
      true if completed

    • bind

      public static <T> void bind(Async<T> source, Async<? super T> target)
      Bind a target Async to complete when a source Async completes. When the source Async completes, the target will be completed with the same result or error.
      Type Parameters:
      T - result type
      Parameters:
      source - source async
      target - target async

    • completed

      public static <T> Async<T> completed(T value)
      Create an Async that is already completed with the given value.
      Type Parameters:
      T - value type
      Parameters:
      value - value to complete the Async
      Returns:
      new completed Async

    • failed

      public static <T> Async<T> failed(PError error)
      Create an Async that is already failed with the given error.
      Type Parameters:
      T - value type
      Parameters:
      error - error to fail the Async
      Returns:
      new failed Async

    • extractArg

      public static <T> Async<T> extractArg(Async<Call> asyncCall, Class<T> type)
      Create an Async that will complete when the provided async call completes, by extracting the first call argument and attempting to map to the given type. The returned Async will complete with an error if the call completes with an error, the argument isn't available, or the argument cannot be mapped to the given type.
      Type Parameters:
      T - type of created async
      Parameters:
      asyncCall - async call
      type - class type of created async
      Returns:
      created async

    • extractArg

      public static <T> Async<T> extractArg(Async<Call> asyncCall, Class<T> type, int argIdx)
      Create an Async that will complete when the provided async call completes, by extracting the indexed call argument and attempting to map to the given type. The returned Async will complete with an error if the call completes with an error, the argument isn't available, or the argument cannot be mapped to the given type.
      Type Parameters:
      T - type of created async
      Parameters:
      asyncCall - async call
      type - class type of created async
      argIdx - index of argument to extract
      Returns:
      created async

    • extractArgs

      public static Async<PArray> extractArgs(Async<Call> asyncCall)
      Create an Async that will complete when the provided async call completes, by extracting the call arguments. The arguments are wrapped into a PArray for convenience. The returned Async will complete with an error if the call completes with an error.
      Parameters:
      asyncCall - async call
      Returns:
      created async

    • toCompletableFuture

      public static <T> CompletableFuture<T> toCompletableFuture(Async<T> async)
      A utility method for linking an Async with a CompletableFuture for passing to external APIs.

      IMPORTANT : do not use completable futures returned from this method inside component code. To react to Async completion from within component code, use an Async.Queue.

      The completable future will automatically complete with the result or failure of the Async. The link is one way - the Async will not respond to any changes to the future.

      Type Parameters:
      T - async and future type
      Parameters:
      async - async to link to created future
      Returns:
      created future