Why Exception Handling with Kotlin Coroutines is hard and how to master it

Getting the “happy path” right with Kotlin Coroutines is pretty straightforward. On the other hand, handling exceptions appropriately when something goes wrong is not that trivial.

In this talk, you will learn about the reasons for the complexity of exception handling with Kotlin Coroutines and about all things you need to consider to appropriately deal with occurring exceptions.
You will learn when you should use a conventional try-catch clause, and when you should install a CoroutineExceptionHandler instead.
You will also learn about the special properties of top-level Coroutines when it comes to exception handling and how they differ when they are starting with launch and async.
Furthermore, you will learn all about the exception handling peculiarities of the scoping functions coroutineScope{} and supervisorScope{} and why you should re-throw CancellationExceptions to avoid subtle errors.

This talk is for developers that are already familiar with the basics of Kotlin Coroutines but still struggle to understand how exception handling works in detail. By the end of this talk, you will have a better understanding of how exceptions are treated by the Coroutines machinery and how you can handle them appropriately.

Transcript

1. Why Exception Handling in Kotlin Coroutines is hard … … and how to master it! Lukas Lechner Freelance Developer & Online Instructor www.lukaslechner.com November 17, 2020
2. Lukas Lechner Freelance Developer & Online Instructor www.lukaslechner.com @LukasLechnerDev
3. Kotlin Coroutines: Write asynchronous and concurrent code in a sequential fashion by using conventional coding constructs.
4. Exceptions in General
5. fun main() { // some code throw Exception() } >_ Exception in thread "main" java.lang.Exception
6. fun main() { // some code throw Exception() }
7. fun main() { try { // some code throw Exception() } catch (exception: Exception) { println(“Handled exception") } } >_ Handled exception fun main() { try { // some code throw Exception() } catch (exception: Exception) { println(“Handled exception") } }
8. fun main() { try { functionThatThrows() } catch (exception: Exception) { println(“Handled exception") } } fun functionThatThrows() { // some code throw Exception() } >_ Handled exception fun main() { try { functionThatThrows() } catch (exception: Exception) { println(“Handled exception") } } fun functionThatThrows() { // some code throw Exception() }
9. Exceptions in Coroutines
10. fun main() { val rootScope = CoroutineScope(Job()) rootScope.launch { throw Exception() } Thread.sleep(100) } >_ Exception in thread "DefaultDispatcher-worker-1" java.lang.Exception
11. fun main() { val rootScope = CoroutineScope(Job()) rootScope.launch { try { throw Exception() } catch (exception: Exception) { println(“Handled $exception") } } Thread.sleep(100) } >_ Handled exception fun main() { val rootScope = CoroutineScope(Job()) rootScope.launch { try { throw Exception() } catch (exception: Exception) { println(“Handled $exception") } } Thread.sleep(100) }
12. ... rootScope.launch { try { suspendFunctionThatThrows() } catch (exception: Exception) { println(“Handled $exception") } } suspend fun suspendFunctionThatThrows() { throw Exception() } >_ Handled exception ... rootScope.launch { try { suspendFunctionThatThrows() } catch (exception: Exception) { println(“Handled $exception") } } suspend fun suspendFunctionThatThrows() { throw Exception() }
13. ... rootScope.launch { try { throw Exception() } catch (exception: Exception) { println("Handled $exception") } } }
14. ... rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println("Handle $exception") } } >_ Exception in thread “DefaultDispatcher-worker-2" java.lang.Exception ... rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } }
15. ... val rootScope = CoroutineScope(Job()) rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } }
16. ... val rootScope = CoroutineScope(Job()) rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } } rootScope Job
17. ... val rootScope = CoroutineScope(Job()) rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } } Job Coroutine started with launch{} rootScope Job
18. Job Child Coroutine started with launch{} ... val rootScope = CoroutineScope(Job()) rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } } Job Coroutine started with launch{} rootScope Job
19. Uncaught Exception Handler Job Child Coroutine started with launch{} ... val rootScope = CoroutineScope(Job()) rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } } Job Coroutine started with launch{} rootScope Job
20. Coroutine Exception Handler
21. Every Coroutine and CoroutineScope has a CoroutineContext CoroutineContext Context Elements Job ExceptionHandler Name Dispatcher
22. val ceh = CoroutineExceptionHandler { coroutineContext, exception -> println(“Handled $exception in CoroutineExceptionHandler") }
23. val ceh = CoroutineExceptionHandler {…} val rootScope = CoroutineScope(Job()) rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } } Child Coroutine Root Coroutine rootScope
24. val ceh = CoroutineExceptionHandler {…} val rootScope = CoroutineScope(Job()) rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } } Child Coroutine Root Coroutine rootScope
25. Uncaught Exception Handler val ceh = CoroutineExceptionHandler {…} val rootScope = CoroutineScope(Job()) rootScope.launch { try { launch(ceh) { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } } Child Coroutine Root Coroutine rootScope Coroutine Exception Handler val ceh = CoroutineExceptionHandler {…} val rootScope = CoroutineScope(Job()) rootScope.launch { try { launch(ceh) { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } } >_ Exception in thread “DefaultDispatcher- worker-2" java.lang.Exception
26. val ceh = CoroutineExceptionHandler {…} val topLevelScope = CoroutineScope(Job()) topLevelScope.launch(ceh) { try { launch { throw Exception() } } catch (exception: Exception) { println("Handle $exception") } } val ceh = CoroutineExceptionHandler {…} val rootScope = CoroutineScope(Job()) rootScope.launch(ceh) { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } } Child Coroutine Root Coroutine rootScope Coroutine Exception Handler
27. val ceh = CoroutineExceptionHandler {…} val topLevelScope = CoroutineScope(Job()) topLevelScope.launch(ceh) { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } } val ceh = CoroutineExceptionHandler {…} val rootScope = CoroutineScope(Job()) rootScope.launch(ceh) { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } } Child Coroutine Root Coroutine rootScope Coroutine Exception Handler >_ Handled exception in CoroutineExceptionHandler
28. val ceh = CoroutineExceptionHandler {…} val rootScope = CoroutineScope(Job() + ceh) rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println("Handled $exception") } } Child Coroutine Root Coroutine rootScope Coroutine Exception Handler
29. val ceh = CoroutineExceptionHandler {…} val rootScope = CoroutineScope(Job() + ceh) rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println("Handled $exception") } } Child Coroutine Root Coroutine rootScope Coroutine Exception Handler
30. val ceh = CoroutineExceptionHandler {…} val rootScope = CoroutineScope(Job() + ceh) rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println("Handled $exception") } } Child Coroutine Root Coroutine rootScope Coroutine Exception Handler Coroutine Exception Handler >_ Handled exception in CoroutineExceptionHandler
31. Root Coroutines have some special properties
32. Coroutine Exception Handler VS try/catch
33. Coroutine Exception Handler try/catch ➡ Global “catch all” behaviour ➡ Coroutines have already completed => no recovery possible ➡ e.g. log exception, show error message ➡ handle the exception directly in the Coroutine ➡ possibility to recover ➡ e.g. retry operation or perform other arbitrary operations
34. There are 2 important aspects to consider when using try/catch !
35. 1. Keep the “Cancellation Mechanism” of Structured Concurrency in mind
36. rootScope.launch { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
37. rootScope.launch { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
38. rootScope.launch { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
39. rootScope.launch { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
40. rootScope.launch { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
41. rootScope.launch { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
42. rootScope.launch { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) } rootScope
43. rootScope.launch { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) } launch rootScope
44. rootScope.launch { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) } async launch rootScope async
45. launch async async rootScope rootScope.launch { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
46. launch async async rootScope rootScope.launch { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
47. launch async async rootScope rootScope.launch { val result1 = async { try { networkRequest1() } catch (e: Exception) { // Log exception null } } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
48. launch async async rootScope rootScope.launch { val result1 = async { try { networkRequest1() } catch (e: Exception) { // Log exception null } } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
49. rootScope launch async async rootScope.launch { val result1 = async { try { networkRequest1() } catch (e: Exception) { // Log exception null } } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
50. rootScope launch async async rootScope.launch { val result1 = async { try { networkRequest1() } catch (e: Exception) { // Log exception null } } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
51. rootScope.launch { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
52. val ceh = CoroutineExceptionHandler {…} rootScope.launch { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
53. val ceh = CoroutineExceptionHandler {…} rootScope.launch(ceh) { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
54. val ceh = CoroutineExceptionHandler {…} rootScope.launch(ceh) { val result1 = async { networkRequest1() } val result2 = async { networkRequest2() } display(awaitAll(result1, result2)) }
55. 2. You might catch a CancellationException and therefor your coroutine continues to run
56. val job = launch { println("Starting network request") delay(1000) println("Coroutine still running ... ") } delay(500) job.cancel()
57. val job = launch { println("Starting network request") delay(1000) println("Coroutine still running ... ") } delay(500) job.cancel()
58. val job = launch { println("Starting network request") delay(1000) println("Coroutine still running ... ") } delay(500) job.cancel()
59. val job = launch { println("Starting network request") delay(1000) println("Coroutine still running ... ") } delay(500) job.cancel()
60. val job = launch { println("Starting network request") delay(1000) println("Coroutine still running ... ") } delay(500) job.cancel()
61. val job = launch { println("Starting network request") delay(1000) println("Coroutine still running ... ") } delay(500) job.cancel() throws CancellationException after 500ms •>_ Starting network request
62. val job = launch { try { println("Starting network request") delay(1000) } catch (e: Exception) { // Log Exception println("Caught: $e") } println("Coroutine still running ... ") } delay(500) job.cancel()
63. val job = launch { try { println("Starting network request") delay(1000) } catch (e: Exception) { // Log Exception println("Caught: $e") } println("Coroutine still running ... ") } delay(500) job.cancel() •>_ Starting network request • Caught: JobCancellationException • Coroutine still running ...
64. val job = launch { try { println("Starting network request") delay(1000) } catch (e: HttpException) { // Log Exception println("Caught: $e") } println("Coroutine still running ... ") } delay(500) job.cancel()
65. val job = launch { try { println("Starting network request") delay(1000) } catch (e: Exception) { if (e is CancellationException) { throw e } } println("Coroutine still running ... ") } delay(500) job.cancel()
66. ExceptionHandling launch{} VS async{}
67. launch{} rootScope
68. launch{} rootScope Coroutine Exception Handler
69. fun main() { val rootScope = CoroutineScope(Job()) rootScope.async { throw Exception() } Thread.sleep(100) }
70. fun main() { val rootScope = CoroutineScope(Job()) rootScope.async { throw Exception() } Thread.sleep(100) }
71. fun main() { val rootScope = CoroutineScope(Job()) rootScope.async { throw Exception() } Thread.sleep(100) }
72. fun main() { val rootScope = CoroutineScope(Job()) rootScope.async { throw Exception() } Thread.sleep(100) } •>_ No Output
73. async{} rootScope
74. async{} rootScope Coroutine Exception Handler Deferred<T> re-thrown when calling .await()
75. fun main() { val rootScope = CoroutineScope(Job()) rootScope.async { throw Exception() } Thread.sleep(100) }
76. ... val deferredResult = rootScope.async { throw Exception() }
77. ... val deferredResult = rootScope.async { throw Exception() }
78. ... val deferredResult = rootScope.async { throw Exception() } deferredResult.await()
79. ... val deferredResult = rootScope.async { throw Exception() } deferredResult.await()
80. ... val deferredResult = rootScope.async { throw Exception() } rootScope.launch { deferredResult.await() }
81. ... val deferredResult = rootScope.async { throw Exception() } rootScope.launch { deferredResult.await() }
82. ... val deferredResult = rootScope.async { throw Exception() } rootScope.launch { try { deferredResult.await() } catch (exception: Exception) { println(“Handled $exception") } }
83. ... val deferredResult = rootScope.async { throw Exception() } rootScope.launch { try { deferredResult.await() } catch (exception: Exception) { println(“Handled $exception") } }
84. ... val deferredResult = rootScope.async { throw Exception() } val ceh = CoroutineExceptionHandler { ... } rootScope.launch(ceh) { deferredResult.await() }
85. ... val deferredResult = rootScope.async { throw Exception() } val ceh = CoroutineExceptionHandler { ... } rootScope.launch(ceh) { deferredResult.await() }
86. async{} Child Coroutines
87. ... val rootScope = CoroutineScope(Job()) rootScope.launch { async { throw Exception() } }
88. ... val rootScope = CoroutineScope(Job()) rootScope.launch { async { throw Exception() } }
89. ... val rootScope = CoroutineScope(Job()) rootScope.launch { async { throw Exception() } }
90. ... val rootScope = CoroutineScope(Job()) rootScope.launch { async { throw Exception() } }
91. ... val rootScope = CoroutineScope(Job()) rootScope.launch { async { throw Exception() } } async{} child Coroutine launch{} root Coroutine rootScope >_ Exception in thread “DefaultDispatcher- worker-2" java.lang.Exception
92. Scoping Function coroutineScope{}
93. ... rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } }
94. ... rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } }
95. ... rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } }
96. >_ Exception in thread “DefaultDispatcher-worker-2" java.lang.Exception ... rootScope.launch { try { launch { throw Exception() } } catch (exception: Exception) { println(“Handled $exception") } }
97. rootScope.launch { try { coroutineScope { launch { throw Exception() } } } catch (exception: Exception) { println(“Handled $exception") } }
98. rootScope.launch { try { coroutineScope { launch { throw Exception() } } } catch (exception: Exception) { println(“Handled $exception") } } >_ Handled exception
99. coroutineScope{} re-throws uncaught exceptions of its child coroutine
100. coroutineScope{} re-throws uncaught exceptions of its child Coroutines and so we can handle them with a try/catch
101. suspend fun suspendFunction() = coroutineScope { // suspend function body }
102. suspendFunction() suspend fun suspendFunction() = coroutineScope { // suspend function body }
103. suspendFunction() suspend fun suspendFunction() = coroutineScope { // suspend function body }
104. try { suspendFunction() } catch (exception: Exception) { println(“Handled $exception") } suspend fun suspendFunction() = coroutineScope { // suspend function body }
105. try { suspendFunction() } catch (exception: Exception) { println(“Handled $exception") } suspend fun suspendFunction() = coroutineScope { // suspend function body }
106. Scoping Function supervisorScope{}
107. supervisorScope{} a new independent child scope in our job hierarchy
108. rootScope.launch { // Coroutine 1 launch { // Coroutine 2 } supervisorScope { launch { // Coroutine 3 } launch { // Coroutine 4 } } }
109. rootScope.launch { // Coroutine 1 launch { // Coroutine 2 } supervisorScope { launch { // Coroutine 3 } launch { // Coroutine 4 } } } rootScope
110. rootScope.launch { // Coroutine 1 launch { // Coroutine 2 } supervisorScope { launch { // Coroutine 3 } launch { // Coroutine 4 } } } Coroutine 1 rootScope
111. rootScope.launch { // Coroutine 1 launch { // Coroutine 2 } supervisorScope { launch { // Coroutine 3 } launch { // Coroutine 4 } } } Coroutine 2 Coroutine 1 rootScope
112. rootScope.launch { // Coroutine 1 launch { // Coroutine 2 } supervisorScope { launch { // Coroutine 3 } launch { // Coroutine 4 } } } Coroutine 2 SupervisorJob Coroutine 1 rootScope
113. rootScope.launch { // Coroutine 1 launch { // Coroutine 2 } supervisorScope { launch { // Coroutine 3 } launch { // Coroutine 4 } } } Coroutine 2 Coroutine 3 SupervisorJob Coroutine 4 Coroutine 1 rootScope supervisorScope
114. Coroutine 2 Coroutine 3 Coroutine 4 Coroutine 1 SupervisorJob supervisorScope
115. Coroutine 2 Coroutine 3 Coroutine 4 Coroutine 1 SupervisorJob
116. Coroutine 2 Coroutine 3 Coroutine 4 Coroutine Exception Handler Coroutine Exception Handler Coroutine 1 SupervisorJob
117. Recap
118. 1) Exceptions can be handled directly in a Coroutine with a try-catch block. This way, the Coroutine doesn’t complete exceptionally. launch { try { throw Exception() } catch (exception: Exception) { println("Handled $exception") } } }
119. 2) If an exception is thrown in a Coroutine and not handled directly within the Coroutine with a try-catch block, the Coroutine completes exceptionally. launch { throw Exception() } Coroutine
120. 3) As a result, the exception is propagated up the job hierarchy until it reaches either the RootScope or a SupervisorJob. While the exceptions travels upwards, parent coroutines fail too and sibling coroutines get cancelled. Coroutine 2 Coroutine 4 SupervisorJob Coroutine 5 rootScope Coroutine 1 Coroutine 3 1 3 2 1
121. 4) When the root coroutine was started with launch{}, the exception will be passed to an installed CoroutineExceptionHandler. When the root coroutine was started with async{}, the exception is encapsulated in the Deferred object. async{} rootScope launch{} 1 Coroutine Exception Handler Deferred<T> re-thrown when calling.await() 2 1 2
122. 5) The scoping function coroutineScope{} re-throws uncaught exceptions of its child Coroutines and so we can handle them with a try/catch. launch { try { coroutineScope { launch { throw Exception() } } } catch (exception: Exception) { println(“Handled $exception") } }
123. 6) Keep in mind: • When your Coroutine is not completing exceptionally, parent and sibling coroutines won’t be canceled. • Suspend functions can throw a CancellationException at any point and by catching them, the Coroutine will keep on running.
124. Further Resources www.lukaslechner.com/coroutines-exception-handling-cheat-sheet www.lukaslechner.com/why-exception-handling-with-kotlin-coroutines-is-so- hard-and-how-to-successfully-master-it/ github.com/LukasLechnerDev/Kotlin-Coroutine-Use-Cases-on-Android
125. Further Resources www.lukaslechner.com/coroutines-on-android
126. Why Exception Handling in Kotlin Coroutines is hard … … and how to master it! Lukas Lechner Freelance Developer & Online Instructor www.lukaslechner.com November 17, 2020