Package io.foldright.cffu

Class LLCF

java.lang.Object

io.foldright.cffu.LLCF

public final class LLCF
extends Object

Low Level CompletableFuture utility methods for manipulating CompletableFuture. This class is for library writers, the methods intended for end users are in the CompletableFutureUtils class.

In general, you should NEVER use this class, unless you understand the underlying logic of CompletableFuture and need hack it. Because the methods are Low Level, use below the method name convention intentionally:

• methods with f_ prefix means not type-safe, e.g.
  • return type CompletableFuture that may be a minimal-stage
  • force cast to CompletableFuture<T> from any CompletableFuture<?>
  • return generic type T but constrained runtime type TupleX
• methods with 0 suffix means no parameter validation, e.g.
  • no null check

Author:

Jerry Lee (oldratlee at gmail dot com)

See Also:

• CompletableFutureUtils

Field Summary

Fields

Modifier and Type	Field	Description
static final Executor	ASYNC_POOL	Default executor of CompletableFuture(NOT including the customized subclasses of CompletableFuture) -- ForkJoinPool.commonPool() unless it cannot support parallelism.

Method Summary

Modifier and Type	Method	Description
static <T> boolean	completeCf0(CompletableFuture<? super T> cf, T value, Throwable ex)	Completes the given CompletableFuture with the exception(if non-null), otherwise with the value.
static <T> CompletableFuture<T>	f_cast(CompletableFuture<?> cf)	Force casts CompletableFuture with the value type, IGNORE the compile-time type check.
static <T> CompletableFuture<T>	f_toCf0(CompletionStage<? extends T> stage)	Force converts CompletionStage to CompletableFuture, reuse cf instances as many as possible.
static <T> CompletableFuture<T>[]	f_toCfArray0(CompletionStage<? extends T>[] stages)	Force converts CompletionStage array to CompletableFuture array, reuse cf instances as many as possible.
static <T> CompletableFuture<T>	f_toCfCopy0(CompletionStage<? extends T> stage)	Converts CompletionStage to a CompletableFuture copy.
static <T> CompletableFuture<T>[]	f_toCfCopyArray0(CompletionStage<? extends T>[] stages)	Converts CompletionStage array to a CompletableFuture copy array.
static boolean	isMinStageCf(CompletableFuture<?> cf)	Checks if the given CompletableFuture instance is a minimal-stage.
static <T, X extends Throwable, F extends BiConsumer<? super T, ? super X>> F	nonExSwallowedBiConsumer(F action, boolean addSuppressedToOriginalEx)	Wraps a BiConsumer that processes exceptions to ensure that if the error handle function throws a new exception, the error context is preserved by calling Throwable.addSuppressed(java.lang.Throwable).
static <T, X extends Throwable, U, F extends BiFunction<? super T, ? extends X, ? extends U>> F	nonExSwallowedBiFunction(F fn, boolean addSuppressedToOriginalEx)	Wraps a BiFunction that processes exceptions to ensure that if the error handle function throws a new exception, the error context is preserved by calling Throwable.addSuppressed(java.lang.Throwable).
static <X extends Throwable, T, F extends Function<? super X, ? extends T>> F	nonExSwallowedFunction(F fn, boolean addSuppressedToOriginalEx)	Wraps a function that processes exceptions to ensure that if the error handle function throws a new exception, the error context is preserved by calling Throwable.addSuppressed(java.lang.Throwable).
static <T, F extends CompletionStage<? extends T>> F	peek0(F cfThis, BiConsumer<? super T,? super Throwable> action, String where)	Peeks the result by executing the given action when the given stage completes, returns the given stage.
static <T, F extends CompletionStage<? extends T>> F	peekAsync0(F cfThis, BiConsumer<? super T,? super Throwable> action, String where, Executor executor)	Peeks the result by executing the given action using the supplied executor when the given stage completes, returns the given stage.
static void	safeAddSuppressedEx(Throwable suppressed, Throwable target)	Adds a suppressed exception to a target exception, first unwrapping the target exception if it is a CompletionException or ExecutionException.
static Executor	screenExecutor(Executor e)	Null-checks user executor argument, and translates uses of commonPool to ASYNC_POOL in case parallelism disabled.
static <T> CompletableFuture<T>	toNonMinCf0(CompletionStage<? extends T> stage)	Converts CompletionStage to non-minimal-stage CompletableFuture, reuse cf instances as many as possible.
static <T> CompletableFuture<T>[]	toNonMinCfArray0(CompletionStage<? extends T>[] stages)	Converts CompletionStage array to non-minimal-stage CompletableFuture array, reuse cf instances as many as possible.
static <T> CompletableFuture<T>	toNonMinCfCopy0(CompletionStage<? extends T> stage)	Converts CompletionStage to a non-minimal-stage CompletableFuture copy.
static <T> CompletableFuture<T>[]	toNonMinCfCopyArray0(CompletionStage<? extends T>[] stages)	Converts CompletionStage array to a non-minimal-stage CompletableFuture copy array.

Methods inherited from class java.lang.Object

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

Field Details

ASYNC_POOL

public static final Executor ASYNC_POOL

Default executor of CompletableFuture(NOT including the customized subclasses of CompletableFuture) -- ForkJoinPool.commonPool() unless it cannot support parallelism.

See Also:

• CompletableFutureUtils.defaultExecutor(CompletionStage)

Method Details

f_cast

@Contract(pure=true)
public static <T> CompletableFuture<T> f_cast(CompletableFuture<?> cf)

Force casts CompletableFuture with the value type, IGNORE the compile-time type check.

f_toCf0

@Contract(pure=true)
public static <T> CompletableFuture<T> f_toCf0(CompletionStage<? extends T> stage)

Force converts CompletionStage to CompletableFuture, reuse cf instances as many as possible.

CAUTION: This method is NOT type safe! Because reused the CF instance, The returned cf may be a minimal-stage, MUST NOT be written or read(explicitly) (e.g. CompletableFuture.complete(T)); Otherwise, the caller usage of cf may throw UnsupportedOperationException.

f_toCfArray0

@Contract(pure=true)
public static <T> CompletableFuture<T>[] f_toCfArray0(CompletionStage<? extends T>[] stages)

Force converts CompletionStage array to CompletableFuture array, reuse cf instances as many as possible. This method is NOT type safe! More info see method f_toCf0(CompletionStage).

f_toCfCopy0

@Contract(pure=true)
public static <T> CompletableFuture<T> f_toCfCopy0(CompletionStage<? extends T> stage)

Converts CompletionStage to a CompletableFuture copy.

CAUTION: This method is NOT type safe! Because reused the CF instance, The returned cf may be a minimal-stage, MUST NOT be written or read(explicitly) (e.g. CompletableFuture.complete(T)); Otherwise, the caller usage of cf may throw UnsupportedOperationException.

Implementation Note: The returned instances of calling copy methods (CompletableFuture.copy()) on minimal-stage instances is still minimal-stage (e.g. minimalCompletionStage().copy(), completedStage().copy())

f_toCfCopyArray0

@Contract(pure=true)
public static <T> CompletableFuture<T>[] f_toCfCopyArray0(CompletionStage<? extends T>[] stages)

Converts CompletionStage array to a CompletableFuture copy array. This method is NOT type safe! More info see method f_toCfCopy0(CompletionStage).

toNonMinCf0

@Contract(pure=true)
public static <T> CompletableFuture<T> toNonMinCf0(CompletionStage<? extends T> stage)

Converts CompletionStage to non-minimal-stage CompletableFuture, reuse cf instances as many as possible.

CAUTION: because reused the CF instance, if the caller need defensive copy instead of writing it directly, use method toNonMinCfCopy0(CompletionStage)).

toNonMinCfArray0

@Contract(pure=true)
public static <T> CompletableFuture<T>[] toNonMinCfArray0(CompletionStage<? extends T>[] stages)

Converts CompletionStage array to non-minimal-stage CompletableFuture array, reuse cf instances as many as possible. More info see method toNonMinCf0(CompletionStage).

toNonMinCfCopy0

@Contract(pure=true)
public static <T> CompletableFuture<T> toNonMinCfCopy0(CompletionStage<? extends T> stage)

Converts CompletionStage to a non-minimal-stage CompletableFuture copy. This method is type safe.

Implementation Note: The returned instances of calling copy methods (CompletableFuture.copy()) on minimal-stage instances is still minimal-stage (e.g. minimalCompletionStage().copy(), completedStage().copy()).

toNonMinCfCopyArray0

@Contract(pure=true)
public static <T> CompletableFuture<T>[] toNonMinCfCopyArray0(CompletionStage<? extends T>[] stages)

Converts CompletionStage array to a non-minimal-stage CompletableFuture copy array. This method is type safe. More info see method toNonMinCfCopy0(CompletionStage).

isMinStageCf

@Contract(pure=true)
public static boolean isMinStageCf(CompletableFuture<?> cf)

Checks if the given CompletableFuture instance is a minimal-stage.

Implementation Note: While minimal-stage is implemented as a private subclass of CompletableFuture, the CompletableFuture API consistently uses CompletionStage type for minimal-stage instances and reserves CompletableFuture type for non-minimal-stage instances only.

This type contract for minimal-stage MUST be followed for end users APIs.

peek0

@Contract("_, _, _ -> param1")
public static <T,
F extends CompletionStage<? extends T>>
F peek0(F cfThis,
 BiConsumer<? super T,? super Throwable> action,
 String where)

Peeks the result by executing the given action when the given stage completes, returns the given stage. The uncaught exceptions thrown by the action are reported.

See Also:

• CompletableFutureUtils.peek(CompletionStage, BiConsumer)
• Errors should never pass silently. Unless explicitly silenced.

peekAsync0

@Contract("_, _, _, _ -> param1")
public static <T,
F extends CompletionStage<? extends T>>
F peekAsync0(F cfThis,
 BiConsumer<? super T,? super Throwable> action,
 String where,
 Executor executor)

Peeks the result by executing the given action using the supplied executor when the given stage completes, returns the given stage. The uncaught exceptions thrown by the action are reported.

See Also:

• CompletableFutureUtils.peekAsync(CompletionStage, BiConsumer, Executor)
• Errors should never pass silently. Unless explicitly silenced.

completeCf0

public static <T> boolean completeCf0(CompletableFuture<? super T> cf,
 @Nullable
 T value,
 @Nullable
 Throwable ex)

Completes the given CompletableFuture with the exception(if non-null), otherwise with the value. In general, you should NEVER use this method in application codes, use CompletableFuture.complete(Object) or CompletableFuture.completeExceptionally(Throwable) instead.

safeAddSuppressedEx

public static void safeAddSuppressedEx(@Nullable
 Throwable suppressed,
 Throwable target)

Adds a suppressed exception to a target exception, first unwrapping the target exception if it is a CompletionException or ExecutionException.

Unwrapping target exception is necessary to ensures suppressed exceptions are properly preserved, because CompletableFuture internally wraps exceptions in CompletionException / ExecutionException, which can later be unwrapped and discarded during CompletableFuture processing (e.g. CompletableFuture.exceptionNow()), potentially losing any suppressed exceptions that were attached to the wrapper.

Parameters:

suppressed - the exception to be added as a suppressed exception. If null, no action is taken

target - the target exception to add the suppressed exception to

See Also:

• CompletableFutureUtils.unwrapCfException(Throwable)

nonExSwallowedFunction

@Contract(value="null, _ -> null; !null, _ -> !null",
          pure=true)
@Nullable
public static <X extends Throwable,
T,
F extends Function<? super X,
? extends T>>
F nonExSwallowedFunction(@Nullable
 F fn,
 boolean addSuppressedToOriginalEx)

Wraps a function that processes exceptions to ensure that if the error handle function throws a new exception, the error context is preserved by calling Throwable.addSuppressed(java.lang.Throwable).

nonExSwallowedBiFunction

@Contract(value="null, _ -> null; !null, _ -> !null",
          pure=true)
@Nullable
public static <T,
X extends Throwable,
U,
F extends BiFunction<? super T,
? extends X,
? extends U>>
F nonExSwallowedBiFunction(@Nullable
 F fn,
 boolean addSuppressedToOriginalEx)

Wraps a BiFunction that processes exceptions to ensure that if the error handle function throws a new exception, the error context is preserved by calling Throwable.addSuppressed(java.lang.Throwable).

nonExSwallowedBiConsumer

@Contract(value="null, _ -> null; !null, _ -> !null",
          pure=true)
@Nullable
public static <T,
X extends Throwable,
F extends BiConsumer<? super T,
? super X>>
F nonExSwallowedBiConsumer(@Nullable
 F action,
 boolean addSuppressedToOriginalEx)

Wraps a BiConsumer that processes exceptions to ensure that if the error handle function throws a new exception, the error context is preserved by calling Throwable.addSuppressed(java.lang.Throwable).

screenExecutor

@Contract(pure=true)
public static Executor screenExecutor(Executor e)

Null-checks user executor argument, and translates uses of commonPool to ASYNC_POOL in case parallelism disabled.