| /* |
| * Copyright 2016-2020 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. |
| */ |
| |
| package kotlinx.coroutines |
| |
| import kotlinx.coroutines.selects.* |
| |
| /** |
| * Deferred value is a non-blocking cancellable future — it is a [Job] with a result. |
| * |
| * It is created with the [async][CoroutineScope.async] coroutine builder or via the constructor of [CompletableDeferred] class. |
| * It is in [active][isActive] state while the value is being computed. |
| * |
| * `Deferred` has the same state machine as the [Job] with additional convenience methods to retrieve |
| * the successful or failed result of the computation that was carried out. The result of the deferred is |
| * available when it is [completed][isCompleted] and can be retrieved by [await] method, which throws |
| * an exception if the deferred had failed. |
| * Note that a _cancelled_ deferred is also considered as completed. |
| * The corresponding exception can be retrieved via [getCompletionExceptionOrNull] from a completed instance of deferred. |
| * |
| * Usually, a deferred value is created in _active_ state (it is created and started). |
| * However, the [async][CoroutineScope.async] coroutine builder has an optional `start` parameter that creates a deferred value in _new_ state |
| * when this parameter is set to [CoroutineStart.LAZY]. |
| * Such a deferred can be be made _active_ by invoking [start], [join], or [await]. |
| * |
| * A deferred value is a [Job]. A job in the |
| * [coroutineContext](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.coroutines/coroutine-context.html) |
| * of [async][CoroutineScope.async] builder represents the coroutine itself. |
| * |
| * All functions on this interface and on all interfaces derived from it are **thread-safe** and can |
| * be safely invoked from concurrent coroutines without external synchronization. |
| * |
| * **`Deferred` interface and all its derived interfaces are not stable for inheritance in 3rd party libraries**, |
| * as new methods might be added to this interface in the future, but is stable for use. |
| */ |
| public interface Deferred<out T> : Job { |
| |
| /** |
| * Awaits for completion of this value without blocking a thread and resumes when deferred computation is complete, |
| * returning the resulting value or throwing the corresponding exception if the deferred was cancelled. |
| * |
| * This suspending function is cancellable. |
| * If the [Job] of the current coroutine is cancelled or completed while this suspending function is waiting, this function |
| * immediately resumes with [CancellationException]. |
| * There is a **prompt cancellation guarantee**. If the job was cancelled while this function was |
| * suspended, it will not resume successfully. See [suspendCancellableCoroutine] documentation for low-level details. |
| * |
| * This function can be used in [select] invocation with [onAwait] clause. |
| * Use [isCompleted] to check for completion of this deferred value without waiting. |
| */ |
| public suspend fun await(): T |
| |
| /** |
| * Clause for [select] expression of [await] suspending function that selects with the deferred value when it is |
| * resolved. The [select] invocation fails if the deferred value completes exceptionally (either fails or |
| * it cancelled). |
| */ |
| public val onAwait: SelectClause1<T> |
| |
| /** |
| * Returns *completed* result or throws [IllegalStateException] if this deferred value has not |
| * [completed][isCompleted] yet. It throws the corresponding exception if this deferred was [cancelled][isCancelled]. |
| * |
| * This function is designed to be used from [invokeOnCompletion] handlers, when there is an absolute certainty that |
| * the value is already complete. See also [getCompletionExceptionOrNull]. |
| * |
| * **Note: This is an experimental api.** This function may be removed or renamed in the future. |
| */ |
| @ExperimentalCoroutinesApi |
| public fun getCompleted(): T |
| |
| /** |
| * Returns *completion exception* result if this deferred was [cancelled][isCancelled] and has [completed][isCompleted], |
| * `null` if it had completed normally, or throws [IllegalStateException] if this deferred value has not |
| * [completed][isCompleted] yet. |
| * |
| * This function is designed to be used from [invokeOnCompletion] handlers, when there is an absolute certainty that |
| * the value is already complete. See also [getCompleted]. |
| * |
| * **Note: This is an experimental api.** This function may be removed or renamed in the future. |
| */ |
| @ExperimentalCoroutinesApi |
| public fun getCompletionExceptionOrNull(): Throwable? |
| } |