1 /* 2 * Copyright 2016-2021 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. 3 */ 4 5 package kotlinx.coroutines 6 7 import kotlinx.coroutines.selects.* 8 9 /** 10 * Deferred value is a non-blocking cancellable future — it is a [Job] with a result. 11 * 12 * It is created with the [async][CoroutineScope.async] coroutine builder or via the constructor of [CompletableDeferred] class. 13 * It is in [active][isActive] state while the value is being computed. 14 * 15 * `Deferred` has the same state machine as the [Job] with additional convenience methods to retrieve 16 * the successful or failed result of the computation that was carried out. The result of the deferred is 17 * available when it is [completed][isCompleted] and can be retrieved by [await] method, which throws 18 * an exception if the deferred had failed. 19 * Note that a _cancelled_ deferred is also considered as completed. 20 * The corresponding exception can be retrieved via [getCompletionExceptionOrNull] from a completed instance of deferred. 21 * 22 * Usually, a deferred value is created in _active_ state (it is created and started). 23 * However, the [async][CoroutineScope.async] coroutine builder has an optional `start` parameter that creates a deferred value in _new_ state 24 * when this parameter is set to [CoroutineStart.LAZY]. 25 * Such a deferred can be be made _active_ by invoking [start], [join], or [await]. 26 * 27 * A deferred value is a [Job]. A job in the 28 * [coroutineContext](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.coroutines/coroutine-context.html) 29 * of [async][CoroutineScope.async] builder represents the coroutine itself. 30 * 31 * All functions on this interface and on all interfaces derived from it are **thread-safe** and can 32 * be safely invoked from concurrent coroutines without external synchronization. 33 * 34 * **`Deferred` interface and all its derived interfaces are not stable for inheritance in 3rd party libraries**, 35 * as new methods might be added to this interface in the future, but is stable for use. 36 */ 37 public interface Deferred<out T> : Job { 38 39 /** 40 * Awaits for completion of this value without blocking a thread and resumes when deferred computation is complete, 41 * returning the resulting value or throwing the corresponding exception if the deferred was cancelled. 42 * 43 * This suspending function is cancellable. 44 * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function 45 * immediately resumes with [CancellationException]. 46 * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was 47 * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details. 48 * 49 * This function can be used in [select] invocation with [onAwait] clause. 50 * Use [isCompleted] to check for completion of this deferred value without waiting. 51 */ awaitnull52 public suspend fun await(): T 53 54 /** 55 * Clause for [select] expression of [await] suspending function that selects with the deferred value when it is 56 * resolved. The [select] invocation fails if the deferred value completes exceptionally (either fails or 57 * it cancelled). 58 */ 59 public val onAwait: SelectClause1<T> 60 61 /** 62 * Returns *completed* result or throws [IllegalStateException] if this deferred value has not 63 * [completed][isCompleted] yet. It throws the corresponding exception if this deferred was [cancelled][isCancelled]. 64 * 65 * This function is designed to be used from [invokeOnCompletion] handlers, when there is an absolute certainty that 66 * the value is already complete. See also [getCompletionExceptionOrNull]. 67 * 68 * **Note: This is an experimental api.** This function may be removed or renamed in the future. 69 */ 70 @ExperimentalCoroutinesApi 71 public fun getCompleted(): T 72 73 /** 74 * Returns *completion exception* result if this deferred was [cancelled][isCancelled] and has [completed][isCompleted], 75 * `null` if it had completed normally, or throws [IllegalStateException] if this deferred value has not 76 * [completed][isCompleted] yet. 77 * 78 * This function is designed to be used from [invokeOnCompletion] handlers, when there is an absolute certainty that 79 * the value is already complete. See also [getCompleted]. 80 * 81 * **Note: This is an experimental api.** This function may be removed or renamed in the future. 82 */ 83 @ExperimentalCoroutinesApi 84 public fun getCompletionExceptionOrNull(): Throwable? 85 } 86