【Coroutines】キャンセルとタイムアウト

ソース記事は[こちら](https://kotlinlang.org/docs/cancellation-and-timeouts.html)
このセクションはコルーチンのキャンセルとタイムアウトをカバーしている。
## コルーチンの実行のキャンセル
長時間実行するアプリケーションにおいて、そのバックグラウンドのコルーチンをきめ細かく制御する必要があるかるかもしれない。例えば、あるユーザーはコルーチンを起動したページを閉じ、その結果はもう必要なく、操作をキャンセルするかもしれない。[launch](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/launch.html)関数は、実行しているコルーチンをキャンセルするために使うことができる[Job](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/index.html)を返却する。
```Kotlin
import kotlinx.coroutines.*

fun main() = runBlocking {
    val job = launch {
        repeat(1000) { i ->
            println("job: I'm sleeping $i ...")
            delay(500L)
        }
    }
    delay(1300L) // delay a bit
    println("main: I'm tired of waiting!")
    job.cancel() // cancels the job
    job.join() // waits for job's completion 
    println("main: Now I can quit.") 
}
```
次のような出力となる。
```
job: I'm sleeping 0 ...
job: I'm sleeping 1 ...
job: I'm sleeping 2 ...
main: I'm tired of waiting!
main: Now I can quit.
```
mainから`job.cancel`が呼び出されるとすぐに、ジョブはキャンセルされたため、ほかのコルーチンからの出力は見られなくなる。[cancel](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/cancel.html)と[join](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/join.html)を組み合わせる[cancelAndJoin](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/cancel-and-join.html) [Job](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/index.html)拡張関数もある。
## キャンセルは協調的
コルーチンのキャンセルは協調的である。コルーチンのコードは、キャンセルに対して協調的でなければならない。`kotlinx.coroutines`内のすべてのsuspend関数は、キャンセル可能である。それらは、コルーチンのキャンセルをチェックして、キャンセルされると、[CancellationException](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-cancellation-exception/index.html)をスローする。しかし、コルーチンが計算を行っており、キャンセルのチェックをしていない場合、キャンセルすることはできない。次の例に示すように。
```Kotlin
import kotlinx.coroutines.*

fun main() = runBlocking {
    val startTime = System.currentTimeMillis()
    val job = launch(Dispatchers.Default) {
        var nextPrintTime = startTime
        var i = 0
        while (i < 5) { // computation loop, just wastes CPU
            // print a message twice a second
            if (System.currentTimeMillis() >= nextPrintTime) {
                println("job: I'm sleeping ${i++} ...")
                nextPrintTime += 500L
            }
        }
    }
    delay(1300L) // delay a bit
    println("main: I'm tired of waiting!")
    job.cancelAndJoin() // cancels the job and waits for its completion
    println("main: Now I can quit.")  
    // ※次のような出力になる
    // job: I'm sleeping 0 ...
    // job: I'm sleeping 1 ...
    // job: I'm sleeping 2 ...
    // main: I'm tired of waiting!
    // job: I'm sleeping 3 ...
    // job: I'm sleeping 4 ...
    // main: Now I can quit.  
}
```
これを実行し、キャンセルの後でも"I'm sleeping"が出力され続け、5回の繰り返しの後、自分自身によってジョブが完了することを確認しよう。
同じ問題が、[CancellationException](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-cancellation-exception/index.html)をキャッチし、再スローしないことによっても見られる。
```Kotlin
import kotlinx.coroutines.*

fun main() = runBlocking {
    val job = launch(Dispatchers.Default) {
        repeat(5) { i ->
            try {
                // print a message twice a second
                println("job: I'm sleeping $i ...")
                delay(500)
            } catch (e: Exception) {
                // log the exception
                println(e)
            }
        }
    }
    delay(1300L) // delay a bit
    println("main: I'm tired of waiting!")
    job.cancelAndJoin() // cancels the job and waits for its completion
    println("main: Now I can quit.")    
    // ※次のような出力になる
    // job: I'm sleeping 0 ...
    // job: I'm sleeping 1 ...
    // job: I'm sleeping 2 ...
    // main: I'm tired of waiting!
    // kotlinx.coroutines.JobCancellationException: StandaloneCoroutine was cancelled;     
    // job="coroutine#2":StandaloneCoroutine{Cancelling}@724c07e6
    // job: I'm sleeping 3 ...
    // kotlinx.coroutines.JobCancellationException: StandaloneCoroutine was cancelled;
    // job="coroutine#2":StandaloneCoroutine{Cancelling}@724c07e6
    // job: I'm sleeping 4 ...
    // kotlinx.coroutines.JobCancellationException: StandaloneCoroutine was cancelled;
    // job="coroutine#2":StandaloneCoroutine{Cancelling}@724c07e6
    // main: Now I can quit.
}
```
`Exception`をキャッチすることはアンチパターンであるが、この問題はより巧妙な方法で表面化するかもしれない。例えば、[`runcatching`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/run-catching.html)関数を使って、[CancellationException](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-cancellation-exception/index.html)を再スローしないときのような場合である。
## 計算コードをキャンセル可能にする
計算コードをキャンセル可能にするには、二つのアプローチがある。一つは、キャンセルを定期的にチェックするsuspend関数を呼び出すことである。その目的のための良い選択肢として、[yield](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/yield.html)関数がある。もう一つの方法は、明示的にキャンセルステータスをチェックすることである。後者のアプローチを試してみよう。
以前の例で`while (i < 5)`を`while (isActive)`に置き換え、それを返却するようにする。
```Kotlin
import kotlinx.coroutines.*

fun main() = runBlocking {
    val startTime = System.currentTimeMillis()
    val job = launch(Dispatchers.Default) {
        var nextPrintTime = startTime
        var i = 0
        while (isActive) { // cancellable computation loop
            // print a message twice a second
            if (System.currentTimeMillis() >= nextPrintTime) {
                println("job: I'm sleeping ${i++} ...")
                nextPrintTime += 500L
            }
        }
    }
    delay(1300L) // delay a bit
    println("main: I'm tired of waiting!")
    job.cancelAndJoin() // cancels the job and waits for its completion
    println("main: Now I can quit.")    
}
// ※以下の出力となる
// job: I'm sleeping 0 ...
// job: I'm sleeping 1 ...
// job: I'm sleeping 2 ...
// main: I'm tired of waiting!
// main: Now I can quit
```
ご覧のように、現在はこのループはキャンセル可能である。`isActive`は[CoruotineScope](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-coroutine-scope/index.html)オブジェクト経由のコルーチンの内部で利用可能な、拡張プロパティである。
## finallyでリソースを閉じる
キャンセル可能なsuspend関数は、キャンセルにおいて[CancellationException](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-cancellation-exception/index.html)をスローするが、それは通常のの方法で扱うことができる。例えば、`try {...} finally {...}`式とKotlinの`use`関数はコルーチンがキャンセルされるときに、通常通りに完了のふるまいを実行する。
```Kotlin
import kotlinx.coroutines.*

fun main() = runBlocking {
    val job = launch {
        try {
            repeat(1000) { i ->
                println("job: I'm sleeping $i ...")
                delay(500L)
            }
        } finally {
            println("job: I'm running finally")
        }
    }
    delay(1300L) // delay a bit
    println("main: I'm tired of waiting!")
    job.cancelAndJoin() // cancels the job and waits for its completion
    println("main: Now I can quit.")    
}
```
[join](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/join.html)と[cancelAndAndJoin](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/cancel-and-join.html)は両方とも、すべての完了動作が完了するのを待つため、上記の例では、次のような出力が生成される。
```
job: I'm sleeping 0 ...
job: I'm sleeping 1 ...
job: I'm sleeping 2 ...
main: I'm tired of waiting!
job: I'm running finally
main: Now I can quit.
```
## キャンセル不可能なブロックの実行
前回の例の`finally`ブロックでsuspend関数を使おうとすると、[CancellationException](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-cancellation-exception/index.html)を引き起こす。なぜならそのコードを実行しているコルーチンは、キャンセルされているからである。大抵は、これは問題ではない。というのも、すべての行儀の良い終了操作(ファイルのクローズ、ジョブのキャンセル、何らかの通信チャンネルのクローズ)は、大抵ノンブロッキングで、suspend関数を含まない。しかしレアケースでキャンセルされたコルーチンで、一時停止が必要なとき、次の例で見えるように、[withContext]()関数と、[NonCancellable]()コンテキストを使って、対応するコードを`withContext(NonCancellable) {...}`でラップすることができる。
```Kotlin
import kotlinx.coroutines.*

fun main() = runBlocking {
    val job = launch {
        try {
            repeat(1000) { i ->
                println("job: I'm sleeping $i ...")
                delay(500L)
            }
        } finally {
            withContext(NonCancellable) {
                println("job: I'm running finally")
                delay(1000L)
                println("job: And I've just delayed for 1 sec because I'm non-cancellable")
            }
        }
    }
    delay(1300L) // delay a bit
    println("main: I'm tired of waiting!")
    job.cancelAndJoin() // cancels the job and waits for its completion
    println("main: Now I can quit.")
}
// ※次のような出力になる
// job: I'm sleeping 0 ...
// job: I'm sleeping 1 ...
// job: I'm sleeping 2 ...
// main: I'm tired of waiting!
// job: I'm running finally
// job: And I've just delayed for 1 sec because I'm non-cancellable
// main: Now I can quit.
```
## タイムアウト
コルーチンの実行をキャンセルするもっとも明らかで実用的な理由は、その実行のために、いくつかのタイムアウトを超過するということである。手動で対応する[Job](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-job/index.html)への参照を追跡して、遅らせて追跡しているものをキャンセルする別のコルーチンを起動することもできるが、それを行う[withTimeout](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-timeout.html)をすぐに使うこともできる。次の例を見てみよう。
```Kotlin
import kotlinx.coroutines.*

fun main() = runBlocking {
    withTimeout(1300L) {
        repeat(1000) { i ->
            println("I'm sleeping $i ...")
            delay(500L)
        }
    }
}
```
これは次の出力を生成する。
```
I'm sleeping 0 ...
I'm sleeping 1 ...
I'm sleeping 2 ...
Exception in thread "main" kotlinx.coroutines.TimeoutCancellationException: Timed out waiting for 1300 ms
```
[withTimeout](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-timeout.html)によってスローされる`TimeoutCancellationException`は、[CancellationException](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-cancellation-exception/index.html)のサブクラスである。前のコンソールに表示されたスタックトレースを見ていない。それはキャンセルされたコルーチンの内部では、`CancellationException`はコルーチンの完了にとって通常の理由とみなされているからである。しかし、この例では`withTimeout`は`main`関数のすぐ内側で使っていた。
キャンセルは単なる例外であるため、すべてのリソースは通常の方法でクローズされる。何らかのタイムアウトについて、特に追加のふるまいが必要な場合は、タイムアウトを含むコードを`try {...} catch (e: TimeoutCancellationException) {...}`にラップするか、[withTimeoutOrNull](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-timeout-or-null.html)関数を使うことができ、それは[withTimeout](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-timeout.html)に似ているが、例外をスローする代わりに、タイムアウトでnullを返却する。
```Kotlin
import kotlinx.coroutines.*

fun main() = runBlocking {
    val result = withTimeoutOrNull(1300L) {
        repeat(1000) { i ->
            println("I'm sleeping $i ...")
            delay(500L)
        }
        "Done" // will get cancelled before it produces this result
    }
    println("Result is $result")
}
```
このコードを実行するともう例外は存在しない。
```
I'm sleeping 0 ...
I'm sleeping 1 ...
I'm sleeping 2 ...
Result is null
```
## 非同期のタイムアウトとリソース
[withTimeout](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/with-timeout.html)内のタイムアウトイベントは、そのブロックで実行しているコードに関して非同期であり、いつでも、タイムアウトブロックの内部から戻る直前でさえ、発生する可能性がある。もしブロックの内部で、あるリソースを開いたり獲得し、かつブロックの外側ではクローズまたは解放する必要がある場合は、このことを覚えておいてほしい。
例えば、ここに`Resource`クラスでクローズできるリソースを模倣している。それは、`acquired`カウンタを増加することで作成され、`close`関数からカウンタを減少させる、その回数を単純に追跡する。短いタイムアウトを持つ多くのコルーチンを実行し、`withTimeout`ブロックの内側からリソースを獲得し、少し後で外側からそれを解放してみよう。
```Kotlin
import kotlinx.coroutines.*

var acquired = 0

class Resource {
    init { acquired++ } // リソースを獲得する
    fun close() { acquired-- } // リソースを解放する
}

fun main() {
    runBlocking {
        repeat(100_000) { // 10万個のコルーチンを起動する。
            launch { 
                val resource = withTimeout(60) { // タイムアウト60 ms
                    delay(50) // ディレイ50 ms
                    Resource() // リソースを獲得し、withTimeoutブロックからそれを返却する     
                }
                resource.close() // リソースを解放する
            }
        }
    }
    // runBlockingの外側ですべてのコルーチンが完了する
    println(acquired) // リソースがまだ獲得されている数を出力する
}
```
上記のコードを実行すると、常にゼロを出力しないことがわかるだろう。それはPCのタイミングに依存するかもしれず、実際にゼロ以外の値を見るためにこの例のタイムアウトを微調整する必要があるかもしれないが。

::: note
留意すべきは、ここで10万個のコルーチンから`acquired`カウンタを増加減少することは、完全に安全であるということである。というのは、それは常に同じメインスレッドから発生しているためである。そのことに関してはコルーチンコンテキストの章でより詳しく説明されるだろう。
:::
問題を回避するため、リソースへの参照を、`withTimeout`ブロックから返却するのとは違って、変数に保存することができる。
```Kotlin
import kotlinx.coroutines.*

var acquired = 0

class Resource {
    init { acquired++ } // リソースを獲得する
    fun close() { acquired-- } // リソースを解放する
}

fun main() {
    runBlocking {
        repeat(100_000) { // 10万個のコルーチンを起動する。
            launch { 
                var resource: Resource? = null // まだ獲得されていない
                try {
                    withTimeout(60) { // タイムアウト60 ms
                        delay(50) // ディレイ50 ms
                        resource = Resource() // 獲得した場合、変数にリソースを保存する      
                    }
                    // ここでリソースに関して他のことをすることができる
                } finally {  
                    resource?.close() // 獲得できた場合、リソースを解放する
                }
            }
        }
    }
    // runBlockingの外側ですべてのコルーチンが完了する
    println(acquired) // リソースがまだ獲得されている数を出力する
}
```
この例では常にゼロを出力する。リソースはリークしない。