Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
/*
* Copyright 2016-2017 JetBrains s.r.o.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package kotlinx.coroutines.experimental
import kotlinx.coroutines.experimental.internal.LockFreeLinkedListNode
import kotlin.coroutines.experimental.Continuation
import kotlin.coroutines.experimental.CoroutineContext
import kotlin.coroutines.experimental.intrinsics.suspendCoroutineOrReturn
import kotlin.coroutines.experimental.suspendCoroutine
// --------------- cancellable continuations ---------------
/**
* Cancellable continuation. Its job is _completed_ when it is resumed or cancelled.
* When [cancel] function is explicitly invoked, this continuation immediately resumes with [CancellationException] or
* with the specified cancel cause.
*
* Cancellable continuation has three states (as subset of [Job] states):
*
* | **State** | [isActive] | [isCompleted] | [isCancelled] |
* | ----------------------------------- | ---------- | ------------- | ------------- |
* | _Active_ (initial state) | `true` | `false` | `false` |
* | _Resumed_ (final _completed_ state) | `false` | `true` | `false` |
* | _Canceled_ (final _completed_ state)| `false` | `true` | `true` |
*
* Invocation of [cancel] transitions this continuation from _active_ to _cancelled_ state, while
* invocation of [resume] or [resumeWithException] transitions it from _active_ to _resumed_ state.
*
* A [cancelled][isCancelled] continuation implies that it is [completed][isCompleted].
*
* Invocation of [resume] or [resumeWithException] in _resumed_ state produces [IllegalStateException]
* but is ignored in _cancelled_ state.
*
* ```
* +-----------+ resume +---------+
* | Active | ----------> | Resumed |
* +-----------+ +---------+
* |
* | cancel
* V
* +-----------+
* | Cancelled |
* +-----------+
*
* ```
*/
public interface CancellableContinuation : Continuation, Job {
/**
* Returns `true` if this continuation was [cancelled][cancel].
*
* It implies that [isActive] is `false` and [isCompleted] is `true`.
*/
public override val isCancelled: Boolean
/**
* Tries to resume this continuation with a given value and returns non-null object token if it was successful,
* or `null` otherwise (it was already resumed or cancelled). When non-null object was returned,
* [completeResume] must be invoked with it.
*
* When [idempotent] is not `null`, this function performs _idempotent_ operation, so that
* further invocations with the same non-null reference produce the same result.
*
* @suppress **This is unstable API and it is subject to change.**
*/
public fun tryResume(value: T, idempotent: Any? = null): Any?
/**
* Tries to resume this continuation with a given exception and returns non-null object token if it was successful,
* or `null` otherwise (it was already resumed or cancelled). When non-null object was returned,
* [completeResume] must be invoked with it.
*
* @suppress **This is unstable API and it is subject to change.**
*/
public fun tryResumeWithException(exception: Throwable): Any?
/**
* Completes the execution of [tryResume] or [tryResumeWithException] on its non-null result.
*
* @suppress **This is unstable API and it is subject to change.**
*/
public fun completeResume(token: Any)
/**
* Makes this continuation cancellable. Use it with `holdCancellability` optional parameter to
* [suspendCancellableCoroutine] function. It throws [IllegalStateException] if invoked more than once.
*/
public fun initCancellability()
/**
* Resumes this continuation with a given [value] in the invoker thread without going though
* [dispatch][CoroutineDispatcher.dispatch] function of the [CoroutineDispatcher] in the [context].
* This function is designed to be used only by the [CoroutineDispatcher] implementations themselves.
* **It should not be used in general code**.
*/
public fun CoroutineDispatcher.resumeUndispatched(value: T)
/**
* Resumes this continuation with a given [exception] in the invoker thread without going though
* [dispatch][CoroutineDispatcher.dispatch] function of the [CoroutineDispatcher] in the [context].
* This function is designed to be used only by the [CoroutineDispatcher] implementations themselves.
* **It should not be used in general code**.
*/
public fun CoroutineDispatcher.resumeUndispatchedWithException(exception: Throwable)
}
/**
* Suspends coroutine similar to [suspendCoroutine], but provide an implementation of [CancellableContinuation] to
* the [block]. This function throws [CancellationException] if the coroutine is cancelled or completed while suspended.
*
* If [holdCancellability] optional parameter is `true`, then the coroutine is suspended, but it is not
* cancellable until [CancellableContinuation.initCancellability] is invoked.
*
* See [suspendAtomicCancellableCoroutine] for suspending functions that need *atomic cancellation*.
*/
public inline suspend fun suspendCancellableCoroutine(
holdCancellability: Boolean = false,
crossinline block: (CancellableContinuation) -> Unit
): T =
suspendCoroutineOrReturn { cont ->
val cancellable = CancellableContinuationImpl(cont, resumeMode = MODE_CANCELLABLE)
if (!holdCancellability) cancellable.initCancellability()
block(cancellable)
cancellable.getResult()
}
/**
* Suspends coroutine similar to [suspendCancellableCoroutine], but with *atomic cancellation*.
*
* When suspended function throws [CancellationException] it means that the continuation was not resumed.
* As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may
* continue to execute even after it was cancelled from the same thread in the case when the continuation
* was already resumed and was posted for execution to the thread's queue.
*/
public inline suspend fun suspendAtomicCancellableCoroutine(
holdCancellability: Boolean = false,
crossinline block: (CancellableContinuation) -> Unit
): T =
suspendCoroutineOrReturn { cont ->
val cancellable = CancellableContinuationImpl(cont, resumeMode = MODE_ATOMIC_DEFAULT)
if (!holdCancellability) cancellable.initCancellability()
block(cancellable)
cancellable.getResult()
}
/**
* Removes a given node on cancellation.
* @suppress **This is unstable API and it is subject to change.**
*/
public fun CancellableContinuation<*>.removeOnCancel(node: LockFreeLinkedListNode): DisposableHandle =
invokeOnCompletion(handler = RemoveOnCancel(this, node))
// --------------- implementation details ---------------
private class RemoveOnCancel(
cont: CancellableContinuation<*>,
val node: LockFreeLinkedListNode
) : JobNode>(cont) {
override fun invoke(reason: Throwable?) {
if (job.isCancelled)
node.remove()
}
override fun toString() = "RemoveOnCancel[$node]"
}
@PublishedApi
internal class CancellableContinuationImpl(
delegate: Continuation,
resumeMode: Int
) : AbstractContinuation(delegate, resumeMode), CancellableContinuation {
@Volatile // just in case -- we don't want an extra data race, even benign one
private var _context: CoroutineContext? = null // created on first need
public override val context: CoroutineContext
get() = _context ?: (delegate.context + this).also { _context = it }
override fun initCancellability() {
initParentJob(delegate.context[Job])
}
override fun tryResume(value: T, idempotent: Any?): Any? {
while (true) { // lock-free loop on state
val state = this.state // atomic read
when (state) {
is Incomplete -> {
val update: Any? = if (idempotent == null) value else
CompletedIdempotentResult(idempotent, value, state)
if (tryUpdateState(state, update)) return state
}
is CompletedIdempotentResult -> {
if (state.idempotentResume === idempotent) {
check(state.result === value) { "Non-idempotent resume" }
return state.token
} else
return null
}
else -> return null // cannot resume -- not active anymore
}
}
}
override fun tryResumeWithException(exception: Throwable): Any? {
while (true) { // lock-free loop on state
val state = this.state // atomic read
when (state) {
is Incomplete -> {
if (tryUpdateState(state, CompletedExceptionally(exception))) return state
}
else -> return null // cannot resume -- not active anymore
}
}
}
override fun completeResume(token: Any) {
completeUpdateState(token as Incomplete, state, resumeMode)
}
override fun CoroutineDispatcher.resumeUndispatched(value: T) {
val dc = delegate as? DispatchedContinuation
resumeImpl(value, if (dc?.dispatcher === this) MODE_UNDISPATCHED else resumeMode)
}
override fun CoroutineDispatcher.resumeUndispatchedWithException(exception: Throwable) {
val dc = delegate as? DispatchedContinuation
resumeImpl(CompletedExceptionally(exception), if (dc?.dispatcher === this) MODE_UNDISPATCHED else resumeMode)
}
@Suppress("UNCHECKED_CAST")
override fun getSuccessfulResult(state: Any?): T =
if (state is CompletedIdempotentResult) state.result as T else state as T
override fun nameString(): String =
"CancellableContinuation(${delegate.toDebugString()})"
}
private class CompletedIdempotentResult(
@JvmField val idempotentResume: Any?,
@JvmField val result: Any?,
@JvmField val token: JobSupport.Incomplete
) {
override fun toString(): String = "CompletedIdempotentResult[$result]"
}
