Add setters for the failure and starvation reporters in IOApp

Author: BalmungSan

core/js/src/main/scala/cats/effect/IOApp.scala

@@ -17,7 +17,6 @@
 package cats.effect
 
 import cats.effect.metrics.{CpuStarvationWarningMetrics, JsCpuStarvationMetrics}
-import cats.effect.std.Console
 import cats.effect.tracing.TracingConstants._
 
 import scala.concurrent.CancellationException
@@ -147,6 +146,14 @@ trait IOApp {
 
   private[this] var _runtime: unsafe.IORuntime = null
 
+  @volatile
+  private[this] var _failureReporter: Throwable => IO[Unit] =
+    err => IO.consoleForIO.printStackTrace(err)
+
+  @volatile
+  private[this] var _onCpuStarvationReporter: CpuStarvationWarningMetrics => IO[Unit] =
+    metrics => CpuStarvationCheck.logWarning(metrics)
+
   /**
    * The runtime which will be used by `IOApp` to evaluate the [[IO]] produced by the `run`
    * method. This may be overridden by `IOApp` implementations which have extremely specialized
@@ -175,15 +182,57 @@ trait IOApp {
    * runtime. With that said, some care should be taken to avoid raising unhandled errors as a
    * result of handling unhandled errors, since that will result in the obvious chaos.
    */
+  @deprecatedOverriding("Use setFailureReporter instead", "3.6.0")
   protected def reportFailure(err: Throwable): IO[Unit] =
-    Console[IO].printStackTrace(err)
+    IO(_failureReporter).flatMap(_.apply(err))
+
+  /**
+   * Configures the action to perform when unhandled errors are caught by the runtime.
+   *
+   * An unhandled error is an error that is raised (and not handled) on a Fiber that nobody is
+   * joining.
+   *
+   * For example:
+   *
+   * {{{
+   *   import scala.concurrent.duration._
+   *   override def run: IO[Unit] = IO(throw new Exception("")).start *> IO.sleep(1.second)
+   * }}}
+   *
+   * In this case, the exception is raised on a Fiber with no listeners. Nobody would be
+   * notified about that error. Therefore it is unhandled, and it goes through the reportFailure
+   * mechanism.
+   *
+   * By default, the runtime simply delegates to [[cats.effect.std.Console!.printStackTrace]].
+   * It is safe to perform any `IO` action within this handler; it will not block the progress
+   * of the runtime. With that said, some care should be taken to avoid raising unhandled errors
+   * as a result of handling unhandled errors, since that will result in the obvious chaos.
+   */
+  protected final def setFailureReporter(
+      reporter: Throwable => IO[Unit]
+  ): IO[Unit] =
+    IO {
+      _failureReporter = reporter
+    }
 
   /**
    * Defines what to do when CpuStarvationCheck is triggered. Defaults to log a warning to
    * System.err.
    */
+  @deprecatedOverriding("Use setOnCpuStarvationReporter instead", "3.6.0")
   protected def onCpuStarvationWarn(metrics: CpuStarvationWarningMetrics): IO[Unit] =
-    CpuStarvationCheck.logWarning(metrics)
+    IO(_onCpuStarvationReporter).flatMap(_.apply(metrics))
+
+  /**
+   * Configures what to do when CpuStarvationCheck is triggered. By default the runtime logs a
+   * warning to System.err.
+   */
+  protected final def setOnCpuStarvationReporter(
+      reporter: CpuStarvationWarningMetrics => IO[Unit]
+  ): IO[Unit] =
+    IO {
+      _onCpuStarvationReporter = reporter
+    }
 
   /**
    * The entry point for your application. Will be called by the runtime when the process is

core/jvm/src/main/scala/cats/effect/IOApp.scala

@@ -17,7 +17,6 @@
 package cats.effect
 
 import cats.effect.metrics.{CpuStarvationWarningMetrics, JvmCpuStarvationMetrics}
-import cats.effect.std.Console
 import cats.effect.tracing.TracingConstants._
 import cats.syntax.all._
 
@@ -144,6 +143,14 @@ trait IOApp {
 
   private[this] var _runtime: unsafe.IORuntime = null
 
+  @volatile
+  private[this] var _failureReporter: Throwable => IO[Unit] =
+    err => IO.consoleForIO.printStackTrace(err)
+
+  @volatile
+  private[this] var _onCpuStarvationReporter: CpuStarvationWarningMetrics => IO[Unit] =
+    metrics => CpuStarvationCheck.logWarning(metrics)
+
   /**
    * The runtime which will be used by `IOApp` to evaluate the [[IO]] produced by the `run`
    * method. This may be overridden by `IOApp` implementations which have extremely specialized
@@ -233,7 +240,7 @@ trait IOApp {
       )
 
   /**
-   * Configures the action to perform when unhandled errors are caught by the runtime. An
+   * Configures the action to perform when unhandled errors are caught by the runtime.An
    * unhandled error is an error that is raised (and not handled) on a Fiber that nobody is
    * joining.
    *
@@ -254,8 +261,38 @@ trait IOApp {
    * should be taken to avoid raising unhandled errors as a result of handling unhandled errors,
    * since that will result in the obvious chaos.
    */
+  @deprecatedOverriding("Use setFailureReporter instead", "3.6.0")
   protected def reportFailure(err: Throwable): IO[Unit] =
-    Console[IO].printStackTrace(err)
+    IO(_failureReporter).flatMap(_.apply(err))
+
+  /**
+   * Configures the action to perform when unhandled errors are caught by the runtime.
+   *
+   * An unhandled error is an error that is raised (and not handled) on a Fiber that nobody is
+   * joining.
+   *
+   * For example:
+   *
+   * {{{
+   *   import scala.concurrent.duration._
+   *   override def run: IO[Unit] = IO(throw new Exception("")).start *> IO.sleep(1.second)
+   * }}}
+   *
+   * In this case, the exception is raised on a Fiber with no listeners. Nobody would be
+   * notified about that error. Therefore it is unhandled, and it goes through the reportFailure
+   * mechanism.
+   *
+   * By default, the runtime simply delegates to [[cats.effect.std.Console!.printStackTrace]].
+   * It is safe to perform any `IO` action within this handler; it will not block the progress
+   * of the runtime. With that said, some care should be taken to avoid raising unhandled errors
+   * as a result of handling unhandled errors, since that will result in the obvious chaos.
+   */
+  protected final def setFailureReporter(
+      reporter: Throwable => IO[Unit]
+  ): IO[Unit] =
+    IO {
+      _failureReporter = reporter
+    }
 
   /**
    * Configures whether to enable blocked thread detection. This is relatively expensive so is
@@ -329,8 +366,20 @@ trait IOApp {
    * Defines what to do when CpuStarvationCheck is triggered. Defaults to log a warning to
    * System.err.
    */
+  @deprecatedOverriding("Use setOnCpuStarvationReporter instead", "3.6.0")
   protected def onCpuStarvationWarn(metrics: CpuStarvationWarningMetrics): IO[Unit] =
-    CpuStarvationCheck.logWarning(metrics)
+    IO(_onCpuStarvationReporter).flatMap(_.apply(metrics))
+
+  /**
+   * Configures what to do when CpuStarvationCheck is triggered. By default the runtime logs a
+   * warning to System.err.
+   */
+  protected final def setOnCpuStarvationReporter(
+      reporter: CpuStarvationWarningMetrics => IO[Unit]
+  ): IO[Unit] =
+    IO {
+      _onCpuStarvationReporter = reporter
+    }
 
   /**
    * Defines what to do when IOApp detects that `main` is being invoked on a `Thread` which

core/native/src/main/scala/cats/effect/IOApp.scala

@@ -146,6 +146,14 @@ trait IOApp {
 
   private[this] var _runtime: unsafe.IORuntime = null
 
+  @volatile
+  private[this] var _failureReporter: Throwable => IO[Unit] =
+    err => IO.consoleForIO.printStackTrace(err)
+
+  @volatile
+  private[this] var _onCpuStarvationReporter: CpuStarvationWarningMetrics => IO[Unit] =
+    metrics => CpuStarvationCheck.logWarning(metrics)
+
   /**
    * The runtime which will be used by `IOApp` to evaluate the [[IO]] produced by the `run`
    * method. This may be overridden by `IOApp` implementations which have extremely specialized
@@ -167,12 +175,57 @@ trait IOApp {
    */
   protected def runtimeConfig: unsafe.IORuntimeConfig = unsafe.IORuntimeConfig()
 
+  // Currently unused!
+  private def reportFailure(err: Throwable): IO[Unit] =
+    IO(_failureReporter).flatMap(_.apply(err))
+
+  /**
+   * Configures the action to perform when unhandled errors are caught by the runtime.
+   *
+   * An unhandled error is an error that is raised (and not handled) on a Fiber that nobody is
+   * joining.
+   *
+   * For example:
+   *
+   * {{{
+   *   import scala.concurrent.duration._
+   *   override def run: IO[Unit] = IO(throw new Exception("")).start *> IO.sleep(1.second)
+   * }}}
+   *
+   * In this case, the exception is raised on a Fiber with no listeners. Nobody would be
+   * notified about that error. Therefore it is unhandled, and it goes through the reportFailure
+   * mechanism.
+   *
+   * By default, the runtime simply delegates to [[cats.effect.std.Console!.printStackTrace]].
+   * It is safe to perform any `IO` action within this handler; it will not block the progress
+   * of the runtime. With that said, some care should be taken to avoid raising unhandled errors
+   * as a result of handling unhandled errors, since that will result in the obvious chaos.
+   */
+  protected final def setFailureReporter(
+      reporter: Throwable => IO[Unit]
+  ): IO[Unit] =
+    IO {
+      _failureReporter = reporter
+    }
+
   /**
    * Defines what to do when CpuStarvationCheck is triggered. Defaults to log a warning to
    * System.err.
    */
+  @deprecatedOverriding("Use setOnCpuStarvationReporter instead", "3.6.0")
   protected def onCpuStarvationWarn(metrics: CpuStarvationWarningMetrics): IO[Unit] =
-    CpuStarvationCheck.logWarning(metrics)
+    IO(_onCpuStarvationReporter).flatMap(_.apply(metrics))
+
+  /**
+   * Configures what to do when CpuStarvationCheck is triggered. By default the runtime logs a
+   * warning to System.err.
+   */
+  protected final def setOnCpuStarvationReporter(
+      reporter: CpuStarvationWarningMetrics => IO[Unit]
+  ): IO[Unit] =
+    IO {
+      _onCpuStarvationReporter = reporter
+    }
 
   /**
    * The [[unsafe.PollingSystem]] used by the [[runtime]] which will evaluate the [[IO]]