This section covers coroutine cancellation and timeouts.

    In a long-running application you might need fine-grained control on your background coroutines. For example, a user might have closed the page that launched a coroutine and now its result is no longer needed and its operation can be cancelled. The function returns a Job that can be used to cancel the running coroutine:

    It produces the following output:

    1. job: I'm sleeping 0 ...
    2. job: I'm sleeping 1 ...
    3. job: I'm sleeping 2 ...
    4. main: I'm tired of waiting!
    5. main: Now I can quit.

    As soon as main invokes job.cancel, we don’t see any output from the other coroutine because it was cancelled. There is also a extension function cancelAndJoin that combines and join invocations.

    Cancellation is cooperative

    Coroutine cancellation is cooperative. A coroutine code has to cooperate to be cancellable. All the suspending functions in kotlinx.coroutines are cancellable. They check for cancellation of coroutine and throw CancellationException when cancelled. However, if a coroutine is working in a computation and does not check for cancellation, then it cannot be cancelled, like the following example shows:

    1. import kotlinx.coroutines.*
    3. fun main() = runBlocking {
    4. //sampleStart
    5.     val startTime = System.currentTimeMillis()
    6.     val job = launch(Dispatchers.Default) {
    7.         var nextPrintTime = startTime
    8.         var i = 0
    9.         while (i < 5) { // computation loop, just wastes CPU
    10.             // print a message twice a second
    11.             if (System.currentTimeMillis() >= nextPrintTime) {
    12.                 println("job: I'm sleeping ${i++} ...")
    13.                 nextPrintTime += 500L
    14.             }
    15.         }
    16.     }
    17.     delay(1300L) // delay a bit
    18.     println("main: I'm tired of waiting!")
    19.     job.cancelAndJoin() // cancels the job and waits for its completion
    20.     println("main: Now I can quit.")
    21. //sampleEnd    
    22. }

    You can get the full code .

    Run it to see that it continues to print “I’m sleeping” even after cancellation until the job completes by itself after five iterations.

    There are two approaches to making computation code cancellable. The first one is to periodically invoke a suspending function that checks for cancellation. There is a yield function that is a good choice for that purpose. The other one is to explicitly check the cancellation status. Let us try the latter approach.

    Replace while (i < 5) in the previous example with while (isActive) and rerun it.

    1. import kotlinx.coroutines.*
    3. fun main() = runBlocking {
    4. //sampleStart
    5.     val startTime = System.currentTimeMillis()
    6.     val job = launch(Dispatchers.Default) {
    7.         var nextPrintTime = startTime
    8.         while (isActive) { // cancellable computation loop
    9.             // print a message twice a second
    10.             if (System.currentTimeMillis() >= nextPrintTime) {
    11.                 println("job: I'm sleeping ${i++} ...")
    12.                 nextPrintTime += 500L
    13.             }
    14.         }
    15.     }
    16.     delay(1300L) // delay a bit
    17.     println("main: I'm tired of waiting!")
    18.     job.cancelAndJoin() // cancels the job and waits for its completion
    20. //sampleEnd    
    21. }

    As you can see, now this loop is cancelled. is an extension property available inside the coroutine via the CoroutineScope object.

    Closing resources with finally

    Cancellable suspending functions throw CancellationException on cancellation which can be handled in the usual way. For example, try {...} finally {...} expression and Kotlin use function execute their finalization actions normally when a coroutine is cancelled:

    Both and cancelAndJoin wait for all finalization actions to complete, so the example above produces the following output:

    1. job: I'm sleeping 0 ...
    2. job: I'm sleeping 1 ...
    3. job: I'm sleeping 2 ...
    4. main: I'm tired of waiting!
    5. job: I'm running finally
    6. main: Now I can quit.

    Any attempt to use a suspending function in the finally block of the previous example causes , because the coroutine running this code is cancelled. Usually, this is not a problem, since all well-behaving closing operations (closing a file, cancelling a job, or closing any kind of a communication channel) are usually non-blocking and do not involve any suspending functions. However, in the rare case when you need to suspend in a cancelled coroutine you can wrap the corresponding code in withContext(NonCancellable) {...} using withContext function and context as the following example shows:

    1. import kotlinx.coroutines.*
    3. fun main() = runBlocking {
    4. //sampleStart
    5.     val job = launch {
    6.         try {
    7.             repeat(1000) { i ->
    8.                 println("job: I'm sleeping $i ...")
    9.                 delay(500L)
    10.             }
    11.         } finally {
    12.             withContext(NonCancellable) {
    13.                 println("job: I'm running finally")
    14.                 delay(1000L)
    15.                 println("job: And I've just delayed for 1 sec because I'm non-cancellable")
    16.             }
    17.         }
    18.     }
    19.     delay(1300L) // delay a bit
    20.     println("main: I'm tired of waiting!")
    21.     job.cancelAndJoin() // cancels the job and waits for its completion
    22.     println("main: Now I can quit.")
    23. //sampleEnd    
    24. }

    You can get the full code here.

    Timeout

    The most obvious practical reason to cancel execution of a coroutine is because its execution time has exceeded some timeout. While you can manually track the reference to the corresponding Job and launch a separate coroutine to cancel the tracked one after delay, there is a ready to use function that does it. Look at the following example:

    1. import kotlinx.coroutines.*
    3. fun main() = runBlocking {
    4. //sampleStart
    5.     withTimeout(1300L) {
    6.             println("I'm sleeping $i ...")
    7.             delay(500L)
    8.         }
    9.     }
    10. //sampleEnd
    11. }

    You can get the full code here.

    It produces the following output:

    The TimeoutCancellationException that is thrown by is a subclass of CancellationException. We have not seen its stack trace printed on the console before. That is because inside a cancelled coroutine CancellationException is considered to be a normal reason for coroutine completion. However, in this example we have used right inside the main function.

    1. import kotlinx.coroutines.*
    3. fun main() = runBlocking {
    4. //sampleStart
    5.     val result = withTimeoutOrNull(1300L) {
    6.         repeat(1000) { i ->
    7.             println("I'm sleeping $i ...")
    8.             delay(500L)
    9.         }
    10.         "Done" // will get cancelled before it produces this result
    11.     }
    12.     println("Result is $result")
    13. //sampleEnd
    14. }

    There is no longer an exception when running this code:

    1. I'm sleeping 0 ...
    2. I'm sleeping 1 ...
    3. I'm sleeping 2 ...
    4. Result is null

    The timeout event in is asynchronous with respect to the code running in its block and may happen at any time, even right before the return from inside of the timeout block. Keep this in mind if you open or acquire some resource inside the block that needs closing or release outside of the block.

    For example, here we imitate a closeable resource with the Resource class, that simply keeps track of how many times it was created by incrementing the acquired counter and decrementing this counter from its close function. Let us run a lot of coroutines with the small timeout try acquire this resource from inside of the withTimeout block after a bit of delay and release it from outside.

    1. import kotlinx.coroutines.*
    3. //sampleStart
    4. var acquired = 0
    6. class Resource {
    7.     init { acquired++ } // Acquire the resource
    8.     fun close() { acquired-- } // Release the resource
    9. }
    11. fun main() {
    12.     runBlocking {
    13.         repeat(100_000) { // Launch 100K coroutines
    14.             launch { 
    15.                 val resource = withTimeout(60) { // Timeout of 60 ms
    16.                     delay(50) // Delay for 50 ms
    17.                     Resource() // Acquire a resource and return it from withTimeout block     
    18.                 }
    19.                 resource.close() // Release the resource
    20.             }
    21.         }
    22.     }
    23.     // Outside of runBlocking all coroutines have completed
    24.     println(acquired) // Print the number of resources still acquired
    25. }

    You can get the full code here.

    If you run the above code you’ll see that it does not always print zero, though it may depend on the timings of your machine you may need to tweak timeouts in this example to actually see non-zero values.

    Note, that incrementing and decrementing counter here from 100K coroutines is completely safe, since it always happens from the same main thread. More on that will be explained in the next chapter on coroutine context.

    To workaround this problem you can store a reference to the resource in the variable as opposed to returning it from the withTimeout block.

    This example always prints zero. Resources do not leak.