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, C extends CompletionStage<? extends T>> C	peek0(C 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, C extends CompletionStage<? extends T>> C	peekAsync0(C 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 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,
C extends CompletionStage<? extends T>>
C peek0(C 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,
C extends CompletionStage<? extends T>>
C peekAsync0(C 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.

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.