1 package kotlinx.coroutines 2 3 /** 4 * Handler for [Job.invokeOnCompletion] and [CancellableContinuation.invokeOnCancellation]. 5 * 6 * The meaning of `cause` that is passed to the handler is: 7 * - It is `null` if the job has completed normally or the continuation was cancelled without a `cause`. 8 * - It is an instance of [CancellationException] if the job or the continuation was cancelled _normally_. 9 * **It should not be treated as an error**. In particular, it should not be reported to error logs. 10 * - Otherwise, the job or the continuation had _failed_. 11 * 12 * A function used for this should not throw any exceptions. 13 * If it does, they will get caught, wrapped into [CompletionHandlerException], and then either 14 * - passed to [handleCoroutineException] for [CancellableContinuation.invokeOnCancellation] 15 * and, for [Job] instances that are coroutines, [Job.invokeOnCompletion], or 16 * - for [Job] instances that are not coroutines, simply thrown, potentially crashing unrelated code. 17 * 18 * Functions used for this must be fast, non-blocking, and thread-safe. 19 * This handler can be invoked concurrently with the surrounding code. 20 * There is no guarantee on the execution context in which the function is invoked. 21 * 22 * **Note**: This type is a part of internal machinery that supports parent-child hierarchies 23 * and allows for implementation of suspending functions that wait on the Job's state. 24 * This type should not be used in general application code. 25 */ 26 // TODO: deprecate. This doesn't seem better than a simple function type. 27 public typealias CompletionHandler = (cause: Throwable?) -> Unit 28