Package pl.morgwai.base.guice.scopes

Class ContextTrackingExecutor

java.lang.Object

pl.morgwai.base.guice.scopes.ContextTrackingExecutor

All Implemented Interfaces:

Executor

public class ContextTrackingExecutor
extends Object
implements Executor

An executor that automatically updates which thread runs within which TrackableContext when executing a task. By default backed by a fixed size ThreadPoolExecutor.

Instances usually correspond 1-1 with some type of blocking or time consuming operations, such as CPU intensive calculations or blocking network communication with some resource.
In case of network operations, a given threadPool size should usually correspond to the pool size of the connections to the given resource.
In case of CPU intensive operations, it should usually correspond to the number of cores available to the process (Runtime.availableProcessors()).

Instances are usually created at app startup, stored on static vars and/or bound for injection with a specific name:

 bind(ContextTrackingExecutor.class)
     .annotatedWith(Names.named("someOpTypeExecutor"))
     .toInstance(...)

and then injected using @Named annotation:

 @Named("someOpTypeExecutor")
 ContextTrackingExecutor someOpTypeExecutor

At app shutdown shutdown() followed by enforceTermination(long, TimeUnit) should be called on every instance.

If multiple threads run within the same context, then the attributes they access must be thread-safe or properly synchronized.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ContextTrackingExecutor.NamedThreadFactory	A thread factory that names new threads based on its own name.

Field Summary

Fields

Modifier and Type	Field	Description
protected static org.slf4j.Logger	log

Constructor Summary

Constructors

Constructor	Description
ContextTrackingExecutor(String name, int poolSize, BlockingQueue<Runnable> workQueue, ThreadFactory threadFactory, List<ContextTracker<?>> trackers)	Constructs an instance backed by a new fixed size ThreadPoolExecutor.
ContextTrackingExecutor(String name, int poolSize, BlockingQueue<Runnable> workQueue, List<ContextTracker<?>> trackers)	Constructs an instance backed by a new fixed size ThreadPoolExecutor that uses a NamedThreadFactory.
ContextTrackingExecutor(String name, int poolSize, List<ContextTracker<?>> trackers)	Constructs an instance backed by a new fixed size ThreadPoolExecutor that uses a NamedThreadFactory and an unbound LinkedBlockingQueue.
ContextTrackingExecutor(String name, ExecutorService backingExecutor, int poolSize, List<ContextTracker<?>> trackers)	Constructs an instance backed by backingExecutor.

Method Summary

Modifier and Type	Method	Description
void	awaitTermination()	Keeps calling backingExecutor.awaitTermination(Long.MAX_VALUE, TimeUnit.DAYS) until it returns true.
boolean	awaitTermination(long timeout, TimeUnit unit)	Calls backingExecutor.awaitTermination(...).
Optional<List<Runnable>>	enforceTermination(long timeout, TimeUnit unit)	Awaits up to timeoutMillis for termination and if executor fails to do so either due to timeout or interrupt shutdownNow() is called. Logs outcome to Logger named after this class.
void	execute(Runnable task)	Executes task within all contexts that were active when this method was called.
<T> CompletableFuture<T>	execute(Callable<T> task)	Convenience method to execute a Callable.
static void	executeWithinAll(List<TrackableContext<?>> contexts, Runnable operation)	Executes operation on the current thread within all contexts.
static <T> T	executeWithinAll(List<TrackableContext<?>> contexts, Callable<T> operation)	Executes operation on the current thread within all contexts.
static List<TrackableContext<?>>	getActiveContexts(List<ContextTracker<?>> trackers)	Retrieves all active contexts from trackers.
String	getName()
int	getPoolSize()
boolean	isShutdown()	Calls backingExecutor.isShutdown().
boolean	isTerminated()	Calls backingExecutor.isTerminated().
void	shutdown()	Calls backingExecutor.shutdown().
List<Runnable>	shutdownNow()	Calls backingExecutor.shutdownNow().
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

log

protected static final org.slf4j.Logger log

Constructor Detail

ContextTrackingExecutor

public ContextTrackingExecutor(String name,
                               int poolSize,
                               List<ContextTracker<?>> trackers)

Constructs an instance backed by a new fixed size ThreadPoolExecutor that uses a NamedThreadFactory and an unbound LinkedBlockingQueue.

To avoid OutOfMemoryErrors, an external mechanism that limits maximum number of tasks (such as a load balancer or a frontend proxy) should be used.

ContextTrackingExecutor

public ContextTrackingExecutor(String name,
                               int poolSize,
                               BlockingQueue<Runnable> workQueue,
                               List<ContextTracker<?>> trackers)

Constructs an instance backed by a new fixed size ThreadPoolExecutor that uses a NamedThreadFactory.

execute(Runnable) throws a RejectedExecutionException if workQueue is full. It should usually be handled by informing the client that the service has temporarily exceeded its capacity (for example a gRPC can send status UNAVAILABLE(14) and a servlet can send status 503 Service Unavailable).

ContextTrackingExecutor

public ContextTrackingExecutor(String name,
                               int poolSize,
                               BlockingQueue<Runnable> workQueue,
                               ThreadFactory threadFactory,
                               List<ContextTracker<?>> trackers)

Constructs an instance backed by a new fixed size ThreadPoolExecutor.

execute(Runnable) throws a RejectedExecutionException if workQueue is full. It should usually be handled by informing the client that the service has temporarily exceeded its capacity (for example a gRPC can send status UNAVAILABLE(14) and a servlet can send status 503 Service Unavailable).

ContextTrackingExecutor

public ContextTrackingExecutor(String name,
                               ExecutorService backingExecutor,
                               int poolSize,
                               List<ContextTracker<?>> trackers)

Constructs an instance backed by backingExecutor. poolSize is informative only, to be returned by getPoolSize().

Method Detail

getPoolSize

public int getPoolSize()

getName

public String getName()

execute

public <T> CompletableFuture<T> execute(Callable<T> task)

Convenience method to execute a Callable.

See Also:

execute(Runnable)

execute

public void execute(Runnable task)

Executes task within all contexts that were active when this method was called.

Specified by:

execute in interface Executor

getActiveContexts

public static List<TrackableContext<?>> getActiveContexts(List<ContextTracker<?>> trackers)

Retrieves all active contexts from trackers. The returned list can be then used as an argument to executeWithinAll(List, Runnable) to transfer the contexts after a switch to another thread.

Libraries usually bind List<ContextTracker<?>> to an instance containing all possible trackers for use as an argument for this method.

executeWithinAll

public static void executeWithinAll(List<TrackableContext<?>> contexts,
                                    Runnable operation)

Executes operation on the current thread within all contexts. Used to transfer active contexts after a switch to another thread.

See Also:

getActiveContexts(List)

executeWithinAll

public static <T> T executeWithinAll(List<TrackableContext<?>> contexts,
                                     Callable<T> operation)
                              throws Exception

Executes operation on the current thread within all contexts. Used to transfer active contexts after a switch to another thread.

Throws:

Exception

See Also:

getActiveContexts(List)

toString

public String toString()

Overrides:

toString in class Object

shutdown

public void shutdown()

Calls backingExecutor.shutdown().

isShutdown

public boolean isShutdown()

Calls backingExecutor.isShutdown().

isTerminated

public boolean isTerminated()

Calls backingExecutor.isTerminated().

enforceTermination

public Optional<List<Runnable>> enforceTermination(long timeout,
                                                   TimeUnit unit)
                                            throws InterruptedException

Awaits up to timeoutMillis for termination and if executor fails to do so either due to timeout or interrupt shutdownNow() is called.
Logs outcome to Logger named after this class.

Should be called at app shutdown.

Returns:

empty if the executor was shutdown cleanly, list of tasks returned by backingExecutor.shutdownNow() otherwise.

Throws:

InterruptedException

See Also:

ExecutorService.awaitTermination(long, TimeUnit), ExecutorService.shutdownNow()

awaitTermination

public boolean awaitTermination(long timeout,
                                TimeUnit unit)
                         throws InterruptedException

Calls backingExecutor.awaitTermination(...).

Throws:

InterruptedException

See Also:

enforceTermination(long, TimeUnit)

awaitTermination

public void awaitTermination()
                      throws InterruptedException

Keeps calling backingExecutor.awaitTermination(Long.MAX_VALUE, TimeUnit.DAYS) until it returns true.

Throws:

InterruptedException

See Also:

enforceTermination(long, TimeUnit), awaitTermination(long, TimeUnit)

shutdownNow

public List<Runnable> shutdownNow()

Calls backingExecutor.shutdownNow().

See Also:

enforceTermination(long, TimeUnit)