de.ipcon.tools.concurrent

Class Tasklet<R>

java.lang.Object

de.ipcon.tools.concurrent.Tasklet<R>

Type Parameters:

R - the result type of the computation.

All Implemented Interfaces:

java.lang.Runnable, java.util.function.BiFunction<R,java.lang.Throwable,R>

public class Tasklet<R>
extends java.lang.Object
implements java.lang.Runnable, java.util.function.BiFunction<R,java.lang.Throwable,R>

Represents a single unit of work (a task) within the SPU (Swing Process Utility) architecture.

Lifecycle & Purpose:

A Tasklet wraps a user-provided Callable and manages its execution context. Unlike standard FutureTask, a Tasklet is designed to:

• Be queued and serialized based on a Queue ID (qid).
• Execute lazily: Creation does not imply immediate submission to an executor.
• Bridge the gap between the EDT (Event Dispatch Thread) and background threads.
• Support "blocking" on the EDT without freezing the UI via SecondaryLoop.
• Propagate context such as ProgressDisplayI and parent relationships.

The "Trigger" Mechanism:

For off-EDT tasks, this class uses a specific CompletableFuture pattern. The result future (returned to the caller) is chained to a trigger future via CompletableFuture.handleAsync(BiFunction, java.util.concurrent.Executor). Calling spawn() completes the trigger, which signals the ForkJoinPool to pick up this Tasklet (via the apply(R, java.lang.Throwable) method) and execute the actual logic.

Debugging

Tasklet supports async-stacktraces, which are disabled by default due to their impact on performance. They can be enabled by setting the log-level of this class to DEBUG, either by its client-log.conf or programmatically: org.apache.log4j.Logger.getLogger(de.ipcon.tools.concurrent.Tasklet.class).setLevel(org.apache.log4j.Level.DEBUG)

To log all Throwable thrown by tasks, additionally to completing the task exceptionally, enable Level.TRACE

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Tasklet.AsyncThreadException

Method Summary

Modifier and Type	Method and Description
java.lang.Throwable	appendAsyncThreadCause(java.lang.Throwable cause) If originThread information is logged, then the stacktraces of the originThread are added as cause to the provided throwable.
R	apply(R input, java.lang.Throwable exception) Entry point for off-EDT execution via CompletableFuture.handleAsync(java.util.function.BiFunction<? super T, java.lang.Throwable, ? extends U>).
static ProgressDisplayI	currentProgressDisplay() Retrieves the ProgressDisplayI associated with the current task.
static java.lang.Throwable	getAsyncThreadCause(java.lang.Throwable cause) Appends the Cross-Thread information of the currently running tasklet and all its parents as cause to the given cause.
void	run() The core execution logic.
static void	setCurrentProgressDisplay(ProgressDisplayI progressDisplay) Associates a ProgressDisplayI with the currently running Tasklet.
java.lang.String	toString()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.function.BiFunction

andThen

Method Detail

apply

public R apply(R input,
               java.lang.Throwable exception)

Entry point for off-EDT execution via CompletableFuture.handleAsync(java.util.function.BiFunction<? super T, java.lang.Throwable, ? extends U>).

This acts as an adapter between the CompletableFuture API and our run() method. It waits for the result (which is computed inside run()) to ensure the future chain completes.

Specified by:

apply in interface java.util.function.BiFunction<R,java.lang.Throwable,R>

Parameters:

input - ignored (result of the trigger, usually null).

exception - ignored (exception from the trigger, usually null).

Returns:

the result of the task execution.

run

public void run()

The core execution logic.

This method:

1. Sets up thread-local context (current tasklet).
2. Executes the user task.
3. Handles success/failure by completing the result future.
4. Cleans up (exits SecondaryLoop, puts task back in queue for Dispatcher cleanup).
5. Restores previous thread-local context.

Specified by:

run in interface java.lang.Runnable

setCurrentProgressDisplay

public static void setCurrentProgressDisplay(ProgressDisplayI progressDisplay)

Associates a ProgressDisplayI with the currently running Tasklet. This allows progress updates to be routed to the correct UI component associated with this task.

Parameters:

progressDisplay - the progress display to set.

getAsyncThreadCause

public static java.lang.Throwable getAsyncThreadCause(java.lang.Throwable cause)

Appends the Cross-Thread information of the currently running tasklet and all its parents as cause to the given cause. In descending order, i.e. the async stacktrace of the parent-tasklet will be the cause of the current tasklet, etc. Will not modify the cause if there already is a AsyncThreadException in one of the causes.

Parameters:

cause - a nonnull throwable to append the asynchronous threads as cause.

Returns:

the provided throwable, appended with the AsyncThreadException as cause

appendAsyncThreadCause

public java.lang.Throwable appendAsyncThreadCause(java.lang.Throwable cause)

If originThread information is logged, then the stacktraces of the originThread are added as cause to the provided throwable.

Parameters:

cause - the nullable cause to append the information to.

Returns:

null if cause is null, the cause optionally appended by the additional stacktrace information otherwise.

currentProgressDisplay

public static ProgressDisplayI currentProgressDisplay()

Retrieves the ProgressDisplayI associated with the current task.

Returns:

the progress display, or null.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object