Enhancement Request 36456812 - [36430839->24.09] Add support for defining virtual-thread-per-task executors in JDK 21 (merge main -> ce/main @ 108026)

[git-p4: depot-paths = "//dev/coherence-ce/main/": change = 108030]

Author: rlubke

prj/coherence-concurrent/README.adoc

@@ -1,8 +1,8 @@
 ///////////////////////////////////////////////////////////////////////////////
-    Copyright (c) 2021, Oracle and/or its affiliates.
+    Copyright (c) 2021, 2024, Oracle and/or its affiliates.
 
     Licensed under the Universal Permissive License v 1.0 as shown at
-    http://oss.oracle.com/licenses/upl.
+    https://oss.oracle.com/licenses/upl.
 ///////////////////////////////////////////////////////////////////////////////
 = Distributed Concurrency
 
@@ -131,6 +131,9 @@ Several executor types are available for configuration.
 
 |Work stealing
 |Creates a work-stealing thread pool using the number of available processors as its target parallelism level.
+
+|VirtualThread
+|Creates a VirtualThread-per-task ExecutorService.  Requires JDK 21 or newer.
 |===
 
 ===== Configuration Elements
@@ -158,6 +161,11 @@ Several executor types are available for configuration.
 |N/A
 |Defines a work-stealing-pool executor
 
+|virtual-per-task
+|no
+|N/A
+|Defines a VirtualThread-per-task executor
+
 |name
 |yes
 |java.lang.String

prj/coherence-concurrent/pom.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
-  ~ Copyright (c) 2000, 2023, Oracle and/or its affiliates.
+  ~ Copyright (c) 2000, 2024, Oracle and/or its affiliates.
   ~
   ~ Licensed under the Universal Permissive License v 1.0 as shown at
   ~ https://oss.oracle.com/licenses/upl.
@@ -85,6 +85,11 @@
       <plugin>
         <groupId>org.apache.felix</groupId>
         <artifactId>maven-bundle-plugin</artifactId>
+        <configuration>
+          <instructions>
+            <Multi-Release>true</Multi-Release>
+          </instructions>
+        </configuration>
       </plugin>
 
       <!-- maven-jar-plugin with configuration to package generated MANIFEST.MF to project jar -->
@@ -130,6 +135,26 @@
         </executions>
       </plugin>
 
+      <plugin>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>compile-java21</id>
+            <phase>compile</phase>
+            <goals>
+              <goal>compile</goal>
+            </goals>
+            <configuration>
+              <release>21</release>
+              <compileSourceRoots>
+                <compileSourceRoot>${project.basedir}/src/main/java21</compileSourceRoot>
+              </compileSourceRoots>
+              <multiReleaseOutput>true</multiReleaseOutput>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+
       <!-- this is necessary as this concurrent.xsd includes coherence-config-base.xsd.  -->
       <plugin>
         <artifactId>maven-resources-plugin</artifactId>

prj/coherence-concurrent/src/main/java/com/oracle/coherence/concurrent/config/builders/AbstractExecutorBuilder.java

@@ -1,8 +1,8 @@
 /*
- * Copyright (c) 2021 Oracle and/or its affiliates.
+ * Copyright (c) 2021, 2024, Oracle and/or its affiliates.
  *
  * Licensed under the Universal Permissive License v 1.0 as shown at
- * http://oss.oracle.com/licenses/upl.
+ * https://oss.oracle.com/licenses/upl.
  */
 package com.oracle.coherence.concurrent.config.builders;
 
@@ -16,7 +16,6 @@
 import com.tangosol.config.annotation.Injectable;
 import com.tangosol.config.expression.Expression;
 
-
 /**
  * Base {@link ParameterizedBuilder} fpr named executors.
  *

prj/coherence-concurrent/src/main/java/com/oracle/coherence/concurrent/config/builders/AbstractExecutorWithFactoryBuilder.java

@@ -7,13 +7,16 @@
 package com.oracle.coherence.concurrent.config.builders;
 
 import com.oracle.coherence.concurrent.executor.util.NamedThreadFactory;
+
 import com.tangosol.coherence.config.ParameterList;
+
 import com.tangosol.coherence.config.builder.ParameterizedBuilder;
 
 import com.tangosol.config.annotation.Injectable;
 
 import com.tangosol.config.expression.Parameter;
 import com.tangosol.config.expression.ParameterResolver;
+
 import java.util.concurrent.ThreadFactory;
 
 /**
@@ -66,11 +69,24 @@ protected ThreadFactory instantiateThreadFactory(String sName,
             ParameterResolver resolver, ClassLoader loader, ParameterList listParameters)
         {
         return m_bldr == null
-                ? new NamedThreadFactory(sName)
+                ? instantiateNamedThreadFactory(sName)
                 : m_bldr.realize(resolver, loader, listParameters);
 
         }
 
+    /**
+     * Creates a new {@link NamedThreadFactory}
+     *
+     * @param sName  the name to use if no user-defined ThreadFactory
+     *               is defined
+     *
+     * @return the {@link NamedThreadFactory}
+     */
+    protected ThreadFactory instantiateNamedThreadFactory(String sName)
+        {
+        return new NamedThreadFactory(sName);
+        }
+
     // ----- data members ---------------------------------------------------
 
     /**

prj/coherence-concurrent/src/main/java/com/oracle/coherence/concurrent/config/builders/CachedBuilder.java

@@ -9,6 +9,7 @@
 import com.oracle.coherence.concurrent.config.NamedExecutorService;
 
 import com.oracle.coherence.concurrent.executor.util.NamedThreadFactory;
+
 import com.tangosol.coherence.config.ParameterList;
 
 import com.tangosol.coherence.config.builder.ParameterizedBuilder;

prj/coherence-concurrent/src/main/java/com/oracle/coherence/concurrent/config/builders/FixedBuilder.java

@@ -9,6 +9,7 @@
 import com.oracle.coherence.concurrent.config.NamedExecutorService;
 
 import com.oracle.coherence.concurrent.executor.util.NamedThreadFactory;
+
 import com.tangosol.coherence.config.ParameterList;
 
 import com.tangosol.coherence.config.builder.ParameterizedBuilder;

prj/coherence-concurrent/src/main/java/com/oracle/coherence/concurrent/config/builders/SingleBuilder.java

@@ -9,6 +9,7 @@
 import com.oracle.coherence.concurrent.config.NamedExecutorService;
 
 import com.oracle.coherence.concurrent.executor.util.NamedThreadFactory;
+
 import com.tangosol.coherence.config.ParameterList;
 
 import com.tangosol.coherence.config.builder.ParameterizedBuilder;

prj/coherence-concurrent/src/main/java/com/oracle/coherence/concurrent/executor/util/NamedThreadFactory.java

@@ -7,8 +7,8 @@
 package com.oracle.coherence.concurrent.executor.util;
 
 import java.util.concurrent.ThreadFactory;
-import java.util.concurrent.atomic.AtomicInteger;
 
+import java.util.concurrent.atomic.AtomicInteger;
 
 /**
  * A {@link ThreadFactory} implementation for used with {@code named}
@@ -45,12 +45,33 @@ public NamedThreadFactory(String f_sName)
     @Override
     public Thread newThread(Runnable r)
         {
-        return new Thread(r, "CES:" + f_sName + '-' + f_counter.incrementAndGet());
+        return newThread(r, "CES:" + f_sName + '-' + f_counter.incrementAndGet());
+        }
+
+    // ----- helper methods -------------------------------------------------
+
+    /**
+     * Creates a new thread for the given runnable and using the given name.
+     *
+     * @param r      the {@link Runnable}
+     * @param sName  the name of the thread
+     *
+     * @return a new thread for the given runnable and using the given name
+     */
+    public Thread newThread(Runnable r, String sName)
+        {
+        return new Thread(r, sName);
         }
 
     // ----- data members ---------------------------------------------------
 
+    /**
+     * The thread counter.
+     */
     protected final AtomicInteger f_counter = new AtomicInteger();
 
+    /**
+     * The thread name.
+     */
     protected final String f_sName;
     }

prj/coherence-concurrent/src/main/java21/com/oracle/coherence/concurrent/config/NamespaceHandler.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2024, Oracle and/or its affiliates.
+ *
+ * Licensed under the Universal Permissive License v 1.0 as shown at
+ * https://oss.oracle.com/licenses/upl.
+ */
+package com.oracle.coherence.concurrent.config;
+
+import com.oracle.coherence.concurrent.config.processors.CachedProcessor;
+import com.oracle.coherence.concurrent.config.processors.FixedProcessor;
+import com.oracle.coherence.concurrent.config.processors.SingleProcessor;
+import com.oracle.coherence.concurrent.config.processors.ThreadFactoryProcessor;
+import com.oracle.coherence.concurrent.config.processors.WorkStealingProcessor;
+import com.oracle.coherence.concurrent.config.processors.VirtualPerTaskProcessor;
+
+import com.tangosol.config.xml.AbstractNamespaceHandler;
+
+/**
+ * {@link com.tangosol.config.xml.NamespaceHandler} for processing
+ * {@code coherence-concurrent}-related artifacts defined in a Coherence
+ * configuration file.
+ *
+ * @author rl  11.20.21
+ * @since 21.12
+ */
+public class NamespaceHandler
+        extends AbstractNamespaceHandler
+    {
+    // ----- constructors ---------------------------------------------------
+
+    /**
+     * Construct {@code NamespaceHandler} instance.
+     */
+    public NamespaceHandler()
+        {
+        registerProcessor(CachedProcessor.class);
+        registerProcessor(FixedProcessor.class);
+        registerProcessor(SingleProcessor.class);
+        registerProcessor(ThreadFactoryProcessor.class);
+        registerProcessor(WorkStealingProcessor.class);
+        registerProcessor(VirtualPerTaskProcessor.class);
+        }
+    }

prj/coherence-concurrent/src/main/java21/com/oracle/coherence/concurrent/config/builders/VirtualPerTaskBuilder.java

@@ -0,0 +1,113 @@
+/*
+ * Copyright (c) 2024, Oracle and/or its affiliates.
+ *
+ * Licensed under the Universal Permissive License v 1.0 as shown at
+ * https://oss.oracle.com/licenses/upl.
+ */
+package com.oracle.coherence.concurrent.config.builders;
+
+import com.oracle.coherence.concurrent.config.NamedExecutorService;
+
+import com.oracle.coherence.concurrent.executor.util.NamedThreadFactory;
+
+import com.tangosol.coherence.config.ParameterList;
+
+import com.tangosol.coherence.config.builder.ParameterizedBuilder;
+
+import com.tangosol.config.expression.ParameterResolver;
+
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.ThreadFactory;
+
+import java.util.function.Supplier;
+
+/**
+ * A {@link ParameterizedBuilder} for constructing a {@link NamedExecutorService}
+ * wrapper that will construct a virtual-thread-per-task executor.
+ *
+ * @author rl  3.26.2024
+ * @since 15.1.1.0
+ */
+public class VirtualPerTaskBuilder
+        extends AbstractExecutorWithFactoryBuilder<NamedExecutorService>
+    {
+    // ----- ParameterizedBuilder interface ---------------------------------
+
+    @Override
+    public NamedExecutorService realize(ParameterResolver resolver, ClassLoader loader, ParameterList listParameters)
+        {
+        String                    sName    = m_name.evaluate(resolver);
+        ThreadFactory             factory  = instantiateThreadFactory(sName, resolver,
+                                                                      loader, listParameters);
+        Supplier<ExecutorService> supplier = factory == null
+                                                 ? Executors::newVirtualThreadPerTaskExecutor
+                                                 : () -> Executors.newThreadPerTaskExecutor(factory);
+        NamedExecutorService      service  = new NamedExecutorService(sName, description(factory), supplier);
+
+        register(service);
+
+        return service;
+        }
+
+    // ----- helper methods -------------------------------------------------
+
+    @Override
+    protected ThreadFactory instantiateNamedThreadFactory(String sName)
+        {
+        return new VirtualNamedThreadFactory(sName);
+        }
+
+    // ----- inner class: VirtualNamedThreadFactory -------------------------
+
+    /**
+     * A {@link ThreadFactory} for virtual threads.
+     */
+    protected static class VirtualNamedThreadFactory
+            extends NamedThreadFactory
+        {
+        // ----- constructors -----------------------------------------------
+
+        /**
+         * Constructs a new {@code VirtualNamedThreadFactory}.
+         *
+         * @param f_sName  the base name that will be used when naming
+         *                 threads
+         */
+        public VirtualNamedThreadFactory(String f_sName)
+            {
+            super(f_sName);
+            }
+
+        // ----- NamedThreadFactory methods ---------------------------------
+
+        @Override
+        public Thread newThread(Runnable r, String sName)
+            {
+            Thread.Builder.OfVirtual builder = Thread.ofVirtual();
+            if (sName != null)
+                {
+                builder.name(sName);
+                }
+            return builder.unstarted(r);
+            }
+        }
+
+    // ----- helper methods -------------------------------------------------
+
+    /**
+     * Creates the description for this executor.
+     *
+     * @param factory  the {@link ThreadFactory}, if any
+     *
+     * @return the description for this executor
+     */
+    protected String description(ThreadFactory factory)
+        {
+        String sFactory = factory == null || VirtualNamedThreadFactory.class.equals(factory.getClass())
+                          ? "default"
+                          : factory.getClass().getName();
+
+        return String.format("VirtualThreadPerTask(ThreadFactory=%s)", sFactory);
+        }
+    }