Package com.tapkey.mobile.concurrent

Class Async

  • public class Async
extends Object

    • Method Detail

      • PromiseFromResult

        public static <T> Promise<T> PromiseFromResult​(T result)
        Creates a completed promise that resolves to the given value.
        Parameters:
        result - the value the promise resolves to.
        Returns:
        a promise that is completed and resolves to the given value.

      • PromiseFromException

        public static <T> Promise<T> PromiseFromException​(Exception exception)
        Creates a failed promise, that resolves to the given exception.
        Parameters:
        exception - the exception the promise resolves to.
        Returns:
        a promise that is in a failed state and resolves to the given exception.

      • PromiseFromAsyncResult

        public static <T> Promise<T> PromiseFromAsyncResult​(AsyncResult<? extends T> asyncResult)
        Creates a completed promise that resolves to the given AsyncResult.
        Parameters:
        asyncResult - the result the promise resolves to.
        Returns:
        a promise that is completed and resolves to the given result.

      • AsyncResultFromResult

        public static <T> AsyncResult<T> AsyncResultFromResult​(T result)
        Creates an AsyncResult that resolves to the given result.
        Parameters:
        result - the result the returned instance resolves to.
        Returns:
        an AsyncResult that resolves to the given result.

      • whenAny

        public static <T> Promise<KeyValuePair<Integer,​AsyncResult<? extends T>>> whenAny​(Promise<? extends T>... promises)
        Asynchronously waits for the first of the specified promises to complete, regardless, whether it completes successfully or with an Exception. The returned instance will always complete successfully.
        Parameters:
        promises - the Promise instances to wait for.
        Returns:
        a promise, that completes when the first of the specified promises completes and resolves to a KeyValuePair, where the key represents the index of the resolved promise as specified in the specified list of promises and the value represents the AsyncResult the promise resolved to.

      • whenAny

        public static <T> Promise<KeyValuePair<Integer,​AsyncResult<? extends T>>> whenAny​(List<? extends Promise<? extends T>> promises)
        Asynchronously waits for the first of the specified promises to complete, regardless, whether it completes successfully or with an Exception. The returned instance will always complete successfully.
        Parameters:
        promises - the Promise instances to wait for.
        Returns:
        a promise, that completes when the first of the specified promises completes and resolves to a KeyValuePair, where the key represents the index of the resolved promise as specified in the specified list of promises and the value represents the AsyncResult the promise resolved to.

      • whenBoth

        public static <T1,​T2> Promise<Tuple<T1,​T2>> whenBoth​(Promise<? extends T1> p1,
                                                                 Promise<? extends T2> p2)
        Asynchronously waits for the specified promises to complete, regardless, whether they complete successfully or with an Exception. The returned instance will complete successfully if both specified Promise instances complete successfully. In this case, the returned Promise resolves to a Tuple containing the values the specified promises resolved to. If at least one of the specified promises fails, the returned Promise will resolve to the Exception of the first failed Promise according to the order they have been specified.
        Parameters:
        p1 - the first Promise instance to wait for.
        p2 - the first Promise instance to wait for.
        Returns:
        a Promise, that completes when all specified promises complete.

      • whenAll

        public static <T> Promise<List<T>> whenAll​(Promise<? extends T> p1,
                                           Promise<? extends T> p2)
        Asynchronously waits for all specified promises to complete, regardless, whether they complete successfully or with an Exception. The returned instance will complete successfully if all specified Promise instances complete successfully. In this case, the returned Promise resolves to a List of values corresponding to the values the specified promises resolved to. The order of the returned values corresponds to the order of the specified promises. If at least one of the specified promises fails, the returned Promise will resolve to the Exception of the first failed Promise according to the order they have been specified.
        Parameters:
        p1 - the first Promise instance to wait for.
        p2 - the first Promise instance to wait for.
        Returns:
        a Promise, that completes when all specified promises complete.

      • whenAll

        public static <T> Promise<List<T>> whenAll​(Promise<? extends T> p1,
                                           Promise<? extends T> p2,
                                           Promise<? extends T> p3)
        Asynchronously waits for all specified promises to complete, regardless, whether they complete successfully or with an Exception. The returned instance will complete successfully if all specified Promise instances complete successfully. In this case, the returned Promise resolves to a List of values corresponding to the values the specified promises resolved to. The order of the returned values corresponds to the order of the specified promises. If at least one of the specified promises fails, the returned Promise will resolve to the Exception of the first failed Promise according to the order they have been specified.
        Parameters:
        p1 - the first Promise instance to wait for.
        p2 - the first Promise instance to wait for.
        p3 - the first Promise instance to wait for.
        Returns:
        a Promise, that completes when all specified promises complete.

      • whenAll

        public static <T> Promise<List<T>> whenAll​(List<? extends Promise<? extends T>> promises)
        Asynchronously waits for all specified promises to complete, regardless, whether they complete successfully or with an Exception. The returned instance will complete successfully if all specified Promise instances complete successfully. In this case, the returned Promise resolves to a List of values corresponding to the values the specified promises resolved to. The order of the returned values corresponds to the order of the specified promises. If at least one of the specified promises fails, the returned Promise will resolve to the Exception of the first failed Promise according to the order they have been specified.
        Parameters:
        promises - the Promise instances to wait for.
        Returns:
        a Promise, that completes when all specified promises complete.

      • whenAllWithAsyncResults

        public static <T> Promise<List<AsyncResult<? extends T>>> whenAllWithAsyncResults​(Promise<? extends T> p1,
                                                                                  Promise<? extends T> p2)
        Asynchronously waits for all specified promises to complete, regardless, whether they complete successfully or with an Exception. The returned instance will always complete successfully. The AsyncResult instances that the specified Promise instances resolve to will be returned in the result of the returned Promise.
        Parameters:
        p1 - the first Promise instance to wait for.
        p2 - the second Promise instance to wait for.
        Returns:
        a promise, that completes when all specified promises complete and resolves to a List of AsyncResult instances that reflect the results of the specified Promise instances. The order of the results corresponds to the order of the specified instances.

      • whenAllWithAsyncResults

        public static <T> Promise<List<AsyncResult<? extends T>>> whenAllWithAsyncResults​(Promise<? extends T> p1,
                                                                                  Promise<? extends T> p2,
                                                                                  Promise<? extends T> p3)
        Asynchronously waits for all specified promises to complete, regardless, whether they complete successfully or with an Exception. The returned instance will always complete successfully. The AsyncResult instances that the specified Promise instances resolve to will be returned in the result of the returned Promise.
        Parameters:
        p1 - the first Promise instance to wait for.
        p2 - the second Promise instance to wait for.
        p3 - the third Promise instance to wait for.
        Returns:
        a promise, that completes when all specified promises complete and resolves to a List of AsyncResult instances that reflect the results of the specified Promise instances. The order of the results corresponds to the order of the specified instances.

      • whenAllWithAsyncResults

        public static <T> Promise<List<AsyncResult<? extends T>>> whenAllWithAsyncResults​(List<? extends Promise<? extends T>> promises)
        Asynchronously waits for all specified promises to complete, regardless, whether they complete successfully or with an Exception. The returned instance will always complete successfully. The AsyncResult instances that the specified Promise instances resolve to will be returned in the result of the returned Promise.
        Parameters:
        promises - the Promise instances to wait for.
        Returns:
        a promise, that completes when all specified promises complete and resolves to a List of AsyncResult instances that reflect the results of the specified Promise instances. The order of the results corresponds to the order of the specified instances.

      • executeAsync

        public static <T> Promise<T> executeAsync​(Func<T,​? extends Exception> f)
        Runs the specified operation on a multi-threaded worker-thread-backed scheduler. If the specified operation completes successfully, the returned Promise resolves to the returned value. Otherwise it will resolve to the raised Exception.
        Parameters:
        f - async operation to run.
        Returns:
        Promise that continues on the caller's current AsyncScheduler with the operation's result.

      • executeOnScheduler

        public static <T> Promise<T> executeOnScheduler​(AsyncScheduler scheduler,
                                                Func<T,​? extends Exception> f)
        Executes the specified function on the specified scheduler and returns a promise which will deliver the result on the caller's current AsyncScheduler.
        Parameters:
        scheduler - scheduler to run the given operation on.
        f - operation to run.
        Returns:
        Promise that continues on the caller's current AsyncScheduler with the operation's result.

      • foreachResAsync

        public static <TIn,​TOut> Promise<List<TOut>> foreachResAsync​(Iterable<? extends TIn> items,
                                                                   Func1<TIn,​Promise<TOut>,​? extends RuntimeException> f)
        Iterates the given items and sequentially executes the given async functions for each item. The returned Promise completes after asynchronous processing of all items has completed successfully. In this case the returned Promise resolves to a List containing the values the promises returned by the specified function resolved to. If execution of the specified function fails, iteration will stop and the returned Promise will resolve to the corresponding Exception.
        Parameters:
        items - the items to iterate.
        f - the async function to execute for each item.
        Returns:
        a Promise that completes successfully if the specified function completed successfully for each item or that completes exceptionally otherwise.

      • foreachAsync

        public static <T> Promise<Void> foreachAsync​(Iterable<? extends T> items,
                                             Func1<T,​Promise<LoopResult>,​? extends RuntimeException> f)
        Iterates the given items and sequentially executes the given async functions for each item. Execution stops, iteration ends and the returned Promise completes if one of the following happens: * all items have been iterated, processed successfully and resolved to LoopResult.Continue or null. * the Promise returned by the async function resolved to LoopResult.Break. * the Promise returned by the async function completed exceptionally. In the last case the returned Promise resolves to the Exception returned by the async function. In all other cases the returned Promise resolves to null.
        Parameters:
        items - the items to iterate.
        f - the async function to execute for each item.
        Returns:
        a Promise that completes successfully if the specified function completed successfully for each item it was invoked for or that completes exceptionally otherwise.

      • forAsync

        public static Promise<Void> forAsync​(int n,
                                     Func1<Integer,​Promise<LoopResult>,​? extends RuntimeException> f)
        Counts from 0 to n (excluding) and sequentially executes the given async functions for each value. Execution stops, iteration ends and the returned Promise completes if one of the following happens: * all values have been iterated, processed successfully and resolved to null or LoopResult.Continue. * the Promise returned by the async function resolved to LoopResult.Break. * the Promise returned by the async function completed exceptionally. In the last case the returned Promise resolves to the Exception returned by the async function. In all other cases the returned Promise resolves to null.
        Parameters:
        n - the upper limit (excluding) to count to.
        f - the async function to execute for each item.
        Returns:
        a Promise that completes successfully if the specified function completed successfully for each item it was invoked for or that completes exceptionally otherwise.

      • loopAsync

        public static Promise<Void> loopAsync​(Func<Promise<LoopResult>,​RuntimeException> f)
        Executes the given async function until one of the following happens: * the Promise returned by the async function resolved to something other than LoopResult.Continue or null (i.e. LoopResult.Break). * the Promise returned by the async function completed exceptionally. In the latter case the returned Promise resolves to the Exception returned by the async function. In the first case the returned Promise resolves to null.
        Parameters:
        f - the async function to execute for each item.
        Returns:
        a Promise that completes successfully if the specified function completed successfully for each item it was invoked for or that completes exceptionally otherwise.

      • delayAsync

        public static Promise<Void> delayAsync​(long delayMs)
        Returns a Promise that completes after the given time span.
        Parameters:
        delayMs - the number of milliseconds to delay.
        Returns:
        a Promise that completes after the given time span.

      • delayAsync

        public static Promise<Void> delayAsync​(long delayMs,
                                       CancellationToken cancellationToken)
        Returns a Promise that completes after either the given time span elapsed or the given CancellationToken requested cancellation. In the first case, the returned Promise completes successfully while in the second case it completes exceptionally with an CancellationException.
        Parameters:
        delayMs - the number of milliseconds to delay.
        cancellationToken - the CancellationToken that can be used for cancellation.
        Returns:
        a Promise that completes either after the given time span elapsed or after cancellation, whatever happens earlier.

      • first

        public static Promise<Void> first()
        Returns a completed Promise that resolves to null.
        Returns:
        a completed Promise that resolves to null.

      • first

        public static <Void> Promise<Void> first​(Action<? extends Exception> f)
        Synchronously executes the given Action and then returns a completed Promise that resolves to null. If execution of the action fails, the returned promise completes exceptionally and resolves to the raised Exception.
        Parameters:
        f - the action to execute.
        Returns:
        a completed Promise that resolves according to the outcome of the specified action.

      • first

        public static <T> Promise<T> first​(Func<T,​? extends Exception> f)
        Synchronously executes the given Func and then returns a completed Promise that resolves to the value returned by the function. If execution fails, the returned promise completes exceptionally and resolves to the raised Exception.
        Parameters:
        f - the function to execute.
        Returns:
        a completed Promise that resolves according to the outcome of the specified function.

      • firstWithAsyncStackTraceEnabled

        public static Promise<Void> firstWithAsyncStackTraceEnabled​(boolean asyncStackTraceEnabled)
        for internal use

      • withSettings

        public static Promise<Void> withSettings​(Promise<Void> promise,
                                         net.tpky.mc.concurrent.AsyncTaskSettings settings)
        for internal use

      • firstAsync

        public static <T> Promise<T> firstAsync​(Func<Promise<T>,​RuntimeException> f)
        Executes the given Func and returns the Promise returned by the function. The purpose of this function is to use it for structuring async code. It doesn't provide any actual functionality.
        Parameters:
        f - the async function to execute.
        Returns:
        the Promise returned by the function.

        Instead of writing code like in this example 

                        firstAsyncOperation().continueAsyncOnUi(result ->
                                secondAsyncOperation()
                ).continueAsyncOnUi(result ->
                                thirdAsyncOperation()
                ).conclude();

        we could also write in a more readable way 

                        Async.firstAsync(() ->
                                firstAsyncOperation()
                ).continueAsyncOnUi(result ->
                                secondAsyncOperation()
                ).continueAsyncOnUi(result ->
                                thirdAsyncOperation()
                ).conclude();

      • switchToScheduler

        public static <T> Promise<T> switchToScheduler​(AsyncScheduler scheduler,
                                               Func<Promise<T>,​RuntimeException> f)
        Starts an async function on the specified scheduler and continues the returned promise on the caller's current scheduler.
        Parameters:
        scheduler - Scheduler to start the specified async operation on.
        f - Async operation to be started on the specified scheduler.
        Returns:
        Promise that continues on the caller's current scheduler.

      • switchToScheduler

        public static <T> Promise<T> switchToScheduler​(AsyncScheduler runOnScheduler,
                                               AsyncScheduler continueOnScheduler,
                                               Func<Promise<T>,​RuntimeException> f)
        Starts an async function on the specified scheduler and continues the returned promise on the other specified scheduler.
        Parameters:
        runOnScheduler - Scheduler to start the specified async operation on.
        continueOnScheduler - Scheduler to continue the returned promise on.
        f - Async operation to be started on the specified scheduler.
        Returns:
        Promise that continues on the specified scheduler.