Package io.aether.utils.futures

Interface ARFuture<T>

Type Parameters:

T - The type of the result value.

All Superinterfaces:

AFutureBase<ARFuture<T>>, ToString

All Known Implementing Classes:

ARFutureWithFlag

public interface ARFuture<T>
extends AFutureBase<ARFuture<T>>

An asynchronous operation that completes with a result value of type T. This interface extends the base asynchronous functionality and provides static factory methods (implemented via proxy to ARFutureImpl).

Field Summary

Fields

Modifier and Type	Field	Description
static ARFuture<java.lang.Boolean>	FALSE
static ARFuture<java.lang.Boolean>	TRUE

Method Summary

Modifier and Type	Method	Description
static <T> ARFuture<java.util.List<T>>	all(@NotNull java.util.List<ARFuture<T>> list)	Returns an ARFuture that completes with a List of all results once all futures are completed.
static <T1,T2> ARFuture<Tuple2<T1,T2>>	all(ARFuture<T1> f1, ARFuture<T2> f2)	Returns an ARFuture that completes with a Tuple2 of results.
static <T1,T2,T3> ARFuture<Tuple3<T1,T2,T3>>	all(ARFuture<T1> f1, ARFuture<T2> f2, ARFuture<T3> f3)	Returns an ARFuture that completes with a Tuple3 of results.
static <T1,T2,T3> ARFuture<Tuple3<T1,T2,T3>>	all(ARFuture<T1> f1, ARFuture<T2> f2, ARFuture<T3> f3, A3Consumer<T1,T2,T3> task)	Performs an action upon successful completion of three futures.
static <T1,T2> ARFuture<Tuple2<T1,T2>>	all(ARFuture<T1> f1, ARFuture<T2> f2, ABiConsumer<T1,T2> task)	Performs an action upon successful completion of two futures.
static <T> ARFuture<T[]>	all(java.lang.Class<T> elType, Flow<ARFuture<T>> ff)	Returns an ARFuture that completes with an array of all results once all futures are completed.
static <T> ARFuture<T[]>	all(java.lang.Class<T> elType, ARFuture<T>... ff)	Returns an ARFuture that completes with an array of all results once all futures are completed.
<T2> ARFuture<Tuple2<T,T2>>	and(ARFuture<T2> f)	Chains this future with another, combining their results into a Tuple2.
static <T> ARFuture<T>	any(java.util.Collection<ARFuture<T>> ff)	Returns an ARFuture that completes with the result of the fastest future in the collection.
static <T> ARFuture<T>	anyAndCancel(Flow<ARFuture<T>> ff)	Returns an ARFuture that completes with the result of the fastest future in the collection, and cancels all other futures.
ARFuture<T>	apply(AConsumer<T> c)	Executes a consumer upon successful completion, preserving the original result.
ARFuture<T>	apply(ARunnable c)	Executes a runnable upon successful completion, preserving the original result.
static <T> ARFuture<T>	canceled()	Creates a cancelled ARFuture instance.
void	done(T value)	Completes the future with the given value.
static <T> ARFuture<T>	doThrow(java.lang.Throwable e)
T	get()	Gets the result of the future, waiting if necessary, and throws an exception on error/cancel.
T	get(long timout)	Gets the result of the future with a timeout, waiting if necessary.
T	getNow()	Gets the result value if the future is already done, otherwise returns null.
T	getNowElse(T elseValue)	Gets the result value if the future is already done, otherwise returns the provided default value.
static <T> ARFuture<T>	make()
<E> @NotNull ARFuture<E>	map(@NotNull AFunction<T,E> f)	Transforms the successful result into a different type using the provided function.
static <T1,T2,T3,R> ARFuture<R>	map(ARFuture<T1> f1, ARFuture<T2> f2, ARFuture<T3> f3, A3Function<T1,T2,T3,R> task)	Maps the results of three futures to a new result type.
static <T1,T2,R> ARFuture<R>	map(ARFuture<T1> f1, ARFuture<T2> f2, A2Function<T1,T2,R> task)	Maps the results of two futures to a new result type.
<E> @NotNull ARFuture<E>	mapRFuture(@NotNull AFunction<T,ARFuture<E>> f)	Transforms the successful result into another ARFuture.
<E> ARFuture<E>	mapSafe(@NotNull AFunction<T,E> f)	Transforms the successful result into a different type in a safe context (e.g., dedicated executor).
@NotNull AFuture	mapToFuture(@NotNull AConsumer<T> f)	Maps the result to a void AFuture and converts the result to an AFuture.
<E> @NotNull ARFuture<E>	mapWL(@NotNull AFunction<T,E> f)	Transforms the successful result into a different type using a function wrapped for Log context.
static <T> ARFuture<T>	of(T value)	Creates a new ARFuture instance that is already successfully completed with the given value.
static <T> ARFuture<T>	ofThrow(java.lang.Throwable throwable)	Creates an ARFuture instance that is already completed with the given Throwable error.
static <T> ARFuture<T>	run(java.util.concurrent.Executor executor, ACallable<T> task)	Executes a callable task using the provided executor and returns an ARFuture.
static <T> ARFuture<T>	run2(java.util.concurrent.Executor executor, ACallable<ARFuture<T>> task)	Executes a task using the provided executor and returns an ARFuture.
ARFuture<T>	to(@NotNull AFuture f)
ARFuture<T>	to(@NotNull ARFuture<T> f)	Transfers the final status (done/error/cancel) to another future.
ARFuture<T>	to(@NotNull AConsumer<T> task, int timeout, ARunnable onTimeout)	Registers a success callback with a timeout action.
ARFuture<T>	to(AConsumer<T> onDone)	Registers a callback to be executed upon successful completion.
ARFuture<T>	to(AConsumer<T> onDone, AConsumer<java.lang.Throwable> onError)	Registers a callback for success and another for error.
AFuture	toFuture()	Converts this ARFuture into a void AFuture.
ARFutureWithFlag<T>	toWithFlag()	Casts this ARFuture to its flag-carrying subclass.
boolean	tryDone(T value)	Attempts to complete the future with the given value.

Methods inherited from interface io.aether.utils.futures.AFutureBase

addListener, addListener2, cancel, error, getError, getNowRaw, isCanceled, isDone, isError, isFinalStatus, isNotDone, onCancel, onCancel, onError, setError, timeout, timeoutError, timeoutMs, timeoutMs, to, to, tryCancel, tryError, updateStatus

Methods inherited from interface io.aether.utils.ToString

toString, toString2

Field Detail

TRUE

static final ARFuture<java.lang.Boolean> TRUE

FALSE

static final ARFuture<java.lang.Boolean> FALSE

Method Detail

toWithFlag

ARFutureWithFlag<T> toWithFlag()

Casts this ARFuture to its flag-carrying subclass.

Returns:

The ARFutureWithFlag instance.

done

void done(T value)

Completes the future with the given value.

Parameters:

value - The result value.

Throws:

java.lang.IllegalStateException - if the future is already completed.

tryDone

boolean tryDone(T value)

Attempts to complete the future with the given value.

Parameters:

value - The result value.

Returns:

true if the status was updated, false otherwise.

get

T get()

Gets the result of the future, waiting if necessary, and throws an exception on error/cancel.

Returns:

The result value (T).

get

T get(long timout)

Gets the result of the future with a timeout, waiting if necessary.

Parameters:

timout - The timeout in milliseconds.

Returns:

The result value (T).

getNow

T getNow()

Gets the result value if the future is already done, otherwise returns null.

Returns:

The result T or null.

getNowElse

T getNowElse(T elseValue)

Gets the result value if the future is already done, otherwise returns the provided default value.

Parameters:

elseValue - The default value to return if not done.

Returns:

The result T or elseValue.

to

ARFuture<T> to(AConsumer<T> onDone)

Registers a callback to be executed upon successful completion.

Parameters:

onDone - The consumer that accepts the result value.

Returns:

This future instance.

to

ARFuture<T> to(AConsumer<T> onDone,
               AConsumer<java.lang.Throwable> onError)

Registers a callback for success and another for error.

Parameters:

onDone - The consumer that accepts the result value.

onError - The consumer that accepts the throwable error.

Returns:

This future instance.

to

ARFuture<T> to(@NotNull
               @NotNull AConsumer<T> task,
               int timeout,
               ARunnable onTimeout)

Registers a success callback with a timeout action.

Parameters:

task - The consumer that accepts the result value.

timeout - The timeout in seconds.

onTimeout - The runnable to execute on timeout.

Returns:

This future instance.

to

ARFuture<T> to(@NotNull
               @NotNull ARFuture<T> f)

Transfers the final status (done/error/cancel) to another future.

Parameters:

f - The target future.

Returns:

This future instance.

to

ARFuture<T> to(@NotNull
               @NotNull AFuture f)

toFuture

AFuture toFuture()

Converts this ARFuture into a void AFuture.

Returns:

The resulting AFuture.

and

<T2> ARFuture<Tuple2<T,T2>> and(ARFuture<T2> f)

Chains this future with another, combining their results into a Tuple2.

Type Parameters:

T2 - The type of the other future's result.

Parameters:

f - The other future.

Returns:

A new ARFuture with a Tuple2 result.

map

@NotNull
<E> @NotNull ARFuture<E> map(@NotNull
                             @NotNull AFunction<T,E> f)

Transforms the successful result into a different type using the provided function.

Type Parameters:

E - The new result type.

Parameters:

f - The function to apply to the result.

Returns:

A new ARFuture with the transformed result.

mapWL

@NotNull
<E> @NotNull ARFuture<E> mapWL(@NotNull
                               @NotNull AFunction<T,E> f)

Transforms the successful result into a different type using a function wrapped for Log context.

Type Parameters:

E - The new result type.

Parameters:

f - The function to apply to the result.

Returns:

A new ARFuture with the transformed result.

mapRFuture

@NotNull
<E> @NotNull ARFuture<E> mapRFuture(@NotNull
                                    @NotNull AFunction<T,ARFuture<E>> f)

Transforms the successful result into another ARFuture.

Type Parameters:

E - The new result type.

Parameters:

f - The function returning the new ARFuture.

Returns:

A new ARFuture that completes with the result of the future returned by f.

mapToFuture

@NotNull
@NotNull AFuture mapToFuture(@NotNull
                             @NotNull AConsumer<T> f)

Maps the result to a void AFuture and converts the result to an AFuture.

Parameters:

f - The consumer to apply to the result.

Returns:

An AFuture representing the completion of the consumer's execution.

mapSafe

<E> ARFuture<E> mapSafe(@NotNull
                        @NotNull AFunction<T,E> f)

Transforms the successful result into a different type in a safe context (e.g., dedicated executor).

Type Parameters:

E - The new result type.

Parameters:

f - The function to apply to the result.

Returns:

A new ARFuture with the transformed result.

apply

ARFuture<T> apply(ARunnable c)

Executes a runnable upon successful completion, preserving the original result.

Parameters:

c - The runnable to execute.

Returns:

A new ARFuture with the same original result.

apply

ARFuture<T> apply(AConsumer<T> c)

Executes a consumer upon successful completion, preserving the original result.

Parameters:

c - The consumer to execute with the result.

Returns:

A new ARFuture with the same original result.

of

static <T> ARFuture<T> of(T value)

Creates a new ARFuture instance that is already successfully completed with the given value.

Type Parameters:

T - The type of the result.

Parameters:

value - The result value.

Returns:

An immediately completed ARFuture.

canceled

static <T> ARFuture<T> canceled()

Creates a cancelled ARFuture instance.

Type Parameters:

T - The type of the result.

Returns:

An immediately cancelled ARFuture.

ofThrow

static <T> ARFuture<T> ofThrow(java.lang.Throwable throwable)

Creates an ARFuture instance that is already completed with the given Throwable error.

Type Parameters:

T - The type of the result.

Parameters:

throwable - The exception to complete the future with.

Returns:

An ARFuture completed with an error.

run2

static <T> ARFuture<T> run2(java.util.concurrent.Executor executor,
                            ACallable<ARFuture<T>> task)

Executes a task using the provided executor and returns an ARFuture.

Type Parameters:

T - The type of the result.

Parameters:

executor - The executor to run the task on.

task - The function returning the result value.

Returns:

A new ARFuture that completes with the result of the task.

run

static <T> ARFuture<T> run(java.util.concurrent.Executor executor,
                           ACallable<T> task)

Executes a callable task using the provided executor and returns an ARFuture.

Type Parameters:

T - The type of the result.

Parameters:

executor - The executor to run the task on.

task - The callable task.

Returns:

A new ARFuture that completes with the result of the task.

anyAndCancel

static <T> ARFuture<T> anyAndCancel(Flow<ARFuture<T>> ff)

Returns an ARFuture that completes with the result of the fastest future in the collection, and cancels all other futures.

Type Parameters:

T - The type of the result.

Parameters:

ff - The flow of futures.

Returns:

The ARFuture with the fastest result.

any

static <T> ARFuture<T> any(java.util.Collection<ARFuture<T>> ff)

Returns an ARFuture that completes with the result of the fastest future in the collection.

Type Parameters:

T - The type of the result.

Parameters:

ff - The collection of futures.

Returns:

The ARFuture with the fastest result.

all

static <T> ARFuture<T[]> all(java.lang.Class<T> elType,
                             Flow<ARFuture<T>> ff)

Returns an ARFuture that completes with an array of all results once all futures are completed. Fails or cancels immediately if any individual future fails or cancels.

Type Parameters:

T - The type of the result.

Parameters:

elType - The class type of the array elements.

ff - The flow of futures.

Returns:

The ARFuture with the array of results.

all

@SafeVarargs
static <T> ARFuture<T[]> all(java.lang.Class<T> elType,
                             ARFuture<T>... ff)

Returns an ARFuture that completes with an array of all results once all futures are completed.

Type Parameters:

T - The type of the result.

Parameters:

elType - The class type of the array elements.

ff - The array of futures.

Returns:

The ARFuture with the array of results.

all

static <T1,T2> ARFuture<Tuple2<T1,T2>> all(ARFuture<T1> f1,
                                                       ARFuture<T2> f2)

Returns an ARFuture that completes with a Tuple2 of results.

Type Parameters:

T1 - The type of the first result.

T2 - The type of the second result.

Parameters:

f1 - The first future.

f2 - The second future.

Returns:

The ARFuture with the Tuple2 of results.

all

static <T1,T2,T3> ARFuture<Tuple3<T1,T2,T3>> all(ARFuture<T1> f1,
                                                                         ARFuture<T2> f2,
                                                                         ARFuture<T3> f3)

Returns an ARFuture that completes with a Tuple3 of results.

Type Parameters:

T1 - The type of the first result.

T2 - The type of the second result.

T3 - The type of the third result.

Parameters:

f1 - The first future.

f2 - The second future.

f3 - The third future.

Returns:

The ARFuture with the Tuple3 of results.

all

static <T> ARFuture<java.util.List<T>> all(@NotNull
                                           @NotNull java.util.List<ARFuture<T>> list)

Returns an ARFuture that completes with a List of all results once all futures are completed.

Type Parameters:

T - The type of the result.

Parameters:

list - The list of futures.

Returns:

The ARFuture with the List of results.

all

static <T1,T2> ARFuture<Tuple2<T1,T2>> all(ARFuture<T1> f1,
                                                       ARFuture<T2> f2,
                                                       ABiConsumer<T1,T2> task)

Performs an action upon successful completion of two futures.

Type Parameters:

T1 - The type of the first result.

T2 - The type of the second result.

Parameters:

f1 - The first future.

f2 - The second future.

task - The action to perform with the results.

Returns:

The ARFuture with the Tuple2 of results.

all

static <T1,T2,T3> ARFuture<Tuple3<T1,T2,T3>> all(ARFuture<T1> f1,
                                                                         ARFuture<T2> f2,
                                                                         ARFuture<T3> f3,
                                                                         A3Consumer<T1,T2,T3> task)

Performs an action upon successful completion of three futures.

Type Parameters:

T1 - The type of the first result.

T2 - The type of the second result.

T3 - The type of the third result.

Parameters:

f1 - The first future.

f2 - The second future.

f3 - The third future.

task - The action to perform with the results.

Returns:

The ARFuture with the Tuple3 of results.

map

static <T1,T2,R> ARFuture<R> map(ARFuture<T1> f1,
                                             ARFuture<T2> f2,
                                             A2Function<T1,T2,R> task)

Maps the results of two futures to a new result type.

Type Parameters:

T1 - The type of the first result.

T2 - The type of the second result.

R - The new result type.

Parameters:

f1 - The first future.

f2 - The second future.

task - The function to map the results.

Returns:

The ARFuture with the mapped result.

map

static <T1,T2,T3,R> ARFuture<R> map(ARFuture<T1> f1,
                                                      ARFuture<T2> f2,
                                                      ARFuture<T3> f3,
                                                      A3Function<T1,T2,T3,R> task)

Maps the results of three futures to a new result type.

Type Parameters:

T1 - The type of the first result.

T2 - The type of the second result.

T3 - The type of the third result.

R - The new result type.

Parameters:

f1 - The first future.

f2 - The second future.

f3 - The third future.

task - The function to map the results.

Returns:

The ARFuture with the mapped result.

make

static <T> ARFuture<T> make()

doThrow

static <T> ARFuture<T> doThrow(java.lang.Throwable e)