+ coco4j

+ doc

Author: q3769

README.md

@@ -21,7 +21,8 @@ execution order at the same time.
 
 ## Prerequisite
 
-Java 8 or better
+- Java 8 or better for versions before 20230922.20230925.0 (exclusive)
+- Java 21 or better for versions after 20230922.20230925.0 (inclusive)
 
 ## Get it...
 
@@ -31,21 +32,21 @@ Install as a compile-scope dependency in Maven or other build tools alike.
 
 ## Use it...
 
-### General notes
+Some general notes:
 
-#### Sequence keys
+- Sequence keys
 
 A sequence key cannot be `null`. Any two keys, `sequenceKey1` and `sequenceKey2`, are considered "the same sequence key"
 if and only if `Objects.equals(sequenceKey1, sequenceKey2)` returns `true`.
 
-#### Thread safety
+- Thread safety
 
 A conseq4j instance is thread-safe in and of itself. The usual thread-safety rules and concerns, however, still apply
 when programming the executable tasks. Moreover, in the context of concurrency and sequencing, the thread-safety concern
 goes beyond concurrent modification of individual-task data, into that of meaningful execution order among multiple
 related tasks.
 
-#### Concurrency and sequencing
+- Concurrency and sequencing
 
 First of all, by definition, there is no such thing as order or sequence among tasks submitted concurrently by different
 threads. No particular execution order is guaranteed on those concurrent tasks, regardless of their sequence keys. The
@@ -63,10 +64,10 @@ etc...
 
 ### Style 1: summon a sequential executor by its sequence key, then use the executor as with a JDK `ExecutorService`
 
-#### API
+- API
 
 ```java
-public interface SequentialExecutorServiceFactory extends Terminable {
+public interface SequentialExecutorServiceFactory {
     /**
      * @param sequenceKey
      *         an {@link Object} instance whose hash code is used to summon the corresponding executor.
@@ -77,40 +78,6 @@ public interface SequentialExecutorServiceFactory extends Terminable {
 }
 ```
 
-where ```Terminable``` is defined as
-
-```java
-public interface Terminable {
-    /**
-     * Initiates an orderly shutdown of all managed thread resources. Previously submitted tasks are executed, but no
-     * new tasks will be accepted. Invocation has no additional effect if already shut down.
-     * <p>
-     * This method does not wait for the previously submitted tasks to complete execution. Use an external awaiting
-     * mechanism to do that, with the help of {@link #isTerminated()}.
-     */
-    void shutdown();
-
-    /**
-     * Non-blocking
-     *
-     * @return true if all tasks of all managed executors have completed following shut down. Note that isTerminated is
-     *         never true unless shutdown was called first.
-     */
-    boolean isTerminated();
-
-    /**
-     * Attempts to stop all actively executing tasks, halts the processing of waiting tasks, and returns a list of the
-     * tasks that were awaiting execution.
-     * <p>
-     * This method does not wait for the previously submitted tasks to complete execution. Use an external awaiting
-     * mechanism to do that, with the help of {@link #isTerminated()}.
-     *
-     * @return Tasks submitted but never started executing
-     */
-    List<Runnable> shutdownNow();
-}
-```
-
 This API style loosely takes the form of "thread affinity". Sequence keys are used to summon executors of JDK
 type [ExecutorService](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html). The same
 sequence key always gets back the same sequential executor. All tasks of that sequence key can then be "affined" to and
@@ -123,7 +90,7 @@ Consider using this style when the summoned executor needs to provide
 the [syntax and semantic richness](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html#method.summary)
 of the JDK `ExecutorService` API.
 
-#### Sample usage
+- Sample usage
 
 ```java
 public class MessageConsumer {
@@ -137,7 +104,8 @@ public class MessageConsumer {
      */
     private final SequentialExecutorServiceFactory conseqServiceFactory = ConseqServiceFactory.instance();
 
-    @Autowired private ShoppingEventProcessor shoppingEventProcessor;
+    @Autowired
+    private ShoppingEventProcessor shoppingEventProcessor;
 
     /**
      * Suppose run-time invocation of this method is managed by the messaging provider. This is usually via a single 
@@ -154,42 +122,46 @@ public class MessageConsumer {
 }
 ```
 
-- The implementation of this thread-affinity style relies on hashing of the sequence keys into a fixed number of
-  "buckets". These buckets are each associated with a sequential executor. The same sequence key is always hashed to and
-  summons back the same executor. Single-threaded, each executor ensures the execution order of all its tasks is the
-  same as they are submitted; excessive tasks pending execution are buffered in a FIFO task queue. Thus, the total
-  number of buckets (i.e. the max number of available executors and the general concurrency) is the maximum number of
-  tasks that can be executed in parallel at any given time.
-- As with hashing, collision may occur among different sequence keys. When hash collision happens, tasks of different
-  sequence keys are assigned to the same executor. Due to the single-thread setup, the executor still ensures the local
-  sequential execution order for each individual sequence key's tasks. However, unrelated tasks of different sequence
-  keys now assigned to the same bucket/executor may delay each other's execution inadvertently while waiting in the
-  executor's task queue. Consider this a trade-off of the executor's having the same syntax and semantic richness as a
-  JDK [ExecutorService](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html).
-- To account for hash collision, conseq4j does not support any shutdown action on the API-provided
-  executor ([ExecutorService](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html))
-  instance. That is to prevent unintended task cancellation across different sequence keys.
-  The [Future](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Future.html) instance(s) subsequently
-  returned by the executor, though, is still cancellable. The hash collision may not be an issue for workloads that are
-  asynchronous and focused on overall through-put, but is something to be aware of.
-- The default general concurrency is either 16 or the JVM
-  run-time's [availableProcessors](https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#availableProcessors--),
-  which ever is larger:
+The implementation of this thread-affinity style relies on hashing of the sequence keys into a fixed number of
+"buckets". These buckets are each associated with a sequential executor. The same sequence key is always hashed to and
+summons back the same executor. Single-threaded, each executor ensures the execution order of all its tasks is the
+same as they are submitted; excessive tasks pending execution are buffered in a FIFO task queue. Thus, the total
+number of buckets (i.e. the max number of available executors and the general concurrency) is the maximum number of
+tasks that can be executed in parallel at any given time.
+
+As with hashing, collision may occur among different sequence keys. When hash collision happens, tasks of different
+sequence keys are assigned to the same executor. Due to the single-thread setup, the executor still ensures the local
+sequential execution order for each individual sequence key's tasks. However, unrelated tasks of different sequence
+keys now assigned to the same bucket/executor may delay each other's execution inadvertently while waiting in the
+executor's task queue. Consider this a trade-off of the executor's having the same syntax and semantic richness as a
+JDK [ExecutorService](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html).
+
+To account for hash collision, conseq4j Style 1 does not support any shutdown action on the API-provided
+executor ([ExecutorService](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html))
+instance. That is to prevent unintended task cancellation across different sequence keys.
+The [Future](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Future.html) instance(s) subsequently
+returned by the executor, though, is still cancellable. The hash collision may not be an issue for workloads that are
+asynchronous and focused on overall through-put, but is something to be aware of.
+
+The default general concurrency is the JVM
+run-time's [availableProcessors](https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#availableProcessors--):
+
   ```jshelllanguage
   ConseqServiceFactory.instance();
   ```
 
-  The concurrency can be customized:
+The concurrency can be customized:
+
   ```jshelllanguage
   ConseqServiceFactory.instance(10)
   ```
 
 ### Style 2: submit each task directly for execution, together with its sequence key
 
-#### API
+- API
 
 ```java
-public interface SequentialExecutor extends Terminable {
+public interface SequentialExecutor {
     /**
      * @param command
      *         the Runnable task to run sequentially with others under the same sequence key
@@ -216,33 +188,32 @@ This API style is more concise. Bypassing the JDK ExecutorService API, it servic
 execution semantics holds: Tasks of the same sequence key are executed in the same submission order; tasks of different
 sequence keys are managed to execute in parallel.
 
-Prefer this style when the full-blown syntax and semantic support of
+For versions requiring Java 21+, conseq4j Style 2 defaults to have no preset limit on the overall concurrency when
+executing tasks; for other versions, this style's default concurrency is the number of JVM run-time'
+s [availableProcessors](https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#availableProcessors--). Prefer
+this style when the full-blown syntax and semantic support of
 JDK [ExecutorService](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html) is not
 required.
 
-#### Sample usage
+- Sample usage
 
 ```java
 public class MessageConsumer {
 
     /**
-     * Default executor concurrency is java.lang.Runtime.availableProcessors.
-     * <p>
-     * Or to provide a custom concurrency of 10, for example:
-     * <code>
-     * private SequentialExecutor conseqExecutor = ConseqExecutor.instance(10));
-     * </code>
+     * Default executor has no preset limit on overall concurrency, running on virtual thread per task.
      */
     private final SequentialExecutor conseqExecutor = ConseqExectuor.instance();
 
-    @Autowired private ShoppingEventProcessor shoppingEventProcessor;
+    @Autowired
+    private ShoppingEventProcessor shoppingEventProcessor;
 
     /**
-     * Suppose run-time invocation of this method is managed by the messaging provider. This is usually via a single 
+     * Suppose run-time invocation of this method is managed by the messaging provider. This is usually via a single
      * caller thread.
      * <p>
-     * Concurrency is achieved when shopping events of different shopping cart IDs are processed in parallel by 
-     * different backing threads. Sequence is maintained for all shopping events of the same shopping cart ID, via 
+     * Concurrency is achieved when shopping events of different shopping cart IDs are processed in parallel by
+     * different backing threads. Sequence is maintained for all shopping events of the same shopping cart ID, via
      * linear progression of execution stages with {@link java.util.concurrent.CompletableFuture}.
      */
     public void onMessage(Message shoppingEvent) {
@@ -251,32 +222,39 @@ public class MessageConsumer {
 }
 ```
 
-- The interface of this direct-execute style uses `Future` as the return type, mainly to reduce conceptual weight of the
-  API. The implementation actually returns `CompletableFuture`, and can be used/cast as such if need be.
-- The implementation relies on
-  JDK's [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) to
-  achieve sequential execution of related tasks. One single pool of threads is used to facilitate the overall
-  asynchronous execution. The concurrency to execute unrelated tasks is generally limited only by the backing work
-  thread pool's capacity.
-- Instead of thread-affinity or bucket hashing, tasks are decoupled from their execution threads. All pooled threads are
-  anonymous and interchangeable to execute any tasks. Even sequential tasks of the same sequence key may be executed by
-  different threads, albeit in sequential order. When the work thread pool has idle threads available, a task awaiting
-  execution must have been blocked only by its own related task(s) of the same sequence key - as is necessary, and not
-  by unrelated tasks of different sequence keys in the same "bucket" - as is unnecessary. This can be a desired
-  advantage over the thread-affinity API style, at the trade-off of lesser syntax and semantic richness than the
-  JDK [ExecutorService](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html).
-- The default general concurrency (i.e. the execution work thread pool capacity is the JVM
-  run-time's [availableProcessors](https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#availableProcessors--)
+The implementation relies on
+JDK's [CompletableFuture](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/CompletableFuture.html) to
+achieve sequential execution of related tasks. One single pool of threads is used to facilitate the overall
+asynchronous execution. The concurrency to execute unrelated tasks is generally limited only by the backing work
+thread pool's capacity, or unlimited in the case of default/virtual thread mode.
+
+Instead of thread-affinity or bucket hashing, tasks are decoupled from their execution threads. All pooled threads are
+anonymous and interchangeable to execute any tasks. Even sequential tasks of the same sequence key may be executed by
+different threads, albeit in sequential order. When the work thread pool has idle threads available, a task awaiting
+execution must have been blocked only by its own related task(s) of the same sequence key - as is necessary, and not
+by unrelated tasks of different sequence keys in the same "bucket" - as is unnecessary. This can be a desired
+advantage over the thread-affinity API style, at the trade-off of lesser syntax and semantic richness than the
+JDK [ExecutorService](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html).
+
+For versions requiring Java 21+, the default ConseqExecutor instance uses Virtual thread per task, and has no preset
+limit on overall concurrency. For other versions, the default concurrency is the number of JVM's available processors.
+
   ```jshelllanguage
   ConseqExecutor.instance()
   ```
-  The concurrency can be customized:
+
+The concurrency/parallelism can be customized to use a Platform thread `ForkJoinPool` of the specified capacity:
+
   ```jshelllanguage
   ConseqExecutor.instance(10)
   ```
-- The `ConseqExecutor` instance can also be powered by a fully-customized `ExecutorService`:
 
-  `ConseqExecutor.instance(ExecutorService workerExecutorService)`
+The `ConseqExecutor` instance can also use a fully-customized (Virtual or Platform thread-based) `ExecutorService` to
+power its async operations, e.g. with a fixed sized platform-thread pool:
+
+  ```jshelllanguage
+  ConseqExecutor.instance(Executors.newFixedThreadPool(10))
+  ```
 
 ## Full disclosure - Asynchronous Conundrum
 

pom.xml

@@ -27,7 +27,7 @@
     <modelVersion>4.0.0</modelVersion>
     <groupId>io.github.q3769</groupId>
     <artifactId>conseq4j</artifactId>
-    <version>20230922.20230924.20230924</version>
+    <version>20230922.20230924.20240512</version>
     <packaging>jar</packaging>
     <name>conseq4j</name>
     <description>A Java concurrent API to sequence related tasks while concurring unrelated ones</description>
@@ -129,7 +129,7 @@
             <plugin>
                 <groupId>io.github.q3769</groupId>
                 <artifactId>semver-maven-plugin</artifactId>
-                <version>20221011.20230506.20230611</version>
+                <version>20240116.0.202402</version>
             </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
@@ -149,25 +149,44 @@
                     </execution>
                 </executions>
             </plugin>
+            <plugin>
+                <groupId>com.diffplug.spotless</groupId>
+                <artifactId>spotless-maven-plugin</artifactId>
+                <version>2.43.0</version>
+                <executions>
+                    <execution>
+                        <id>spotless-apply-id</id>
+                        <phase>process-sources</phase>
+                        <goals>
+                            <goal>apply</goal>
+                        </goals>
+                    </execution>
+                </executions>
+                <configuration>
+                    <java>
+                        <palantirJavaFormat>
+                            <version>2.46.0</version>
+                            <style>PALANTIR</style>
+                            <formatJavadoc>true</formatJavadoc>
+                        </palantirJavaFormat>
+                        <removeUnusedImports/>
+                        <formatAnnotations/>
+                    </java>
+                </configuration>
+            </plugin>
         </plugins>
     </build>
     <dependencies>
-        <dependency>
-            <groupId>com.google.code.findbugs</groupId>
-            <artifactId>jsr305</artifactId>
-            <version>3.0.2</version>
-            <scope>provided</scope>
-        </dependency>
         <dependency>
             <groupId>org.projectlombok</groupId>
             <artifactId>lombok</artifactId>
-            <version>1.18.30</version>
+            <version>1.18.32</version>
             <scope>provided</scope>
         </dependency>
         <dependency>
             <groupId>org.junit.jupiter</groupId>
             <artifactId>junit-jupiter-api</artifactId>
-            <version>5.9.2</version>
+            <version>5.9.3</version>
             <scope>test</scope>
         </dependency>
         <dependency>
@@ -199,6 +218,11 @@
             <version>32.0.1-jre</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>io.github.q3769</groupId>
+            <artifactId>coco4j</artifactId>
+            <version>10.0.0</version>
+        </dependency>
     </dependencies>
     <properties>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>