Add shutdown and shutdown await functions (#255)

Author: freya022

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/commands/ratelimit/handler/DefaultRateLimitHandler.kt

@@ -29,7 +29,7 @@ import java.time.Instant
 import kotlin.time.Duration.Companion.minutes
 import kotlin.time.Duration.Companion.nanoseconds
 
-private val deleteScope = namedDefaultScope("Rate limit message delete", 1)
+private val deleteScope = namedDefaultScope("Rate limit message delete", 1, isDaemon = true)
 
 /**
  * Default [RateLimitHandler] implementation based on [rate limit scopes][RateLimitScope].

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/core/BContext.kt

@@ -11,6 +11,10 @@ import io.github.freya022.botcommands.api.core.service.annotations.InterfacedSer
 import io.github.freya022.botcommands.api.core.service.getService
 import io.github.freya022.botcommands.internal.core.exceptions.ServiceException
 import net.dv8tion.jda.api.JDA
+import java.time.Duration as JavaDuration
+import java.util.concurrent.TimeUnit
+import kotlin.time.Duration
+import kotlin.time.toKotlinDuration
 
 /**
  * Main context for BotCommands framework.
@@ -43,7 +47,21 @@ interface BContext {
          *
          * Fires [BReadyEvent].
          */
-        READY
+        READY,
+
+        /**
+         * The shutdown sequence has been initiated.
+         *
+         * A [BStatusChangeEvent] if fired, but no dedicated event.
+         */
+        SHUTTING_DOWN,
+
+        /**
+         * The instance has been completely shutdown alongside the underlying JDA instance(s)
+         *
+         * Fires [BShutdownEvent].
+         */
+        SHUTDOWN,
     }
 
     //region Configs
@@ -99,7 +117,7 @@ interface BContext {
     val jda: JDA get() = getService<JDA>()
 
     /**
-     * Returns the initialization status of the framework.
+     * Returns the status of the framework.
      *
      * @see Status
      */
@@ -146,6 +164,71 @@ interface BContext {
      */
     fun getExceptionContent(message: String, t: Throwable?, extraContext: Map<String, Any?>): String
 
+    /**
+     * Shuts down this instance of BotCommands, shutting down JDA in the process, then shutting down all executors.
+     *
+     * All currently running tasks will not be interrupted, unless [shutdownNow] is called.
+     *
+     * @see JDA.shutdown
+     * @see shutdownNow
+     */
+    fun shutdown()
+
+    /**
+     * Immediately shuts down this instance of BotCommands, shutting down JDA in the process, then shutting down all executors.
+     *
+     * All currently running tasks will be interrupted, and all coroutine scopes are canceled.
+     *
+     * @see JDA.shutdownNow
+     */
+    fun shutdownNow()
+
+    /**
+     * Blocks the current thread until the [status] is set to [SHUTDOWN][BContext.Status.SHUTDOWN].
+     *
+     * This will wait indefinitely, specify a duration if you want a timeout.
+     *
+     * Unless [shutdownNow] has been used, the shutdown time depends on the amount of requests queued in JDA,
+     * and the amount of tasks submitted to the various executors.
+     *
+     * @return Always `true`
+     */
+    fun awaitShutdown(): Boolean = awaitShutdown(Duration.INFINITE)
+
+    /**
+     * Blocks the current thread until the [status] is set to [SHUTDOWN][BContext.Status.SHUTDOWN],
+     * or until the timeout has been reached.
+     *
+     * Unless [shutdownNow] has been used, the shutdown time depends on the amount of requests queued in JDA,
+     * and the amount of tasks submitted to the various executors.
+     *
+     * @return `true` if the shutdown finished before the timeout, `false` if the timeout was reached
+     */
+    fun awaitShutdown(timeout: JavaDuration): Boolean = awaitShutdown(timeout.toKotlinDuration())
+
+    /**
+     * Blocks the current thread until the [status] is set to [SHUTDOWN][BContext.Status.SHUTDOWN],
+     * or until the timeout has been reached.
+     *
+     * Unless [shutdownNow] has been used, the shutdown time depends on the amount of requests queued in JDA,
+     * and the amount of tasks submitted to the various executors.
+     *
+     * @return `true` if the shutdown finished before the timeout, `false` if the timeout was reached
+     */
+    fun awaitShutdown(timeout: Duration): Boolean
+
+    /**
+     * Blocks the current thread until the [status] is set to [SHUTDOWN][BContext.Status.SHUTDOWN],
+     * or until the timeout has been reached.
+     *
+     * Unless [shutdownNow] has been used, the shutdown time depends on the amount of requests queued in JDA,
+     * and the amount of tasks submitted to the various executors.
+     *
+     * @return `true` if the shutdown finished before the timeout, `false` if the timeout was reached
+     */
+    fun awaitShutdown(timeout: Long, unit: TimeUnit): Boolean =
+        awaitShutdown(JavaDuration.of(timeout, unit.toChronoUnit()))
+
     /**
      * Returns the [TextCommandsContext] service.
      *

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/core/config/BConfig.kt

@@ -2,6 +2,7 @@ package io.github.freya022.botcommands.api.core.config
 
 import io.github.freya022.botcommands.api.ReceiverConsumer
 import io.github.freya022.botcommands.api.commands.text.annotations.Hidden
+import io.github.freya022.botcommands.api.core.BContext
 import io.github.freya022.botcommands.api.core.BotOwners
 import io.github.freya022.botcommands.api.core.annotations.BEventListener
 import io.github.freya022.botcommands.api.core.requests.PriorityGlobalRestRateLimiter
@@ -133,6 +134,18 @@ interface BConfigProps {
     val ignoreRestRateLimiter: Boolean
 
     val classGraphProcessors: List<ClassGraphProcessor>
+
+    /**
+     * Whether to use a [shutdown hook][Runtime.addShutdownHook] to call [BContext.shutdownNow] when the JVM is exiting **gracefully**.
+     *
+     * If disabled you'll have to shut it down yourself.
+     *
+     * Default: `true`
+     *
+     * Spring property: `botcommands.core.enableShutdownHook`
+     */
+    @ConfigurationValue("botcommands.core.enableShutdownHook", defaultValue = "true")
+    val enableShutdownHook: Boolean
 }
 
 /**
@@ -169,6 +182,8 @@ class BConfigBuilder : BConfigProps {
 
     override val classGraphProcessors: MutableList<ClassGraphProcessor> = arrayListOf()
 
+    override var enableShutdownHook: Boolean = true
+
     private val _configs: MutableMap<Class<out IConfig>, IConfig> = hashMapOf()
 
     val eventManagerConfig = BEventManagerConfigBuilder()
@@ -338,6 +353,7 @@ class BConfigBuilder : BConfigProps {
             override val ignoredEventIntents = this@BConfigBuilder.ignoredEventIntents.toImmutableSet()
             override val ignoreRestRateLimiter = this@BConfigBuilder.ignoreRestRateLimiter
             override val classGraphProcessors = this@BConfigBuilder.classGraphProcessors.toImmutableList()
+            override val enableShutdownHook = this@BConfigBuilder.enableShutdownHook
             override val eventManagerConfig = this@BConfigBuilder.eventManagerConfig.build()
             override val serviceConfig = this@BConfigBuilder.serviceConfig.build()
             override val databaseConfig = this@BConfigBuilder.databaseConfig.build()

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/core/db/Database.kt

@@ -166,7 +166,7 @@ internal fun <R> Database.withStatementJava(sql: String, readOnly: Boolean = fal
     }
 
 @PublishedApi
-internal val dbLeakScope = namedDefaultScope("Connection leak watcher", 1)
+internal val dbLeakScope = namedDefaultScope("Connection leak watcher", 1, isDaemon = true)
 
 private val currentTransaction = ThreadLocal<Transaction>()
 
@@ -445,4 +445,4 @@ internal suspend inline fun <R> Database.withReusedConnection(readOnly: Boolean,
     if (connection != null)
         return block(connection)
     return fetchConnection(readOnly).use(block)
-}
+}

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/core/events/BShutdownEvent.kt

@@ -0,0 +1,8 @@
+package io.github.freya022.botcommands.api.core.events
+
+import io.github.freya022.botcommands.api.core.BContext
+
+/**
+ * Event fired after the framework status changed to [SHUTDOWN][BContext.Status.SHUTDOWN].
+ */
+class BShutdownEvent internal constructor(context: BContext) : BEvent(context)

BotCommands-core/src/main/kotlin/io/github/freya022/botcommands/api/core/utils/Utils.kt

@@ -75,6 +75,7 @@ fun <R> withResource(url: String, block: (InputStream) -> R): R {
  *
  * @param name         The base name of the threads and coroutines, will be prefixed by the number if [corePoolSize] > 1
  * @param corePoolSize The number of threads to keep in the pool, even if they are idle, must not be negative
+ * @param isDaemon     If the new threads are daemons, useful for background tasks that should not prevent the JVM from exiting.
  * @param job          The parent job used for coroutines which can be used to cancel all children, uses [SupervisorJob] by default
  * @param errorHandler The [CoroutineExceptionHandler] used for handling uncaught exceptions,
  * uses a logging handler which cancels the parent job on [Error] by default
@@ -83,6 +84,7 @@ fun <R> withResource(url: String, block: (InputStream) -> R): R {
 fun namedDefaultScope(
     name: String,
     corePoolSize: Int,
+    isDaemon: Boolean = false,
     job: Job? = null,
     errorHandler: CoroutineExceptionHandler? = null,
     context: CoroutineContext = EmptyCoroutineContext
@@ -99,6 +101,8 @@ fun namedDefaultScope(
             } else {
                 this.name = "$name ${count.getAndIncrement()}"
             }
+
+            this.isDaemon = isDaemon
         }
     }