Use a Priority class instead of int for shutdown tasks priorities

Author: marko-bekhta

core/deployment/src/main/java/io/quarkus/deployment/builditem/ShutdownContextBuildItem.java

@@ -20,12 +20,7 @@ public final class ShutdownContextBuildItem extends SimpleBuildItem
     }
 
     @Override
-    public void addShutdownTask(int priority, Runnable runnable) {
-        throw new IllegalStateException();
-    }
-
-    @Override
-    public void addLastShutdownTask(int priority, Runnable runnable) {
+    public void addShutdownTask(Priority priority, Runnable runnable) {
         throw new IllegalStateException();
     }
 }

core/runtime/src/main/java/io/quarkus/runtime/ExecutorRecorder.java

@@ -1,5 +1,7 @@
 package io.quarkus.runtime;
 
+import static io.quarkus.runtime.ShutdownContext.*;
+
 import java.time.Duration;
 import java.util.List;
 import java.util.Optional;
@@ -39,7 +41,7 @@ public ScheduledExecutorService setupRunTime(ShutdownContext shutdownContext,
             LaunchMode launchMode, ThreadFactory threadFactory, ContextHandler<Object> contextHandler) {
         final EnhancedQueueExecutor underlying = createExecutor(threadPoolConfig, threadFactory, contextHandler);
         if (launchMode == LaunchMode.DEVELOPMENT) {
-            shutdownContext.addLastShutdownTask(new Runnable() {
+            shutdownContext.addShutdownTask(Priority.core(), new Runnable() {
                 @Override
                 public void run() {
                     for (Runnable i : underlying.shutdownNow()) {
@@ -53,7 +55,7 @@ public void run() {
             });
         } else {
             Runnable shutdownTask = createShutdownTask(threadPoolConfig, underlying);
-            shutdownContext.addLastShutdownTask(shutdownTask);
+            shutdownContext.addShutdownTask(Priority.core(), shutdownTask);
         }
         if (threadPoolConfig.prefill()) {
             underlying.prestartAllCoreThreads();

core/runtime/src/main/java/io/quarkus/runtime/ShutdownContext.java

@@ -3,8 +3,6 @@
 import java.io.Closeable;
 import java.io.IOException;
 
-import jakarta.interceptor.Interceptor;
-
 import org.jboss.logging.Logger;
 
 /**
@@ -14,21 +12,118 @@
  */
 public interface ShutdownContext {
 
-    int DEFAULT_PRIORITY = Interceptor.Priority.LIBRARY_AFTER;
-    int SHUTDOWN_EVENT_PRIORITY = DEFAULT_PRIORITY + 100_000;
+    /**
+     * Priority that define the order in which shutdown tasks are invoked.
+     */
+    interface Priority {
+        int value();
 
-    default void addShutdownTask(Runnable runnable) {
-        addShutdownTask(DEFAULT_PRIORITY, runnable);
-    }
+        /**
+         * For shutdown tasks that have to be executed before the {@link ShutdownEvent application shutdown event}.
+         */
+        static Priority application(int priority) {
+            if (priority == 0) {
+                // do not allow 0 priority as it has a "unique" meaning here.
+                throw new IllegalArgumentException("Use the applicationShutdownEvent() instead.");
+            }
+            return PriorityImpl.priority(priority, PriorityImpl.APPLICATION_VALUE, Integer.MAX_VALUE);
+        }
+
+        /**
+         * This "unique" priority represents the execution of the {@link ShutdownEvent application shutdown event}.
+         */
+        static Priority applicationShutdownEvent() {
+            return PriorityImpl.APPLICATION;
+        }
+
+        /**
+         * For extension shutdown tasks that are executed after all {@link ShutdownEvent application shutdown event} handlers,
+         * but may still require access to some CDI beans.
+         */
+        static Priority extensionPreCdi(int priority) {
+            return PriorityImpl.priority(priority, PriorityImpl.EXTENSIONS_VALUE, PriorityImpl.EXTENSIONS_CDI_VALUE);
+        }
+
+        /**
+         * This "unique" priority represents the shutdown of the CDI container, and any shutdown tasks after it won't be able to
+         * leverage any CDI beans.
+         */
+        static Priority cdiShutdown() {
+            return PriorityImpl.EXTENSIONS_CDI;
+        }
+
+        /**
+         * For extension shutdown tasks that do not require CDI beans.
+         */
+        static Priority extensionPostCdi(int priority) {
+            return PriorityImpl.priority(priority, PriorityImpl.EXTENSIONS_VALUE, PriorityImpl.EXTENSIONS_CDI_VALUE);
+        }
+
+        /**
+         * Same as {@link #extensionPostCdi(int)} with the default priority for convenience.
+         */
+        static Priority extensionPostCdi() {
+            return PriorityImpl.EXTENSION;
+        }
 
-    void addShutdownTask(int priority, Runnable runnable);
+        /**
+         * For core extensions like Vert.x that have to be shut down in the very end.
+         */
+        static Priority core(int priority) {
+            return PriorityImpl.priority(priority, PriorityImpl.CORE_VALUE, PriorityImpl.EXTENSIONS_VALUE);
+        }
+
+        /**
+         * Same as {@link #core(int)} with the default priority for convenience.
+         */
+        static Priority core() {
+            return PriorityImpl.CORE;
+        }
+
+        /**
+         * Most likely an unusable range of priorities to run shutdown tasks after core extensions were already shut down.
+         */
+        static Priority afterCore(int priority) {
+            return PriorityImpl.priority(priority, 0, PriorityImpl.CORE_VALUE);
+        }
+
+        record PriorityImpl(int value) implements Priority {
+            private static final int CORE_VALUE = 100_000;
+            private static final int EXTENSIONS_VALUE = 500_000;
+            private static final int EXTENSIONS_CDI_VALUE = 550_000;
+            private static final int APPLICATION_VALUE = 1_000_000;
 
-    // these are executed after all the ones added via addShutdownTask in the reverse order from which they were added
-    default void addLastShutdownTask(Runnable runnable) {
-        addLastShutdownTask(DEFAULT_PRIORITY, runnable);
+            private static final Priority CORE = new PriorityImpl(CORE_VALUE);
+            private static final Priority EXTENSION = new PriorityImpl(EXTENSIONS_VALUE);
+            private static final Priority EXTENSIONS_CDI = new PriorityImpl(EXTENSIONS_CDI_VALUE);
+            private static final Priority APPLICATION = new PriorityImpl(APPLICATION_VALUE);
+
+            private static Priority priority(int priority, int min, int max) {
+                int value;
+                if (priority > 0) {
+                    value = min + priority;
+                } else {
+                    value = max + priority;
+                }
+                if (value >= max || value < min) {
+                    throw new IllegalArgumentException("Priority value " + priority + " (effective: " + value
+                            + ") is not within the allowed range for this group: [" + min + ", " + max + ")");
+                }
+                return new PriorityImpl(value);
+            }
+        }
+
+    }
+
+    default void addShutdownTask(Runnable runnable) {
+        addShutdownTask(Priority.extensionPostCdi(), runnable);
     }
 
-    void addLastShutdownTask(int priority, Runnable runnable);
+    /**
+     * @param priority higher the priority -- sooner the shutdown task is going to be performed.
+     * @param runnable the shutdown task to perform.
+     */
+    void addShutdownTask(Priority priority, Runnable runnable);
 
     class CloseRunnable implements Runnable {
 

core/runtime/src/main/java/io/quarkus/runtime/StartupContext.java

@@ -21,27 +21,17 @@ public class StartupContext implements Closeable {
     private final Map<String, Object> values = new HashMap<>();
 
     private final PriorityBlockingQueue<ShutdownTask> shutdownTasks = new PriorityBlockingQueue<>();
-    private final PriorityBlockingQueue<ShutdownTask> lastShutdownTasks = new PriorityBlockingQueue<>();
     private String[] commandLineArgs;
     private String currentBuildStepName;
 
     public StartupContext() {
         ShutdownContext shutdownContext = new ShutdownContext() {
             @Override
-            public void addShutdownTask(int priority, Runnable runnable) {
-                if (runnable != null) {
-                    shutdownTasks.offer(new ShutdownTask(priority, runnable));
+            public void addShutdownTask(Priority priority, Runnable runnable) {
+                if (runnable != null && priority != null) {
+                    shutdownTasks.offer(new ShutdownTask(priority.value(), runnable));
                 } else {
-                    throw new IllegalArgumentException("Extension passed an invalid shutdown handler");
-                }
-            }
-
-            @Override
-            public void addLastShutdownTask(int priority, Runnable runnable) {
-                if (runnable != null) {
-                    lastShutdownTasks.offer(new ShutdownTask(priority, runnable));
-                } else {
-                    throw new IllegalArgumentException("Extension passed an invalid last shutdown handler");
+                    throw new IllegalArgumentException("Extension passed an invalid shutdown priority/handler");
                 }
             }
         };
@@ -68,7 +58,6 @@ public Object getValue(String name) {
     @Override
     public void close() {
         runAllAndClear(shutdownTasks);
-        runAllAndClear(lastShutdownTasks);
         values.clear();
     }
 

core/runtime/src/main/java/io/quarkus/runtime/configuration/ConfigRecorder.java

@@ -3,6 +3,7 @@
 import static io.quarkus.runtime.ConfigConfig.BuildTimeMismatchAtRuntime;
 import static io.quarkus.runtime.ConfigConfig.BuildTimeMismatchAtRuntime.fail;
 import static io.quarkus.runtime.ConfigConfig.BuildTimeMismatchAtRuntime.warn;
+import static io.quarkus.runtime.ShutdownContext.*;
 
 import java.util.ArrayList;
 import java.util.List;
@@ -109,6 +110,6 @@ public void releaseConfig(ShutdownContext shutdownContext) {
             throw new RuntimeException(
                     "Internal errror: shutdownContext is null. This probably happened because Quarkus failed to start properly in an earlier step, or because tests were run on a Quarkus instance that had already been shut down.");
         }
-        shutdownContext.addLastShutdownTask(QuarkusConfigFactory::releaseTCCLConfig);
+        shutdownContext.addShutdownTask(Priority.core(), QuarkusConfigFactory::releaseTCCLConfig);
     }
 }

core/runtime/src/main/java/io/quarkus/runtime/dev/io/NioThreadPoolRecorder.java

@@ -1,5 +1,7 @@
 package io.quarkus.runtime.dev.io;
 
+import static io.quarkus.runtime.ShutdownContext.*;
+
 import io.quarkus.dev.io.NioThreadPoolThreadFactory;
 import io.quarkus.runtime.ShutdownContext;
 import io.quarkus.runtime.annotations.Recorder;
@@ -11,7 +13,7 @@ public void updateTccl(ShutdownContext context) {
         ClassLoader newTccl = Thread.currentThread().getContextClassLoader();
         ClassLoader oldTccl = NioThreadPoolThreadFactory.updateTccl(newTccl);
         if (newTccl != oldTccl) {
-            context.addLastShutdownTask(new Runnable() {
+            context.addShutdownTask(Priority.core(), new Runnable() {
                 @Override
                 public void run() {
                     NioThreadPoolThreadFactory.updateTccl(oldTccl);

extensions/arc/runtime/src/main/java/io/quarkus/arc/runtime/ArcRecorder.java

@@ -27,6 +27,7 @@
 import io.quarkus.runtime.LaunchMode;
 import io.quarkus.runtime.RuntimeValue;
 import io.quarkus.runtime.ShutdownContext;
+import io.quarkus.runtime.ShutdownContext.Priority;
 import io.quarkus.runtime.ShutdownEvent;
 import io.quarkus.runtime.StartupEvent;
 import io.quarkus.runtime.annotations.Recorder;
@@ -50,7 +51,7 @@ public ArcContainer initContainer(ShutdownContext shutdown, RuntimeValue<Current
         builder.setCurrentContextFactory(currentContextFactory != null ? currentContextFactory.getValue() : null);
         builder.setStrictCompatibility(strictCompatibility);
         ArcContainer container = Arc.initialize(builder.build());
-        shutdown.addShutdownTask(new Runnable() {
+        shutdown.addShutdownTask(Priority.cdiShutdown(), new Runnable() {
             @Override
             public void run() {
                 Arc.shutdown();
@@ -113,7 +114,7 @@ public void handleLifecycleEvents(ShutdownContext context, LaunchMode launchMode
 
         fireLifecycleEvent(container, new StartupEvent(), mockBeanClasses);
 
-        context.addShutdownTask(ShutdownContext.SHUTDOWN_EVENT_PRIORITY, new Runnable() {
+        context.addShutdownTask(Priority.applicationShutdownEvent(), new Runnable() {
             @Override
             public void run() {
                 fireLifecycleEvent(container, new ShutdownEvent(ApplicationLifecycleManager.shutdownReason), mockBeanClasses);

extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/HibernateOrmRecorder.java

@@ -100,13 +100,12 @@ public DataSourceTenantConnectionResolver get() {
     public Supplier<JPAConfig> jpaConfigSupplier(HibernateOrmRuntimeConfig config, ShutdownContext shutdownContext) {
         return () -> {
             JPAConfig jpaConfig = new JPAConfig(config);
-            shutdownContext.addShutdownTask(
-                    ShutdownContext.DEFAULT_PRIORITY + 1, new Runnable() {
-                        @Override
-                        public void run() {
-                            jpaConfig.shutdown();
-                        }
-                    });
+            shutdownContext.addShutdownTask(ShutdownContext.Priority.extensionPreCdi(-1), new Runnable() {
+                @Override
+                public void run() {
+                    jpaConfig.shutdown();
+                }
+            });
             return jpaConfig;
         };
     }

extensions/narayana-jta/runtime/src/main/java/io/quarkus/narayana/jta/runtime/NarayanaJtaRecorder.java

@@ -1,5 +1,7 @@
 package io.quarkus.narayana.jta.runtime;
 
+import static io.quarkus.runtime.ShutdownContext.*;
+
 import java.lang.reflect.Field;
 import java.nio.charset.StandardCharsets;
 import java.security.MessageDigest;
@@ -220,7 +222,7 @@ public void handleShutdown(ShutdownContext context, TransactionManagerConfigurat
                 }
             }
         });
-        context.addLastShutdownTask(() -> {
+        context.addShutdownTask(Priority.core(), () -> {
             TransactionReaper.terminate(false);
         });
     }

extensions/observability-devservices/runtime/src/main/java/io/quarkus/observability/runtime/DevResourceShutdownRecorder.java

@@ -7,6 +7,6 @@
 @Recorder
 public class DevResourceShutdownRecorder {
     public void shutdown(ShutdownContext context) {
-        context.addLastShutdownTask(DevResources::stop);
+        context.addShutdownTask(ShutdownContext.Priority.core(), DevResources::stop);
     }
 }