CompletionHandler

📌 Kotlin Coroutines의 CompletionHandler 이해하기

1. 개요

CompletionHandler는 Job.invokeOnCompletion 및 CancellableContinuation.invokeOnCancellation에 사용되는 핸들러로, 작업이 완료되거나 취소될 때 호출됩니다.

2. 함수 시그니처

typealias CompletionHandler = (cause: Throwable?) -> Unit

3. 매개변수 cause의 의미

• cause가 null인 경우: 작업이 정상적으로 완료되었거나, 취소되었지만 취소 원인이 없는 경우입니다.
• cause가 CancellationException의 인스턴스인 경우: 작업 또는 연속성이 정상적으로 취소된 경우로, 이는 오류로 간주되지 않으며, 특히 오류 로그에 기록되지 않아야 합니다.
• 그 외의 경우: 작업 또는 연속성이 실패한 경우입니다.

4. 주의사항

• 핸들러 함수는 예외를 throw해서는 안 됩니다. 만약 예외가 발생하면, 해당 예외는 CompletionHandlerException으로 래핑되어 handleCoroutineException에 전달되거나, 코루틴이 아닌 Job의 경우 단순히 throw되어 관련 없는 코드에 영향을 줄 수 있습니다.
• 핸들러 함수는 빠르고(non-blocking), 스레드 안전하게 작성되어야 합니다. 이 핸들러는 주변 코드와 동시에 호출될 수 있으며, 호출되는 실행 컨텍스트에 대한 보장이 없습니다.

5. 사용 예시

CompletionHandler를 사용하여 작업 완료 시 특정 동작을 수행하는 예시입니다:

import kotlinx.coroutines.*

fun main() = runBlocking {
    val job = launch {
        // 일부 작업 수행
        delay(1000L)
        println("작업 완료")
    }

    job.invokeOnCompletion { cause ->
        if (cause != null) {
            println("작업이 실패했습니다: ${cause.message}")
        } else {
            println("작업이 성공적으로 완료되었습니다.")
        }
    }

    job.join()
}

위 예시에서, job이 완료되면 invokeOnCompletion에 등록된 핸들러가 호출되어 작업의 성공 또는 실패 여부를 출력합니다.

📌 원본 출처

본 문서의 내용은 Kotlin 공식 문서를 참고하여 작성되었습니다. 자세한 내용은 아래 공식 문서를 통해 확인할 수 있습니다.

🔗 Kotlin Coroutines 공식 문서 - CompletionHandler