MicroProfile Concurrency

• Status: new

• Decision Notes: Discussion thread topic with background and covering the design

Introduction

The proposal introduces APIs for obtaining CompletableFutures that are backed by managed threads (threads that are managed by the container), with the ability to capture context from the thread that creates the CompletableFuture and apply it when running the CompletionStage action.

Motivation

When using a reactive model with dependent stages which execute upon completion of prior stages, the context under which dependent stages execute is unpredictable. Dependent stages might run with the context of a thread that awaits completion, or the context of a previous stage that completed and triggered the dependent stage, or with no/undefined context at all. Existing solutions for transferring thread context, such as the EE Concurrency Utilities ContextService, are difficult to use and require a lot of boilerplate code. This spec makes it possible for thread context propagation to easily be done in a type-safe way, keeping boilerplate code to a minimum, as well as allowing for thread context propagation to be done automatically when using a CompletableFuture.

It is also important that CompletableFutures and their dependent stages, and dependent stages created by those stages, and so on, all run on threads that are known by the container and properly managed by it. This spec makes it possible to do so by providing an API by which the user obtains managed CompletableFuture instances from a managed executor.

The above are proposed to be addressed within EE Concurrency under EE Concurrency Issue 40, however, it will be a while before Jakarta EE specs are able to make progress, leading us to address this first in MicroProfile.

Goals

• Proper management of CompletableFuture threads by the container.

• Mechanism for thread context propagation to CompletableFuture actions that reduces the need for boilerplate code.

• Full compatibility with EE Concurrency spec, such that proposed interfaces can eventually be seamlessly merged into EE Concurrency.

Proposed solution

This spec introduces two interfaces that contain methods that we hope will eventually be added to Jakarta EE Concurrency.

The interface, org.eclipse.microprofile.concurrent.ManagedExecutor, provides methods for obtaining managed instances of CompletableFuture which are backed by the managed executor as the default asynchronous execution facility and the default mechanism of defining thread context propagation. Similar to EE Concurrency’s ManagedExecutorService, the MicroProfile ManagedExecutor also implements the Java SE java.util.concurrent.ExecutorService interface, using managed threads when asynchronous invocation is required and disallowing the same life cycle methods as ManagedExecutorService. It is intended that ManagedExecutor methods will one day be added to ManagedExecutorService, and for a single implementation to be capable of simultaneously implementing both interfaces, both currently as well as after adoption into Jakarta EE.

A second interface, org.eclipse.microprofile.concurrent.ThreadContext, provides methods for individually contextualizing dependent stage actions. This gives the user more fine-grained control over the capture and propagation of thread context. It is intended that ThreadContext methods will one day be added to EE Concurrency’s ContextService and for a single implementation to be capable of simultaneously implementing both interfaces, both currently as well as after adoption into Jakarta EE.

Injection

It shall be possible to inject instances of ManagedExecutor and ThreadContext via the @Inject annotation, for example:

  @Inject ManagedExecutor executor;
  @Inject ThreadContext threadContext;
  ...
  CompletableFuture<Integer> stage = executor
      .supplyAsync(supplier1)
      .thenApplyAsync(function1)
      .thenApply(function2)
      .thenApply(threadContext.contextualFunction(function3));

The container provides default instances of ManagedExecutor and ThreadContext, which are injected above.

Configuration

Annotations are provided to configure injected instances other than the defaults.

The following is an example of configuring a ManagedExecutor to only propagate CDI context plus context CDI depends upon (Application) and limit the number of async completion stage actions running at any given point in time to 5,

  @Inject @ManagedExecutorConfig(propagated=ThreadContext.CDI, maxAsync=5)
  ManagedExecutor executor;

The following is an example of configuring a ThreadContext to only capture and propagate Security context,

  @Inject @ThreadContextConfig(ThreadContext.SECURITY)
  ThreadContext threadContext;

SPI for Thread Context Providers

The initial release of EE Concurrency assumed single monolithic implementations of all specifications together that could rely on vendor-specific internals to achieve context propagation. However, in practice, open source implementations of various specs are often pieced together into a comprehensive solution.

The thread context provider SPI is defined to bridge the gap, allowing any provider of thread context to publish and make available the type of thread context it supports, following a standard and predictable pattern that can be relied upon by a MicroProfile Concurrency implementation, enabling it to facilitate the inclusion of any generic thread context alongside the spec defined thread context types that it captures and propagates.

With this model, the provider of thread context implements the org.eclipse.microprofile.concurrent.spi.ThreadContextProvider interface and packages it in a way that makes it available to the ServiceLoader. ThreadContextProvider identifies the thread context type and provides a way to capture snapshots of thread context as well as for applying empty/cleared context to threads.