Registers a handler to be synchronously invoked on cancellation (regular or exceptional) of this continuation. When the continuation is already cancelled, the handler is immediately invoked with the cancellation exception. Otherwise, the handler will be invoked as soon as this continuation is cancelled.
The installed handler should not throw any exceptions. If it does, they will get caught, wrapped into a CompletionHandlerException and processed as an uncaught exception in the context of the current coroutine (see CoroutineExceptionHandler).
This handler is also called when this continuation resumes normally (with a value) and then is cancelled while waiting to be dispatched. More generally speaking, this handler is called whenever the caller of suspendCancellableCoroutine is getting a CancellationException.
A typical example for
invokeOnCancellation usage is given in the documentation for the suspendCancellableCoroutine function.
Note: Implementation of
CompletionHandler must be fast, non-blocking, and thread-safe. This
handler can be invoked concurrently with the surrounding code. There is no guarantee on the execution context in which the
handler will be invoked.