Scope with Regular Job

What is a “Scope with Regular Job”?

A Scope with Regular Job in Kotlin coroutines refers to any CoroutineScope that uses Job() and hence abides by default exception handling behavior - where uncaught non-cancellation exceptions in child coroutine Cancels (shutsdown) its entire hierarchy of co-routines.

Default Exception Behavior

Exception/Cancellation Behavior with Regular Job

In ALL scopes that use Regular:

• Uncaught, non-cancellation exception → Cancels Siblings + Propagates recursively through parent Job hierarchy, with each parent shutting down its children, Effectively shutting down the entire hierarchy up to the top most Job (or up to where you caught exception at error boundary).
  • Cancels siblings: functions-suspension-point in sibling functions will throw CancellationException
  • Propagates to parent: Parent scope will rethrow the original exception that was thrown in co-routine.

Highlight

Job - provide another avenue of stopping work other than traditional exceptions. Separate cancellation mechanism that is not as apparent as typical exception flow, where failed co-routine cancel’s all co-routines that are related to it through Job hierarchy.

• Each coroutine has its own Job instance.
• Each Job instance is tied to it’s parent job (if it has a parent Job). This tie in enables cancellation behavior.

Example

If regular Job() were used. If Coroutine#6 throws non-CancellationException exception the entire hierarchy is gonig to be cancelled and Coroutine#1 will rethrow the exception that Coroutine#6 threw.

{max-width: 500px, display: block, margin: 0 auto, border: 5px solid black}

Creating Error Boundary

• Look at scope-function-error-boundary to create error/ boundaries which allows us to try/catch exceptions stopping them from going higher up.

Gotchas

Cancellation Gotchas (With Regular Job)

• ⚠️ Firstly, make sure to understand intended ExceptionCancellationBehavior ⚠️.
• evil-example-swallowing-cancel-exception
• exceptions-from-async-under-coroutineScope-go-to-parent-and-not-await
• cancel-call-does-not-stop-right-away
• join

Link to original

Link to original

Code example

Scope examples with Regular Job

Core examples with regular Job

structured-parallelization

manually-with-scope with child parallelization launched co-routines

Here we manually setup scope and wait on it for launched actions to finish - a bit cumbersome but works.

Code

package com.glassthought.sandbox
 
import gt.sandbox.util.output.Out
import kotlinx.coroutines.*
import kotlin.coroutines.coroutineContext
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.seconds
 
private val out = Out.standard()
 
fun main(): Unit = runBlocking {
  out.info("START - ON MAIN")
 
  try {
    mainImpl(out)
  } catch (e: Exception) {
    out.error("back at MAIN got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - WITHOUT errors on MAIN")
}
 
private suspend fun mainImpl(out: Out) {
  coroutineScope {
    foo("msg-1")
  }
}
 
private suspend fun foo(msg: String) {
  out.actionWithMsg("fooImpl", { fooImpl(msg) })
}
 
private suspend fun fooImpl(msg: String) {
  val job = Job()
  val scope = CoroutineScope(coroutineContext + job)
 
  scope.launch {
    out.delayNamed(3.seconds, "delayed([${msg}])")
  }
  scope.launch {
    out.delayNamed(2.seconds, "delayed([${msg}])")
  }
  scope.launch {
    out.delayNamed(1.seconds, "delayed([${msg}])")
  }
 
  out.actionWithMsg("job.complete()", { job.complete() })
  out.actionWithMsg("job.join()", { job.join() })
}

Command to reproduce:

gt.sandbox.checkout.commit 800315e25e0cc39077c2 \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   37ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] START - ON MAIN
[INFO][elapsed:   52ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [>] Starting action=[fooImpl] 
[INFO][elapsed:   54ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    [>] Starting action=[job.complete()] 
[INFO][elapsed:   55ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    [<] Finished action=[job.complete()].
[INFO][elapsed:   55ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    [>] Starting action=[job.join()] 
[INFO][elapsed:   59ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] Delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed:   60ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] Delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed:   61ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Delaying for 1s what_for=[delayed([msg-1])]
[INFO][elapsed: 1062ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Done delaying for 1s what_for=[delayed([msg-1])]
[INFO][elapsed: 2061ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] Done delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed: 3060ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] Done delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed: 3061ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    [<] Finished action=[job.join()].
[INFO][elapsed: 3061ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [<] Finished action=[fooImpl].
[INFO][elapsed: 3061ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] DONE - WITHOUT errors on MAIN

Link to original

Instead of manually setting up scope and waiting on it we can use coroutineScope

coroutineScope-happy-case

Here we use coroutineScope with 3 parallel children, coroutineScope will auto wait for them to finish.

Code

package com.glassthought.sandbox
 
import gt.sandbox.util.output.Out
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.seconds
 
private val out = Out.standard()
private suspend fun mainImpl(out: Out) {
  coroutineScope {
    foo("msg-1")
  }
}
 
private suspend fun foo(msg: String) {
  out.actionWithMsg("fooImpl", { fooImpl(msg) })
}
 
private suspend fun fooImpl(msg: String) {
  coroutineScope {
    launch {
      out.delayNamed(3.seconds, "delayed([${msg}])")
    }
    launch {
      out.delayNamed(2.seconds, "delayed([${msg}])")
    }
    launch {
      out.delayNamed(1.seconds, "delayed([${msg}])")
    }
  }
}
 
 
fun main(): Unit = runBlocking {
  out.info("START - ON MAIN")
 
  try {
    mainImpl(out)
  } catch (e: Exception) {
    out.error("back at MAIN got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - WITHOUT errors on MAIN")
}

Command to reproduce:

gt.sandbox.checkout.commit e09d077f5c59925b2881 \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   39ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] START - ON MAIN
[INFO][elapsed:   54ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [>] Starting action=[fooImpl] 
[INFO][elapsed:   60ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] Delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed:   62ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] Delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed:   62ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Delaying for 1s what_for=[delayed([msg-1])]
[INFO][elapsed: 1064ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Done delaying for 1s what_for=[delayed([msg-1])]
[INFO][elapsed: 2062ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] Done delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed: 3061ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] Done delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed: 3062ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [<] Finished action=[fooImpl].
[INFO][elapsed: 3062ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] DONE - WITHOUT errors on MAIN

Link to original

Next let’s see how the cancellations are handled, we expect any single failure to cancel all others.

throw-exception-in-one-which-cancels-others

Throw exception in one child co-routine which cancels others (as well as cancels parent)

Code

package com.glassthought.sandbox
 
import gt.sandbox.util.output.Out
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds
 
private val out = Out.standard()
private suspend fun mainImpl(out: Out) {
  coroutineScope {
    foo("msg-1")
  }
}
 
private suspend fun foo(msg: String) {
  out.actionWithMsg("fooImpl", { fooImpl(msg) })
}
 
private suspend fun fooImpl(msg: String) {
  coroutineScope {
    launch {
      out.delayNamed(3.seconds, "delayed([${msg}])")
    }
    launch {
      out.delayNamed(2.seconds, "delayed([${msg}])")
    }
    launch {
      out.delayNamed(1.seconds, "delayed([${msg}])")
      out.actionWithMsg(
        "throw-exception",
        { throw MyRuntimeException.create("from-launch-with-1sec-delay", out) })
 
    }
  }
}
 
 
fun main(): Unit = runBlocking {
  out.info("START - ON MAIN")
 
  try {
    mainImpl(out)
  } catch (e: Exception) {
    out.error("back at MAIN got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - WITHOUT errors on MAIN")
}

Command to reproduce:

gt.sandbox.checkout.commit 115eb01d02706b26722e \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   38ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] START - ON MAIN
[INFO][elapsed:   53ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [>] Starting action=[fooImpl] 
[INFO][elapsed:   58ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] Delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed:   61ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] Delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed:   61ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Delaying for 1s what_for=[delayed([msg-1])]
[INFO][elapsed: 1062ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Done delaying for 1s what_for=[delayed([msg-1])]
[INFO][elapsed: 1063ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] [>] Starting action=[throw-exception] 
[WARN][elapsed: 1102ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1]    💥 throwing exception=[MyRuntimeException] with msg=[from-launch-with-1sec-delay]
[WARN][elapsed: 1102ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] [<][💥] Finished action=[throw-exception], threw exception of type=[MyRuntimeException].
[WARN][elapsed: 1123ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] 🫡 I have caught [JobCancellationException/Parent job is Cancelling], and rethrowing it 🫡
[WARN][elapsed: 1124ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] 🫡 I have caught [JobCancellationException/Parent job is Cancelling], and rethrowing it 🫡
[WARN][elapsed: 1124ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [<][💥] Finished action=[fooImpl], threw exception of type=[MyRuntimeException].
[ERROR][elapsed: 1125ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] back at MAIN got an exception! of type=[MyRuntimeException] with msg=[from-launch-with-1sec-delay] cause=[null]. Exiting with error code 1
 
FAILURE: Build failed with an exception.
 
* What went wrong:
Execution failed for task ':app:run'.
> Process 'command '/home/nickolaykondratyev/.jdks/corretto-21.0.7/bin/java'' finished with non-zero exit value 1
 
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.
 
BUILD FAILED in 1s

Link to original

Now let’s have one of co-routines cancel itself, which should not disturb other co-routines.

throw-cancellation-exception

One child throws cancellation exception which just cancels itself, allowing other SIBLING co-routines to finish processing without issues. Parent also finishes successfully in this case.

Related

• CancellationException

Code

package com.glassthought.sandbox
 
import gt.sandbox.util.output.Out
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds
 
private val out = Out.standard()
private suspend fun mainImpl(out: Out) {
  coroutineScope {
    foo("msg-1")
  }
}
 
private suspend fun foo(msg: String) {
  out.actionWithMsg("fooImpl", { fooImpl(msg) })
}
 
private suspend fun fooImpl(msg: String) {
  coroutineScope {
    launch {
      out.delayNamed(3.seconds, "delayed([${msg}])")
    }
    launch {
      out.delayNamed(2.seconds, "delayed([${msg}])")
    }
    launch {
      out.delayNamed(1.seconds, "delayed([${msg}])")
      out.info("Throwing cancellation exception")
      throw CancellationException("cancelled-1")
    }
  }
}
 
 
fun main(): Unit = runBlocking {
  out.info("START - ON MAIN")
 
  try {
    mainImpl(out)
  } catch (e: Exception) {
    out.error("back at MAIN got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - WITHOUT errors on MAIN")
}

Command to reproduce:

gt.sandbox.checkout.commit a9eae6cf8babc917214c \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   39ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] START - ON MAIN
[INFO][elapsed:   55ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [>] Starting action=[fooImpl] 
[INFO][elapsed:   59ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] Delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed:   62ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] Delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed:   62ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Delaying for 1s what_for=[delayed([msg-1])]
[INFO][elapsed: 1063ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Done delaying for 1s what_for=[delayed([msg-1])]
[INFO][elapsed: 1063ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Throwing cancellation exception
[INFO][elapsed: 2063ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] Done delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed: 3061ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] Done delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed: 3062ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [>] Finished action=[fooImpl].
[INFO][elapsed: 3062ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] DONE - WITHOUT errors on MAIN

Link to original

With await:

happy-case

happy case we spawn 3 child awaits and get their results.

Code

package com.glassthought.sandbox
 
import gt.sandbox.util.output.Out
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.async
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds
 
private val out = Out.standard()
private suspend fun mainImpl(out: Out) {
  coroutineScope {
    foo("msg-1")
  }
}
 
private suspend fun foo(msg: String) {
  out.actionWithMsg("fooImpl", { fooImpl(msg) })
}
 
private suspend fun fooImpl(msg: String) {
  coroutineScope {
    val deferred3 = async {
      out.delayNamed(3.seconds, "delayed([${msg}])")
 
      "res-3"
    }
    val deferred2 = async {
      out.delayNamed(2.seconds, "delayed([${msg}])")
 
      "res-2"
    }
    val deferred1 = async {
      out.delayNamed(1.seconds, "delayed([${msg}])")
 
      "res-1"
    }
    out.info("Just launched co-routines")
 
    out.info("deferred-1.result=" + deferred1.await())
    out.info("deferred-2.result=" + deferred2.await())
    out.info("deferred-3.result=" + deferred3.await())
  }
}
 
fun main(): Unit = runBlocking {
  out.info("START - ON MAIN")
 
  try {
    mainImpl(out)
  } catch (e: Exception) {
    out.error("back at MAIN got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - WITHOUT errors on MAIN")
}

Command to reproduce:

gt.sandbox.checkout.commit fedf1c8aed4a6059c3ee \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   37ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] START - ON MAIN
[INFO][elapsed:   52ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [>] Starting action=[fooImpl] 
[INFO][elapsed:   54ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    Just launched co-routines
[INFO][elapsed:   58ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] Delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed:   59ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] Delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed:   59ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Delaying for 1s what_for=[delayed([msg-1])]
[INFO][elapsed: 1061ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Done delaying for 1s what_for=[delayed([msg-1])]
[INFO][elapsed: 1062ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    deferred-1.result=res-1
[INFO][elapsed: 2060ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] Done delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed: 2060ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    deferred-2.result=res-2
[INFO][elapsed: 3059ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] Done delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed: 3059ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    deferred-3.result=res-3
[INFO][elapsed: 3060ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [>] Finished action=[fooImpl].
[INFO][elapsed: 3060ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] DONE - WITHOUT errors on MAIN

Link to original

⚠️ Unhandled exception from async can go to parent scope without going through await() ⚠️

Uncaught exception behavior with async:

• IF await() is called before the async coroutine fails.
  • THEN: the exception goes through await()
• IF the async coroutine fails before await() is called.
  • THEN: the exception propagates up the Job hierarchy immediately.

As we would expect example: exception goes through await()

Here we observe await() receiving exception

Code

package com.glassthought.sandbox
 
import com.glassthought.sandbox.util.out.impl.out
import gt.sandbox.util.output.Emojis
import gt.sandbox.util.output.Out
import kotlinx.coroutines.async
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds
 
private suspend fun mainImpl(out: Out) {
  coroutineScope {
    foo("msg-1")
  }
}
 
private suspend fun foo(msg: String) {
  out.actionWithMsg("fooImpl", { fooImpl(msg) })
}
 
private suspend fun fooImpl(msg: String) {
  coroutineScope {
    launch {
      out.delayNamed(3.seconds, "delayed([${msg}])")
    }
    launch {
      out.delayNamed(2.seconds, "delayed([${msg}])")
    }
    val deferred = async {
      out.delayNamed(500.milliseconds, "delayed([${msg}])")
 
      throw MyRuntimeException.create("exception-from-async", out)
    }
    out.info("Just launched co-routines. Going into deferred.await()")
 
    // This code is unreachable since async exception will go to the parent instead of
    // going to the await()
    try {
      deferred.await()
    } catch (e: Exception) {
      out.error("[RETHROWING][${Emojis.CAUGHT_EXCEPTION}] Caught exception on [deferred.await()] from async: ${e.message} of type [${e::class.simpleName}]")
 
      throw e
    }
  }
}
 
 
fun main(): Unit = runBlocking {
  out.info("START - ON MAIN")
 
  try {
    mainImpl(out)
  } catch (e: Exception) {
    out.error("back at MAIN got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - WITHOUT errors on MAIN")
}

Command to reproduce:

gt.sandbox.checkout.commit fa1ebcc936a485d23912 \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   15ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] START - ON MAIN
[INFO][elapsed:   31ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [>] Starting action=[fooImpl] 
[INFO][elapsed:   34ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    Just launched co-routines. Going into deferred.await()
[INFO][elapsed:   38ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] Delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed:   39ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] Delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed:   39ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Delaying for 500ms what_for=[delayed([msg-1])]
[INFO][elapsed:  541ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Done delaying for 500ms what_for=[delayed([msg-1])]
[WARN][elapsed:  571ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] 💥 throwing exception=[MyRuntimeException] with msg=[exception-from-async]
[WARN][elapsed:  591ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] 🫡 I have caught [JobCancellationException/Parent job is Cancelling], and rethrowing it 🫡
[WARN][elapsed:  592ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] 🫡 I have caught [JobCancellationException/Parent job is Cancelling], and rethrowing it 🫡
[ERROR][elapsed:  593ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    [RETHROWING][� Caught exception on [deferred.await()] from async: exception-from-async of type [MyRuntimeException]
[WARN][elapsed:  593ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [<][💥] Finished action=[fooImpl], threw exception of type=[MyRuntimeException].
[ERROR][elapsed:  594ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] back at MAIN got an exception! of type=[MyRuntimeException] with msg=[exception-from-async] cause=[null]. Exiting with error code 1
 
FAILURE: Build failed with an exception.
 
* What went wrong:
Execution failed for task ':app:run'.
> Process 'command '/home/nickolaykondratyev/.jdks/corretto-21.0.7/bin/java'' finished with non-zero exit value 1
 
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.
 
BUILD FAILED in 1s

Newer behavior: exception propagates through Job link to parent scope WITHOUT going through await()

⚠️ Here we add delay() such that exception is thrown from async BEFORE we call await() on deferred object.
Result: Exception goes directly to parent scope without going through await(). This cancels any other co-routines on scope with regular Job(). ⚠️

Code

package com.glassthought.sandbox
 
import com.glassthought.sandbox.util.out.impl.out
import gt.sandbox.util.output.Emojis
import gt.sandbox.util.output.Out
import kotlinx.coroutines.CoroutineName
import kotlinx.coroutines.async
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds
 
private suspend fun mainImpl(out: Out) {
  coroutineScope {
    foo("msg-1")
  }
}
 
private suspend fun foo(msg: String) {
  out.actionWithMsg("fooImpl", { fooImpl(msg) })
}
 
private suspend fun fooImpl(msg: String) {
  coroutineScope {
    launch(CoroutineName("IJustDelay-3Sec-AndPrint")) {
      out.delayNamed(3.seconds, "delayed([${msg}])")
    }
    launch(CoroutineName("IJustDelay-2Sec-AndPrint")) {
      out.delayNamed(2.seconds, "delayed([${msg}])")
    }
    val deferred = async(CoroutineName("IAmGoingToThrow")) {
      out.delayNamed(500.milliseconds, "delayed([${msg}])")
 
      throw MyRuntimeException.create("exception-from-async", out)
    }
    out.info("Just launched co-routines.")
 
    out.delayNamed(1.seconds, "Going into DELAY before calling [deferred.await()]")
 
    // This code is unreachable since async exception will go to the parent instead of
    // going to the await()
    try {
      out.info("About to call [deferred.await()] (WE ARE NEVER GOING TO REACH THIS LINE)")
      deferred.await()
    } catch (e: Exception) {
      out.error("[RETHROWING][${Emojis.CAUGHT_EXCEPTION}] Caught exception on [deferred.await()] from async: ${e.message} of type [${e::class.simpleName}]")
 
      throw e
    }
  }
}
 
 
fun main(): Unit = runBlocking(CoroutineName("RunBlocking-At-Main")) {
  out.info("START - ON MAIN")
 
  try {
    mainImpl(out)
  } catch (e: Exception) {
    out.error("back at MAIN got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - WITHOUT errors on MAIN")
}

Command to reproduce:

gt.sandbox.checkout.commit 172df689c3cb592bc3eb \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   15ms][🥇][①][coroutname:@RunBlocking-At-Main#1][tname:main/tid:1] START - ON MAIN
[INFO][elapsed:   32ms][🥇][①][coroutname:@RunBlocking-At-Main#1][tname:main/tid:1] [>] Starting action=[fooImpl] 
[INFO][elapsed:   35ms][🥇][①][coroutname:@RunBlocking-At-Main#1][tname:main/tid:1]    Just launched co-routines.
[INFO][elapsed:   36ms][🥇][①][coroutname:@RunBlocking-At-Main#1][tname:main/tid:1]    Delaying for 1s what_for=[Going into DELAY before calling [deferred.await()]]
[INFO][elapsed:   39ms][🥇][⓶][coroutname:@IJustDelay-3Sec-AndPrint#2][tname:main/tid:1] Delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed:   39ms][🥇][⓷][coroutname:@IJustDelay-2Sec-AndPrint#3][tname:main/tid:1] Delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed:   40ms][🥇][⓸][coroutname:@IAmGoingToThrow#4][tname:main/tid:1] Delaying for 500ms what_for=[delayed([msg-1])]
[INFO][elapsed:  541ms][🥇][⓸][coroutname:@IAmGoingToThrow#4][tname:main/tid:1] Done delaying for 500ms what_for=[delayed([msg-1])]
[WARN][elapsed:  572ms][🥇][⓸][coroutname:@IAmGoingToThrow#4][tname:main/tid:1] 💥 throwing exception=[MyRuntimeException] with msg=[exception-from-async]
[WARN][elapsed:  591ms][🥇][⓶][coroutname:@IJustDelay-3Sec-AndPrint#2][tname:main/tid:1] 🫡 I have caught [JobCancellationException/Parent job is Cancelling], and rethrowing it 🫡
[WARN][elapsed:  592ms][🥇][⓷][coroutname:@IJustDelay-2Sec-AndPrint#3][tname:main/tid:1] 🫡 I have caught [JobCancellationException/Parent job is Cancelling], and rethrowing it 🫡
[WARN][elapsed:  593ms][🥇][①][coroutname:@RunBlocking-At-Main#1][tname:main/tid:1]    🫡 I have caught [JobCancellationException/ScopeCoroutine is cancelling], and rethrowing it 🫡
[WARN][elapsed:  594ms][🥇][①][coroutname:@RunBlocking-At-Main#1][tname:main/tid:1] [<][💥] Finished action=[fooImpl], threw exception of type=[MyRuntimeException].
[ERROR][elapsed:  594ms][🥇][①][coroutname:@RunBlocking-At-Main#1][tname:main/tid:1] back at MAIN got an exception! of type=[MyRuntimeException] with msg=[exception-from-async] cause=[null]. Exiting with error code 1
 
FAILURE: Build failed with an exception.
 
* What went wrong:
Execution failed for task ':app:run'.
> Process 'command '/home/nickolaykondratyev/.jdks/corretto-21.0.7/bin/java'' finished with non-zero exit value 1
 
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.
 
BUILD FAILED in 1s

Link to original

Cancellation of Parent Example

cancel-parent-cancel-children

Here we cancel the parent scope and that automatically cancels children.

Code

package com.glassthought.sandbox
 
import gt.sandbox.util.output.Out
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.async
import kotlinx.coroutines.cancel
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds
 
private val out = Out.standard()
private suspend fun mainImpl(out: Out) {
  coroutineScope {
    foo("msg-1")
  }
}
 
private suspend fun foo(msg: String) {
  out.actionWithMsg("fooImpl", { fooImpl(msg) })
}
 
private suspend fun fooImpl(msg: String) {
  coroutineScope {
    val deferred3 = async {
      out.delayNamed(3.seconds, "delayed([${msg}])")
 
      "res-3"
    }
    val deferred2 = async {
      out.delayNamed(2.seconds, "delayed([${msg}])")
 
      "res-2"
    }
    val deferred1 = async {
      out.delayNamed(1.seconds, "delayed([${msg}])")
 
      "res-1"
    }
 
 
    out.info("Just launched co-routines")
    out.delayNamed(500.milliseconds, "delay before scope cancel")
    this.cancel()
 
    out.info("deferred-1.result=" + deferred1.await())
    out.info("deferred-2.result=" + deferred2.await())
    out.info("deferred-3.result=" + deferred3.await())
  }
 
}
 
fun main(): Unit = runBlocking {
  out.info("START - ON MAIN")
 
  try {
    mainImpl(out)
  } catch (e: Exception) {
    out.error("back at MAIN got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - WITHOUT errors on MAIN")
}

Command to reproduce:

gt.sandbox.checkout.commit a2df237045869c0a8e1b \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   39ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] START - ON MAIN
[INFO][elapsed:   56ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [>] Starting action=[fooImpl] 
[INFO][elapsed:   58ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    Just launched co-routines
[INFO][elapsed:   60ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    Delaying for 500ms what_for=[delay before scope cancel]
[INFO][elapsed:   63ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] Delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed:   63ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] Delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed:   63ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Delaying for 1s what_for=[delayed([msg-1])]
[INFO][elapsed:  562ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    Done delaying for 500ms what_for=[delay before scope cancel]
[WARN][elapsed:  615ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] 🫡 I have caught [JobCancellationException/ScopeCoroutine was cancelled], and rethrowing it 🫡
[WARN][elapsed:  615ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] 🫡 I have caught [JobCancellationException/ScopeCoroutine was cancelled], and rethrowing it 🫡
[WARN][elapsed:  616ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] 🫡 I have caught [JobCancellationException/ScopeCoroutine was cancelled], and rethrowing it 🫡
[INFO][elapsed:  616ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [>][🫡] Cancellation Exception - rethrowing.
[ERROR][elapsed:  617ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] back at MAIN got an exception! of type=[JobCancellationException] with msg=[ScopeCoroutine was cancelled] cause=[kotlinx.coroutines.JobCancellationException: ScopeCoroutine was cancelled; job="coroutine#1":ScopeCoroutine{Cancelled}@768b970c]. Exiting with error code 1
 
FAILURE: Build failed with an exception.
 
* What went wrong:
Execution failed for task ':app:run'.
> Process 'command '/home/nickolaykondratyev/.jdks/corretto-21.0.7/bin/java'' finished with non-zero exit value 1
 
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.
 
BUILD FAILED in 1s

Link to original

Link to original

run-blocking-examples

• basic-log-and-rethrow

• evil-example-swallowing-cancel-exception

Link to original

custom-scope-with-async

custom scope - with await - exception from the co-routine will be rethrown parent when we await, BUT siblings are cancelled RIGHT away when uncaught exception happens.

Code

package com.glassthought.sandbox
 
import gt.sandbox.util.output.Emojis
import gt.sandbox.util.output.Out
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.CoroutineName
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.async
import kotlinx.coroutines.delay
import kotlinx.coroutines.isActive
import kotlinx.coroutines.runBlocking
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.seconds
 
fun main(): kotlin.Unit = runBlocking {
  val out = Out.standard()
  out.info("START")
 
  try {
    val myScope = CoroutineScope(
      Dispatchers.Default
    )
 
    val coRoutine1Deferred = myScope.async(
      CoroutineName("WillFail")
    ) {
      val timeMillis = 1000L
      out.info("This one will throw in $timeMillis ms")
      delay(timeMillis)
      val exc = MyExceptionWillThrowFromCoroutine("I-Failed-In-CoRoutine")
      out.warn("${Emojis.EXCEPTOIN} I am throwing [${exc::class.simpleName}/${exc.message}]! ${Emojis.EXCEPTOIN}")
      throw exc
 
      "ResultFromWillFail"
    }
 
    val coRoutine2Deferred = myScope.async(CoroutineName("JustPrints")) {
      (0..10)
        .map { "a-${it}" }
        .forEach {
          out.info(it)
 
          try {
            delay(500)
          } catch (e: CancellationException) {
            val excMsg = e.message ?: e.toString()
            out.warn("${Emojis.OBIDIENT} I have caught [${e::class.simpleName}/$excMsg], and rethrowing it ${Emojis.OBIDIENT} ")
 
            throw e
          }
        }
    }
 
    out.actionWithMsg(
      actionThatWeAreDelayingFor = "coRoutine1Deferred.join()",
      action = {
        coRoutine1Deferred.join()
      }
    )
    out.infoPrintState(coRoutine1Deferred, "coRoutine1Deferred")
    out.info("myScope.isActive = ${myScope.isActive}")
 
    out.delayedActionWithMsg(
      actionThatWeAreDelayingFor = "coRoutine1Deferred.await()",
      delayBeforeAction = 2.seconds,
      action = {
        out.info("coRoutine1Deferred.await()=[${coRoutine1Deferred.await()}]")
      }
    )
 
    out.delayedActionWithMsg(
      actionThatWeAreDelayingFor = "coRoutine2Deferred.await()",
      delayBeforeAction = 2.seconds,
      action = {
        out.info("coRoutine1Deferred.await()=[${coRoutine2Deferred.await()}]")
      }
    )
  } catch (e: Exception) {
    out.error("in main got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - without errors on main")
}
 
class MyExceptionWillThrowFromCoroutine(msg: String) : RuntimeException(msg)

Command to reproduce:

gt.sandbox.checkout.commit 17ff993a20b91dfff9ea \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   14ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] START
[INFO][elapsed:   33ms][2️⃣][⓶][coroutname:@WillFail#2][tname:DefaultDispatcher-worker-1/tid:31] This one will throw in 1000 ms
[INFO][elapsed:   35ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Performing action=[coRoutine1Deferred.join()]
[INFO][elapsed:   37ms][3️⃣][⓷][coroutname:@JustPrints#3][tname:DefaultDispatcher-worker-2/tid:32] a-0
[INFO][elapsed:  538ms][3️⃣][⓷][coroutname:@JustPrints#3][tname:DefaultDispatcher-worker-2/tid:32] a-1
[INFO][elapsed: 1039ms][2️⃣][⓷][coroutname:@JustPrints#3][tname:DefaultDispatcher-worker-1/tid:31] a-2
[WARN][elapsed: 1068ms][3️⃣][⓶][coroutname:@WillFail#2][tname:DefaultDispatcher-worker-2/tid:32] 💥  I am throwing [MyExceptionWillThrowFromCoroutine/I-Failed-In-CoRoutine]! 💥 
[INFO][elapsed: 1070ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Performed action=[coRoutine1Deferred.join()]
[INFO][elapsed: 1073ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] State of [coRoutine1Deferred]:
coRoutine1Deferred.isActive    | false
coRoutine1Deferred.isCancelled | true
coRoutine1Deferred.isCompleted | true
 
[INFO][elapsed: 1073ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] myScope.isActive = false
[INFO][elapsed: 1076ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] 2s delay, before_action=[coRoutine1Deferred.await()]
[WARN][elapsed: 1083ms][2️⃣][⓷][coroutname:@JustPrints#3][tname:DefaultDispatcher-worker-1/tid:31] 🫡 I have caught [JobCancellationException/Parent job is Cancelling], and rethrowing it 🫡 
[INFO][elapsed: 3077ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Done with=2s delay performing action=[coRoutine1Deferred.await()]
[ERROR][elapsed: 3079ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] in main got an exception! of type=[MyExceptionWillThrowFromCoroutine] with msg=[I-Failed-In-CoRoutine] cause=[com.glassthought.sandbox.MyExceptionWillThrowFromCoroutine: I-Failed-In-CoRoutine]. Exiting with error code 1
 
FAILURE: Build failed with an exception.
 
* What went wrong:
Execution failed for task ':app:run'.
> Process 'command '/home/nickolaykondratyev/.jdks/corretto-21.0.7/bin/java'' finished with non-zero exit value 1
 
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.
 
BUILD FAILED in 3s

Also see:

⚠️ Unhandled exception from async can go to parent scope without going through await() ⚠️

Uncaught exception behavior with async:

• IF await() is called before the async coroutine fails.
  • THEN: the exception goes through await()
• IF the async coroutine fails before await() is called.
  • THEN: the exception propagates up the Job hierarchy immediately.

As we would expect example: exception goes through await()

Here we observe await() receiving exception

Code

package com.glassthought.sandbox
 
import com.glassthought.sandbox.util.out.impl.out
import gt.sandbox.util.output.Emojis
import gt.sandbox.util.output.Out
import kotlinx.coroutines.async
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds
 
private suspend fun mainImpl(out: Out) {
  coroutineScope {
    foo("msg-1")
  }
}
 
private suspend fun foo(msg: String) {
  out.actionWithMsg("fooImpl", { fooImpl(msg) })
}
 
private suspend fun fooImpl(msg: String) {
  coroutineScope {
    launch {
      out.delayNamed(3.seconds, "delayed([${msg}])")
    }
    launch {
      out.delayNamed(2.seconds, "delayed([${msg}])")
    }
    val deferred = async {
      out.delayNamed(500.milliseconds, "delayed([${msg}])")
 
      throw MyRuntimeException.create("exception-from-async", out)
    }
    out.info("Just launched co-routines. Going into deferred.await()")
 
    // This code is unreachable since async exception will go to the parent instead of
    // going to the await()
    try {
      deferred.await()
    } catch (e: Exception) {
      out.error("[RETHROWING][${Emojis.CAUGHT_EXCEPTION}] Caught exception on [deferred.await()] from async: ${e.message} of type [${e::class.simpleName}]")
 
      throw e
    }
  }
}
 
 
fun main(): Unit = runBlocking {
  out.info("START - ON MAIN")
 
  try {
    mainImpl(out)
  } catch (e: Exception) {
    out.error("back at MAIN got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - WITHOUT errors on MAIN")
}

Command to reproduce:

gt.sandbox.checkout.commit fa1ebcc936a485d23912 \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   15ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] START - ON MAIN
[INFO][elapsed:   31ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [>] Starting action=[fooImpl] 
[INFO][elapsed:   34ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    Just launched co-routines. Going into deferred.await()
[INFO][elapsed:   38ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] Delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed:   39ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] Delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed:   39ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Delaying for 500ms what_for=[delayed([msg-1])]
[INFO][elapsed:  541ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Done delaying for 500ms what_for=[delayed([msg-1])]
[WARN][elapsed:  571ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] 💥 throwing exception=[MyRuntimeException] with msg=[exception-from-async]
[WARN][elapsed:  591ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] 🫡 I have caught [JobCancellationException/Parent job is Cancelling], and rethrowing it 🫡
[WARN][elapsed:  592ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] 🫡 I have caught [JobCancellationException/Parent job is Cancelling], and rethrowing it 🫡
[ERROR][elapsed:  593ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    [RETHROWING][� Caught exception on [deferred.await()] from async: exception-from-async of type [MyRuntimeException]
[WARN][elapsed:  593ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [<][💥] Finished action=[fooImpl], threw exception of type=[MyRuntimeException].
[ERROR][elapsed:  594ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] back at MAIN got an exception! of type=[MyRuntimeException] with msg=[exception-from-async] cause=[null]. Exiting with error code 1
 
FAILURE: Build failed with an exception.
 
* What went wrong:
Execution failed for task ':app:run'.
> Process 'command '/home/nickolaykondratyev/.jdks/corretto-21.0.7/bin/java'' finished with non-zero exit value 1
 
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.
 
BUILD FAILED in 1s

Newer behavior: exception propagates through Job link to parent scope WITHOUT going through await()

⚠️ Here we add delay() such that exception is thrown from async BEFORE we call await() on deferred object.
Result: Exception goes directly to parent scope without going through await(). This cancels any other co-routines on scope with regular Job(). ⚠️

Code

package com.glassthought.sandbox
 
import com.glassthought.sandbox.util.out.impl.out
import gt.sandbox.util.output.Emojis
import gt.sandbox.util.output.Out
import kotlinx.coroutines.CoroutineName
import kotlinx.coroutines.async
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds
 
private suspend fun mainImpl(out: Out) {
  coroutineScope {
    foo("msg-1")
  }
}
 
private suspend fun foo(msg: String) {
  out.actionWithMsg("fooImpl", { fooImpl(msg) })
}
 
private suspend fun fooImpl(msg: String) {
  coroutineScope {
    launch(CoroutineName("IJustDelay-3Sec-AndPrint")) {
      out.delayNamed(3.seconds, "delayed([${msg}])")
    }
    launch(CoroutineName("IJustDelay-2Sec-AndPrint")) {
      out.delayNamed(2.seconds, "delayed([${msg}])")
    }
    val deferred = async(CoroutineName("IAmGoingToThrow")) {
      out.delayNamed(500.milliseconds, "delayed([${msg}])")
 
      throw MyRuntimeException.create("exception-from-async", out)
    }
    out.info("Just launched co-routines.")
 
    out.delayNamed(1.seconds, "Going into DELAY before calling [deferred.await()]")
 
    // This code is unreachable since async exception will go to the parent instead of
    // going to the await()
    try {
      out.info("About to call [deferred.await()] (WE ARE NEVER GOING TO REACH THIS LINE)")
      deferred.await()
    } catch (e: Exception) {
      out.error("[RETHROWING][${Emojis.CAUGHT_EXCEPTION}] Caught exception on [deferred.await()] from async: ${e.message} of type [${e::class.simpleName}]")
 
      throw e
    }
  }
}
 
 
fun main(): Unit = runBlocking(CoroutineName("RunBlocking-At-Main")) {
  out.info("START - ON MAIN")
 
  try {
    mainImpl(out)
  } catch (e: Exception) {
    out.error("back at MAIN got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - WITHOUT errors on MAIN")
}

Command to reproduce:

gt.sandbox.checkout.commit 172df689c3cb592bc3eb \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   15ms][🥇][①][coroutname:@RunBlocking-At-Main#1][tname:main/tid:1] START - ON MAIN
[INFO][elapsed:   32ms][🥇][①][coroutname:@RunBlocking-At-Main#1][tname:main/tid:1] [>] Starting action=[fooImpl] 
[INFO][elapsed:   35ms][🥇][①][coroutname:@RunBlocking-At-Main#1][tname:main/tid:1]    Just launched co-routines.
[INFO][elapsed:   36ms][🥇][①][coroutname:@RunBlocking-At-Main#1][tname:main/tid:1]    Delaying for 1s what_for=[Going into DELAY before calling [deferred.await()]]
[INFO][elapsed:   39ms][🥇][⓶][coroutname:@IJustDelay-3Sec-AndPrint#2][tname:main/tid:1] Delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed:   39ms][🥇][⓷][coroutname:@IJustDelay-2Sec-AndPrint#3][tname:main/tid:1] Delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed:   40ms][🥇][⓸][coroutname:@IAmGoingToThrow#4][tname:main/tid:1] Delaying for 500ms what_for=[delayed([msg-1])]
[INFO][elapsed:  541ms][🥇][⓸][coroutname:@IAmGoingToThrow#4][tname:main/tid:1] Done delaying for 500ms what_for=[delayed([msg-1])]
[WARN][elapsed:  572ms][🥇][⓸][coroutname:@IAmGoingToThrow#4][tname:main/tid:1] 💥 throwing exception=[MyRuntimeException] with msg=[exception-from-async]
[WARN][elapsed:  591ms][🥇][⓶][coroutname:@IJustDelay-3Sec-AndPrint#2][tname:main/tid:1] 🫡 I have caught [JobCancellationException/Parent job is Cancelling], and rethrowing it 🫡
[WARN][elapsed:  592ms][🥇][⓷][coroutname:@IJustDelay-2Sec-AndPrint#3][tname:main/tid:1] 🫡 I have caught [JobCancellationException/Parent job is Cancelling], and rethrowing it 🫡
[WARN][elapsed:  593ms][🥇][①][coroutname:@RunBlocking-At-Main#1][tname:main/tid:1]    🫡 I have caught [JobCancellationException/ScopeCoroutine is cancelling], and rethrowing it 🫡
[WARN][elapsed:  594ms][🥇][①][coroutname:@RunBlocking-At-Main#1][tname:main/tid:1] [<][💥] Finished action=[fooImpl], threw exception of type=[MyRuntimeException].
[ERROR][elapsed:  594ms][🥇][①][coroutname:@RunBlocking-At-Main#1][tname:main/tid:1] back at MAIN got an exception! of type=[MyRuntimeException] with msg=[exception-from-async] cause=[null]. Exiting with error code 1
 
FAILURE: Build failed with an exception.
 
* What went wrong:
Execution failed for task ':app:run'.
> Process 'command '/home/nickolaykondratyev/.jdks/corretto-21.0.7/bin/java'' finished with non-zero exit value 1
 
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.
 
BUILD FAILED in 1s

Link to original

Link to original

CoroutineExceptionHandler

kdoc: CoroutineExceptionHandler

An optional element in the coroutine context to handle uncaught-exception.

Highlights

• Handles uncaught-exception.
• Does NOT work with async.

Examples

CoroutineExceptionHandler only works with launch

CoroutineExceptionHandler processes uncaught exception from launch

Code

package com.glassthought.sandbox
 
import gt.sandbox.util.output.Emojis
import gt.sandbox.util.output.Out
import kotlinx.coroutines.*
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.milliseconds
 
fun main(): Unit = runBlocking {
  val out = Out.standard()
  out.info("START")
 
  try {
    mainImpl(out)
  } catch (e: Exception) {
    out.error("in main got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - WITHOUT errors on main")
}
 
private suspend fun mainImpl(out: Out) {
  val coroutineExceptionHandler = CoroutineExceptionHandler { _, throwable ->
    runBlocking {
      out.info("${Emojis.CHECK_MARK} CoroutineExceptionHandler CALLED!")
      out.info("CoroutineExceptionHandler is called with throwable: ${throwable::class.simpleName} - ${throwable.message}")
    }
  }
 
  val parentJob = Job()
  val scope = CoroutineScope(parentJob + coroutineExceptionHandler)
 
  out.info("Launching coroutine that will throw exception...")
  val job = scope.launch {
    out.info("Launch coroutine started")
 
    out.delayLogsCancellation(500.milliseconds)
 
    throw MyExceptionWillThrowFromCoroutine.create("Exception from launch", out)
  }
 
  out.actionWithMsg("job.join()", { job.join() })
  out.infoPrintState(job, "launchJob")
  out.infoPrintState(scope, "scope-where-we-launched")
 
  scope.cancel()
}
 
class MyExceptionWillThrowFromCoroutine private constructor(msg: String) : RuntimeException(msg) {
  companion object {
    suspend fun create(msg: String, out: Out): MyExceptionWillThrowFromCoroutine {
      val exc = MyExceptionWillThrowFromCoroutine(msg)
 
      out.warn("${Emojis.EXCEPTOIN} throwing exception=[${exc::class.simpleName}] with msg=[${msg}]")
 
      return exc
    }
  }
}

Command to reproduce:

gt.sandbox.checkout.commit a7bc470832057f8c7ff6 \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   20ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] START
[INFO][elapsed:   40ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Launching coroutine that will throw exception...
[INFO][elapsed:   46ms][2️⃣][⓶][coroutname:@coroutine#2][tname:DefaultDispatcher-worker-1/tid:31] Launch coroutine started
[INFO][elapsed:   46ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Performing action=[job.join()]
[WARN][elapsed:  582ms][2️⃣][⓶][coroutname:@coroutine#2][tname:DefaultDispatcher-worker-1/tid:31] 💥  throwing exception=[MyExceptionWillThrowFromCoroutine] with msg=[Exception from launch]
[INFO][elapsed:  584ms][2️⃣][⓷][coroutname:@coroutine#3][tname:DefaultDispatcher-worker-1/tid:31] ✅ CoroutineExceptionHandler CALLED!
[INFO][elapsed:  585ms][2️⃣][⓷][coroutname:@coroutine#3][tname:DefaultDispatcher-worker-1/tid:31] CoroutineExceptionHandler is called with throwable: MyExceptionWillThrowFromCoroutine - Exception from launch
[INFO][elapsed:  586ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Performed action=[job.join()]
[INFO][elapsed:  589ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] State of [launchJob]:
launchJob.isActive    | false
launchJob.isCancelled | true
launchJob.isCompleted | true
[INFO][elapsed:  589ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] State of [scope-where-we-launched]: isActive=false
[INFO][elapsed:  589ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] DONE - WITHOUT errors on main

Link to original

⚠️CoroutineExceptionHandler: does NOT work with async⚠️

⚠️ async & CoroutineExceptionHandler: CoroutineExceptionHandler with async will be ignored. AWAIT rethrows the exception - ⚠️

Doc

A coroutine that was created using async always catches all its exceptions and represents them in the resulting Deferred object, so it cannot result in uncaught exceptions. - kdoc

Code

package com.glassthought.sandbox
 
import gt.sandbox.util.output.Emojis
import gt.sandbox.util.output.Out
import kotlinx.coroutines.*
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.milliseconds
 
fun main(): Unit = runBlocking {
  val out = Out.standard()
  out.info("START")
 
  try {
    mainImpl(out)
  } catch (e: Exception) {
    out.error("in main got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - WITHOUT errors on main")
}
 
private suspend fun mainImpl(out: Out) {
 
  // CoroutineExceptionHandler - will be IGNORED with async - ⚠️🐛⚠️
  // This handler will NEVER be called because async doesn't use it
  val coroutineExceptionHandler = CoroutineExceptionHandler { _, throwable ->
    // This block will NEVER execute with async
    println("❌ CoroutineExceptionHandler called (this won't happen): ${throwable.message}")
  }
 
  // Create a scope with the exception handler
  // Note: Using just coroutineExceptionHandler for clarity (no SupervisorJob needed for this demo)
  val scope = CoroutineScope(coroutineExceptionHandler)
 
  out.info("Creating async coroutine...")
 
  val delayInChild = 500.milliseconds
  val deferredResult = scope.async {
    out.info("Async coroutine started, will throw exception after delay...")
    delay(delayInChild)
    throw MyExceptionWillThrowFromCoroutine.create("async-exception-msg", out)
  }
 
  out.info("${Emojis.BUG}: CoroutineExceptionHandler is installed but will NEVER be called for async")
  out.info("Reason: async stores exceptions until await() is called, doesn't propagate to handler")
 
  // Give async time to complete and throw internally
  out.delayNamed(delayInChild * 2, "giving async time to complete and store exception")
 
  // The exception is stored in the Deferred, not propagated to handler
  out.info("Async has completed. Exception is stored in Deferred.")
  out.infoPrintState(deferredResult, "deferredResult")
 
  // This will rethrow the stored exception to the caller
  out.info("Calling await() - this will rethrow the stored exception...")
  try {
    deferredResult.await()
    out.error("Should never reach here - await() should throw")
  } catch (e: Exception) {
    out.warn("✅ Exception caught by try-catch (NOT by CoroutineExceptionHandler): ${e.message}")
    out.info("This shows CoroutineExceptionHandler doesn't work with async/await")
  }
 
  out.info("Demonstration complete - handler was never called")
}
 
class MyExceptionWillThrowFromCoroutine private constructor(msg: String) : RuntimeException(msg) {
  companion object {
    suspend fun create(msg: String, out: Out): MyExceptionWillThrowFromCoroutine {
      val exc = MyExceptionWillThrowFromCoroutine(msg)
 
      out.warn("${Emojis.EXCEPTOIN} throwing exception=[${exc::class.simpleName}] with msg=[${msg}]")
 
      return exc
    }
  }
}

Command to reproduce:

gt.sandbox.checkout.commit 75b9c9b740f35ad9b8b7 \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   15ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] START
[INFO][elapsed:   30ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Creating async coroutine...
[INFO][elapsed:   36ms][2️⃣][⓶][coroutname:@coroutine#2][tname:DefaultDispatcher-worker-1/tid:31] Async coroutine started, will throw exception after delay...
[INFO][elapsed:   36ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] ⚠️�oroutineExceptionHandler is installed but will NEVER be called for async
[INFO][elapsed:   36ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Reason: async stores exceptions until await() is called, doesn't propagate to handler
[INFO][elapsed:   38ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Delaying for 1s what_for=[giving async time to complete and store exception]
[WARN][elapsed:  560ms][2️⃣][⓶][coroutname:@coroutine#2][tname:DefaultDispatcher-worker-1/tid:31] 💥  throwing exception=[MyExceptionWillThrowFromCoroutine] with msg=[async-exception-msg]
[INFO][elapsed: 1039ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Done delaying for 1s what_for=[giving async time to complete and store exception]
[INFO][elapsed: 1039ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Async has completed. Exception is stored in Deferred.
[INFO][elapsed: 1044ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] State of [deferredResult]:
deferredResult.isActive    | false
deferredResult.isCancelled | true
deferredResult.isCompleted | true
 
[INFO][elapsed: 1045ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Calling await() - this will rethrow the stored exception...
[WARN][elapsed: 1048ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] ✅ Exception caught by try-catch (NOT by CoroutineExceptionHandler): async-exception-msg
[INFO][elapsed: 1048ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] This shows CoroutineExceptionHandler doesn't work with async/await
[INFO][elapsed: 1048ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Demonstration complete - handler was never called
[INFO][elapsed: 1048ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] DONE - WITHOUT errors on main

⚠️ IF async throws unhandled exception before await THEN exception is lost⚠️

If async throws before await: The exception is lost and is NOT processed by CoroutineExceptionHandler

Code

package com.glassthought.sandbox
 
import com.glassthought.sandbox.util.out.impl.out
import kotlinx.coroutines.*
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds
 
 
fun main(): Unit {
  val coroutineExceptionHandler = CoroutineExceptionHandler { _, ex ->
    runBlocking(CoroutineName("CoroutineExceptionHandler")) {
      out.error("Caught exception in CoroutineExceptionHandler: ${ex::class.simpleName} with message=[${ex.message}].")
    }
  }
 
  val mainJob = Job()
  val scope = CoroutineScope(mainJob + coroutineExceptionHandler)
 
  scope.launch(CoroutineName("SpawnedFromMain")) {
    out.actionWithMsg("foo", { foo(scope) })
  }
 
  runBlocking {
    out.actionWithMsg("mainJob.join()", { mainJob.join() })
  }
}
 
private suspend fun foo(scope: CoroutineScope) {
  val deferred = scope.async(CoroutineName("async-1")) {
    out.actionWithMsg("throw-exception", {
      throw MyRuntimeException.create("exception-from-async-before-it-got-to-await", out)
    }, delayDuration = 500.milliseconds)
  }
 
  out.info("Just launched co-routines.")
  out.actionWithMsg(
    "deferred.await()",
    {
      deferred.await()
    },
    delayDuration = 1.seconds
  )
}

Command to reproduce:

gt.sandbox.checkout.commit 0423eb04f6570cb822dd \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   19ms][①][coroutname:@SpawnedFromMain#1] [->] action=[foo] is starting.
[INFO][elapsed:   19ms][⓶][coroutname:@coroutine#2] [->] action=[mainJob.join()] is starting.
[INFO][elapsed:   32ms][①][coroutname:@SpawnedFromMain#1]    Just launched co-routines.
[INFO][elapsed:   36ms][①][coroutname:@SpawnedFromMain#1]    [🐢] action=[deferred.await()] is being delayed for=[1000 ms] before starting.
[INFO][elapsed:   36ms][⓷][coroutname:@async-1#3] [🐢] action=[throw-exception] is being delayed for=[500 ms] before starting.
[INFO][elapsed:  536ms][⓷][coroutname:@async-1#3] [->] action=[throw-exception] is starting.
[WARN][elapsed:  566ms][⓷][coroutname:@async-1#3]    💥 throwing exception=[MyRuntimeException] with msg=[exception-from-async-before-it-got-to-await]
[WARN][elapsed:  567ms][⓷][coroutname:@async-1#3] [<-][💥] Finished action=[throw-exception], it THREW exception of type=[MyRuntimeException] we are rethrowing it.
[INFO][elapsed:  583ms][①][coroutname:@SpawnedFromMain#1] [<-][🫡] Cancellation Exception - rethrowing.
[INFO][elapsed:  583ms][⓶][coroutname:@coroutine#2] [<-] Finished action=[mainJob.join()].

GT-Sandbox-Snapshot: Example where awaiting co-routine got cancelled before getting to await

Code

package com.glassthought.sandbox
 
import kotlinx.coroutines.*
 
val startMillis = System.currentTimeMillis()
 
 
fun myPrint(msg: String) {
  val elapsed = System.currentTimeMillis() - startMillis
 
  println("[${elapsed.toString().padStart(3)} ms] $msg")
}
 
fun main() {
  myPrint("[MAIN] START...")
 
  val mainScopeJob = Job()
  val mainScope = CoroutineScope(
    mainScopeJob
      + Dispatchers.IO
      + CoroutineExceptionHandler { _, throwable -> myPrint("👍 CoroutineExceptionHandler invoked exc.message=[${throwable.message}]👍 ") }
      + CoroutineName("main-scope")
  )
 
  val async = mainScope.async(CoroutineName("async-coroutine")) {
    myPrint(" [async-coroutine]: I am going to throw in about 100ms")
    delay(100)
    myPrint(" [async-coroutine]: Throwing exception now!")
 
    throw RuntimeException("I am an exception from async coroutine")
  }
 
  val waiter = mainScope.launch {
    try {
      myPrint("   [launch-routine-just-waiting] I am going to wait 500 millis and then await")
      delay(500)
      async.await()
    } catch (e: CancellationException) {
      myPrint("   [launch-routine-just-waiting] I was cancelled! CancellationException.message=[${e.message}]")
      throw e
    } catch (e: Exception) {
      myPrint("   [launch-routine-just-waiting] ✅ I caught an exception! Exception.message=[${e.message}]")
    }
  }
 
 
  runBlocking {
    mainScopeJob.join()
  }
 
  myPrint("[MAIN] DONE.")
}

Command to reproduce:

gt.sandbox.checkout.commit 1b939780478f3d10a020 \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[  7 ms] [MAIN] START...
[ 43 ms]    [launch-routine-just-waiting] I am going to wait 500 millis and then await
[ 43 ms]  [async-coroutine]: I am going to throw in about 100ms
[145 ms]  [async-coroutine]: Throwing exception now!
[167 ms]    [launch-routine-just-waiting] I was cancelled! CancellationException.message=[Parent job is Cancelling]
[168 ms] [MAIN] DONE.

Related Patterns to combat this

• GettingNiceToHaveDataInAsyncWithoutCrashingRequiredDataGetUsingSupervisorScope - if you use supervisor scope then exception from async does NOT crash shutdown the parent, and hence, you can make sure await() is called.

Link to original

Link to original

Gotchas:

CoroutineExceptionHandler gotchas

• uncaught-exception-vocabulary-does-not-include-all-unahndled-exceptions
  • does-not-work-with-async
    • if-async-throws-before-await-exception-is-lost

Link to original

Link to original

⚠️ join() does NOT rethrow ⚠️

Unlike await() which does rethrow, join() just waits for co-routine to complete, without care of whether completion was successful or failure.

⚠️ join() does NOT rethrow code example ⚠️

Code

package com.glassthought.sandbox
 
import gt.sandbox.util.output.Emojis
import gt.sandbox.util.output.Out
import kotlinx.coroutines.*
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.milliseconds
 
fun main(): Unit = runBlocking {
  val out = Out.standard()
  out.info("START")
 
  try {
    mainImpl(out)
  } catch (e: Exception) {
    out.error("in main got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - WITHOUT errors on main")
}
 
private suspend fun mainImpl(out: Out) {
  val parentJob = Job()
  val scope = CoroutineScope(parentJob)
 
  out.info("Launching coroutine that will throw exception...")
  val job = scope.launch {
    out.info("Launch coroutine started")
 
    out.delayLogsCancellation(500.milliseconds)
 
    throw MyExceptionWillThrowFromCoroutine.create("Exception from launch", out)
  }
 
  out.actionWithMsg("job.join()", { job.join() })
  out.infoPrintState(job, "launchJob")
  out.infoPrintState(scope, "scope-where-we-launched")
}
 
class MyExceptionWillThrowFromCoroutine private constructor(msg: String) : RuntimeException(msg) {
  companion object {
    suspend fun create(msg: String, out: Out): MyExceptionWillThrowFromCoroutine {
      val exc = MyExceptionWillThrowFromCoroutine(msg)
 
      out.warn("${Emojis.EXCEPTOIN} throwing exception=[${exc::class.simpleName}] with msg=[${msg}]")
 
      return exc
    }
  }
}

Command to reproduce:

gt.sandbox.checkout.commit 73693c5d8d2ddb27f9a7 \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   14ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] START
[INFO][elapsed:   29ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Launching coroutine that will throw exception...
[INFO][elapsed:   34ms][2️⃣][⓶][coroutname:@coroutine#2][tname:DefaultDispatcher-worker-1/tid:31] Launch coroutine started
[INFO][elapsed:   34ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Performing action=[job.join()]
[WARN][elapsed:  569ms][2️⃣][⓶][coroutname:@coroutine#2][tname:DefaultDispatcher-worker-1/tid:31] 💥  throwing exception=[MyExceptionWillThrowFromCoroutine] with msg=[Exception from launch]
Exception in thread "DefaultDispatcher-worker-1 @coroutine#2" com.glassthought.sandbox.MyExceptionWillThrowFromCoroutine: Exception from launch
	at com.glassthought.sandbox.MyExceptionWillThrowFromCoroutine$Companion.create(Main.kt:46)
	at com.glassthought.sandbox.MainKt$mainImpl$job$1.invokeSuspend(Main.kt:34)
	at kotlin.coroutines.jvm.internal.BaseContinuationImpl.resumeWith(ContinuationImpl.kt:33)
	at kotlinx.coroutines.DispatchedTask.run(DispatchedTask.kt:108)
	at kotlinx.coroutines.scheduling.CoroutineScheduler.runSafely(CoroutineScheduler.kt:584)
	at kotlinx.coroutines.scheduling.CoroutineScheduler$Worker.executeTask(CoroutineScheduler.kt:793)
	at kotlinx.coroutines.scheduling.CoroutineScheduler$Worker.runWorker(CoroutineScheduler.kt:697)
	at kotlinx.coroutines.scheduling.CoroutineScheduler$Worker.run(CoroutineScheduler.kt:684)
	Suppressed: kotlinx.coroutines.internal.DiagnosticCoroutineContextException: [CoroutineId(2), "coroutine#2":StandaloneCoroutine{Cancelling}@e541635, Dispatchers.Default]
[INFO][elapsed:  576ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] Performed action=[job.join()]
[INFO][elapsed:  579ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] State of [launchJob]:
launchJob.isActive    | false
launchJob.isCancelled | true
launchJob.isCompleted | true
[INFO][elapsed:  579ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] State of [scope-where-we-launched]: isActive=false
[INFO][elapsed:  580ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] DONE - WITHOUT errors on main

Link to original

Also see

• example

Link to original

CancellationException focused examples

cancel-parent-cancel-children

Here we cancel the parent scope and that automatically cancels children.

Code

package com.glassthought.sandbox
 
import gt.sandbox.util.output.Out
import kotlinx.coroutines.CancellationException
import kotlinx.coroutines.async
import kotlinx.coroutines.cancel
import kotlinx.coroutines.coroutineScope
import kotlinx.coroutines.launch
import kotlinx.coroutines.runBlocking
import kotlin.system.exitProcess
import kotlin.time.Duration.Companion.milliseconds
import kotlin.time.Duration.Companion.seconds
 
private val out = Out.standard()
private suspend fun mainImpl(out: Out) {
  coroutineScope {
    foo("msg-1")
  }
}
 
private suspend fun foo(msg: String) {
  out.actionWithMsg("fooImpl", { fooImpl(msg) })
}
 
private suspend fun fooImpl(msg: String) {
  coroutineScope {
    val deferred3 = async {
      out.delayNamed(3.seconds, "delayed([${msg}])")
 
      "res-3"
    }
    val deferred2 = async {
      out.delayNamed(2.seconds, "delayed([${msg}])")
 
      "res-2"
    }
    val deferred1 = async {
      out.delayNamed(1.seconds, "delayed([${msg}])")
 
      "res-1"
    }
 
 
    out.info("Just launched co-routines")
    out.delayNamed(500.milliseconds, "delay before scope cancel")
    this.cancel()
 
    out.info("deferred-1.result=" + deferred1.await())
    out.info("deferred-2.result=" + deferred2.await())
    out.info("deferred-3.result=" + deferred3.await())
  }
 
}
 
fun main(): Unit = runBlocking {
  out.info("START - ON MAIN")
 
  try {
    mainImpl(out)
  } catch (e: Exception) {
    out.error("back at MAIN got an exception! of type=[${e::class.simpleName}] with msg=[${e.message}] cause=[${e.cause}]. Exiting with error code 1")
 
    exitProcess(1)
  }
 
  out.info("DONE - WITHOUT errors on MAIN")
}

Command to reproduce:

gt.sandbox.checkout.commit a2df237045869c0a8e1b \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   39ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] START - ON MAIN
[INFO][elapsed:   56ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [>] Starting action=[fooImpl] 
[INFO][elapsed:   58ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    Just launched co-routines
[INFO][elapsed:   60ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    Delaying for 500ms what_for=[delay before scope cancel]
[INFO][elapsed:   63ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] Delaying for 3s what_for=[delayed([msg-1])]
[INFO][elapsed:   63ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] Delaying for 2s what_for=[delayed([msg-1])]
[INFO][elapsed:   63ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] Delaying for 1s what_for=[delayed([msg-1])]
[INFO][elapsed:  562ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1]    Done delaying for 500ms what_for=[delay before scope cancel]
[WARN][elapsed:  615ms][🥇][⓶][coroutname:@coroutine#2][tname:main/tid:1] 🫡 I have caught [JobCancellationException/ScopeCoroutine was cancelled], and rethrowing it 🫡
[WARN][elapsed:  615ms][🥇][⓷][coroutname:@coroutine#3][tname:main/tid:1] 🫡 I have caught [JobCancellationException/ScopeCoroutine was cancelled], and rethrowing it 🫡
[WARN][elapsed:  616ms][🥇][⓸][coroutname:@coroutine#4][tname:main/tid:1] 🫡 I have caught [JobCancellationException/ScopeCoroutine was cancelled], and rethrowing it 🫡
[INFO][elapsed:  616ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] [>][🫡] Cancellation Exception - rethrowing.
[ERROR][elapsed:  617ms][🥇][①][coroutname:@coroutine#1][tname:main/tid:1] back at MAIN got an exception! of type=[JobCancellationException] with msg=[ScopeCoroutine was cancelled] cause=[kotlinx.coroutines.JobCancellationException: ScopeCoroutine was cancelled; job="coroutine#1":ScopeCoroutine{Cancelled}@768b970c]. Exiting with error code 1
 
FAILURE: Build failed with an exception.
 
* What went wrong:
Execution failed for task ':app:run'.
> Process 'command '/home/nickolaykondratyev/.jdks/corretto-21.0.7/bin/java'' finished with non-zero exit value 1
 
* Try:
> Run with --stacktrace option to get the stack trace.
> Run with --info or --debug option to get more log output.
> Run with --scan to get full insights.
> Get more help at https://help.gradle.org.
 
BUILD FAILED in 1s

Link to original

Scope with Regular Job - throw CancellationException - stops co-routine that threw. Does NOT stop sibling co-routine, does not rethrow to parent.

Code

package com.glassthought.sandbox
 
import gt.sandbox.util.output.Emojis
import gt.sandbox.util.output.Out
import kotlinx.coroutines.*
import kotlin.system.exitProcess
 
suspend fun main(): kotlin.Unit {
  val out = Out.standard()
  out.info("START")
 
  try {
    runBlocking {
 
      launch(CoroutineName("WillThrowCancelExc")) {
        // Loop over a range from 1 to 5 (inclusive)
        val howMany = 5
        for (i in 1..howMany) {
          val timeMillis = 1000L
          out.info("I will call throw CancellationException in $timeMillis ms - processing value:[${i}/${howMany}]")
          delay(timeMillis)
          out.warn("I am throwing CancellationException at value - [${i}/${howMany}]")
 
          throw CancellationException("cancel-message")
        }
      }
 
      launch(CoroutineName("JustPrints")) {
        (0..10)
          .map { "a-${it}" }
          .forEach {
            out.info(it)
 
            try {
              delay(500)
            } catch (e: CancellationException) {
              val excMsg = e.message ?: e.toString()
              out.warn("${Emojis.OBIDIENT} I have caught [${e::class.simpleName}/$excMsg], and rethrowing it ${Emojis.OBIDIENT} ")
 
              throw e
            }
          }
 
        out.info("${Emojis.CHECK_MARK} I have FINISHED all of my messages.")
      }
    }
 
  } catch (e: Exception) {
    out.error("runBlocking threw an exception! of type=[${e::class.simpleName}] with msg=[${e.message}]")
 
    exitProcess(1)
  }
 
  out.info("DONE no errors at main.")
}
 
class MyExceptionWillThrowFromCoroutine(msg: String) : RuntimeException(msg)

Command to reproduce:

gt.sandbox.checkout.commit b7c3be031f6453aa7ce9 \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   25ms][🥇][🧵][tname:main/tid:1] START
[INFO][elapsed:   67ms][🥇][①][coroutname:@WillThrowCancelExc#2][tname:main/tid:1] I will call throw CancellationException in 1000 ms - processing value:[1/5]
[INFO][elapsed:   74ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-0
[INFO][elapsed:  575ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-1
[WARN][elapsed: 1074ms][🥇][①][coroutname:@WillThrowCancelExc#2][tname:main/tid:1] I am throwing CancellationException at value - [1/5]
[INFO][elapsed: 1075ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-2
[INFO][elapsed: 1576ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-3
[INFO][elapsed: 2076ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-4
[INFO][elapsed: 2577ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-5
[INFO][elapsed: 3077ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-6
[INFO][elapsed: 3578ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-7
[INFO][elapsed: 4079ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-8
[INFO][elapsed: 4579ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-9
[INFO][elapsed: 5080ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-10
[INFO][elapsed: 5581ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] ✅ I have FINISHED all of my messages.
[INFO][elapsed: 5581ms][🥇][🧵][tname:main/tid:1] DONE no errors at main.

Calling this.cancel()

⚠️ cancel() call stops on next suspension point, NOT right away ⚠️

Scope with Regular Job - Call this.cancel() - Will stop co-routine on next cooperative cancelation function invocation. Does NOT stop sibling co-routine, does not rethrow to parent. ⚠️Will not stop right away⚠️

Highlight

When co-routine calls this.cancel() it does NOT stop processing right away, it stops processing once it reaches functions-suspension-point.

Code

package com.glassthought.sandbox
 
import gt.sandbox.util.output.Emojis
import gt.sandbox.util.output.Out
import kotlinx.coroutines.*
import kotlin.system.exitProcess
 
suspend fun main(): kotlin.Unit {
  val out = Out.standard()
 
  out.info("START")
 
  try {
    runBlocking {
 
      launch(CoroutineName("WillCancelMyself")) {
        // Loop over a range from 1 to 5 (inclusive)
        val howMany = 5
        for (i in 1..howMany) {
 
          val timeMillis = 1000L
          out.info("I will call cancel in $timeMillis ms - processing value:[${i}/${howMany}] - going into delay()")
 
          try {
            delay(timeMillis)
          } catch (e: CancellationException) {
            val excMsg = e.message ?: e.toString()
            out.warn("${Emojis.OBIDIENT} I have caught [${e::class.simpleName}/$excMsg], and rethrowing it ${Emojis.OBIDIENT} ")
            throw e
          }
 
          out.warn("I am calling this.cancel() at value - [${i}/${howMany}]")
          this.cancel()
 
          out.warn("${Emojis.WARNING_SIGN} We continued work after this.cancel()${Emojis.WARNING_SIGN}")
 
        }
      }
 
      launch(CoroutineName("JustPrints")) {
        (0..10)
          .map { "a-${it}" }
          .forEach {
            out.info(it)
 
            try {
              delay(500)
            } catch (e: CancellationException) {
              val excMsg = e.message ?: e.toString()
              out.warn("${Emojis.OBIDIENT} I have caught [${e::class.simpleName}/$excMsg], and rethrowing it ${Emojis.OBIDIENT} ")
 
              throw e
            }
          }
 
        out.info("${Emojis.CHECK_MARK} I have FINISHED all of my messages.")
      }
    }
 
  } catch (e: Exception) {
    out.error("runBlocking threw an exception! of type=[${e::class.simpleName}] with msg=[${e.message}]")
 
    exitProcess(1)
  }
 
  out.info("DONE no errors at main.")
}
 
class MyExceptionWillThrowFromCoroutine(msg: String) : RuntimeException(msg)

Command to reproduce:

gt.sandbox.checkout.commit 8798f084905aee1fef60 \
&& cd "${GT_SANDBOX_REPO}" \
&& cmd.run.announce "./gradlew run --quiet"

Recorded output of command:

Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
Picked up JAVA_TOOL_OPTIONS: -Dkotlinx.coroutines.debug
[INFO][elapsed:   17ms][🥇][🧵][tname:main/tid:1] START
[INFO][elapsed:   51ms][🥇][①][coroutname:@WillCancelMyself#2][tname:main/tid:1] I will call cancel in 1000 ms - processing value:[1/5] - going into delay()
[INFO][elapsed:   57ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-0
[INFO][elapsed:  558ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-1
[WARN][elapsed: 1057ms][🥇][①][coroutname:@WillCancelMyself#2][tname:main/tid:1] I am calling this.cancel() at value - [1/5]
[WARN][elapsed: 1058ms][🥇][①][coroutname:@WillCancelMyself#2][tname:main/tid:1] ⚠️ We continued work after this.cancel()⚠️
[INFO][elapsed: 1058ms][🥇][①][coroutname:@WillCancelMyself#2][tname:main/tid:1] I will call cancel in 1000 ms - processing value:[2/5] - going into delay()
[WARN][elapsed: 1094ms][🥇][①][coroutname:@WillCancelMyself#2][tname:main/tid:1] 🫡 I have caught [JobCancellationException/StandaloneCoroutine was cancelled], and rethrowing it 🫡 
[INFO][elapsed: 1094ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-2
[INFO][elapsed: 1594ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-3
[INFO][elapsed: 2095ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-4
[INFO][elapsed: 2595ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-5
[INFO][elapsed: 3096ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-6
[INFO][elapsed: 3596ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-7
[INFO][elapsed: 4097ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-8
[INFO][elapsed: 4598ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-9
[INFO][elapsed: 5098ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] a-10
[INFO][elapsed: 5600ms][🥇][⓶][coroutname:@JustPrints#3][tname:main/tid:1] ✅ I have FINISHED all of my messages.
[INFO][elapsed: 5600ms][🥇][🧵][tname:main/tid:1] DONE no errors at main.

Link to original

Link to original

Link to original

Key Takeaway

Unless you explicitly use SupervisorJob or supervisorScope, you’re working with a scope with regular job that follows structured concurrency principles where one child’s failure affects the entire coroutine family.