Job.onCompletion is renamed to Job.invokeOnCompletion for consistency
diff --git a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CancellableContinuation.kt b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CancellableContinuation.kt
index b42c210..05dbe72 100644
--- a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CancellableContinuation.kt
+++ b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CancellableContinuation.kt
@@ -125,7 +125,7 @@
* @suppress **This is unstable API and it is subject to change.**
*/
public fun CancellableContinuation<*>.removeOnCancel(node: LockFreeLinkedListNode): Job.Registration =
- onCompletion(RemoveOnCancel(this, node))
+ invokeOnCompletion(RemoveOnCancel(this, node))
// --------------- implementation details ---------------
diff --git a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Deferred.kt b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Deferred.kt
index c6bfdc0..c3954d3 100644
--- a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Deferred.kt
+++ b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Deferred.kt
@@ -71,7 +71,7 @@
* [completed][isCompleted] yet. It throws the corresponding exception if this deferred has
* [completed exceptionally][isCompletedExceptionally].
*
- * This function is designed to be used from [onCompletion] handlers, when there is an absolute certainty that
+ * This function is designed to be used from [invokeOnCompletion] handlers, when there is an absolute certainty that
* the value is already complete.
*/
public fun getCompleted(): T
@@ -142,7 +142,7 @@
@Suppress("UNCHECKED_CAST")
private suspend fun awaitSuspend(): T = suspendCancellableCoroutine { cont ->
- cont.unregisterOnCompletion(onCompletion {
+ cont.unregisterOnCompletion(invokeOnCompletion {
val state = getState()
check(state !is Incomplete)
if (state is CompletedExceptionally)
diff --git a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt
index 95825cb..8e474da 100644
--- a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt
+++ b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt
@@ -96,15 +96,20 @@
fun getCompletionException(): Throwable
/**
- * Registers completion handler. The action depends on the state of this job.
- * When job is cancelled with [cancel], then the handler is immediately invoked
- * with a cancellation cause or with a fresh [CancellationException].
- * Otherwise, handler will be invoked once when this job is complete
- * (cancellation also is a form of completion).
+ * Registers handler that is **synchronously** invoked on completion of this job.
+ * When job is already complete, then the handler is immediately invoked
+ * with a cancellation cause or `null`. Otherwise, handler will be invoked once when this
+ * job is complete. Note, that [cancellation][cancel] is also a form of completion).
*
* The resulting [Registration] can be used to [Registration.unregister] if this
* registration is no longer needed. There is no need to unregister after completion.
*/
+ public fun invokeOnCompletion(handler: CompletionHandler): Registration
+
+ /**
+ * @suppress **Deprecated**: Renamed to `invokeOnCompletion`
+ */
+ @Deprecated(message = "Renamed to `invokeOnCompletion`", replaceWith = ReplaceWith("invokeOnCompletion"))
public fun onCompletion(handler: CompletionHandler): Registration
/**
@@ -142,7 +147,7 @@
public operator fun plus(other: Job) = other
/**
- * Registration object for [onCompletion]. It can be used to [unregister] if needed.
+ * Registration object for [invokeOnCompletion]. It can be used to [unregister] if needed.
* There is no need to unregister after completion.
*/
public interface Registration {
@@ -154,7 +159,7 @@
}
/**
- * Handler for [Job.onCompletion].
+ * Handler for [Job.invokeOnCompletion].
*/
public typealias CompletionHandler = (Throwable?) -> Unit
@@ -168,22 +173,22 @@
*
* This is a shortcut for the following code with slightly more efficient implementation (one fewer object created).
* ```
- * onCompletion { registration.unregister() }
+ * invokeOnCompletion { registration.unregister() }
* ```
*/
public fun Job.unregisterOnCompletion(registration: Job.Registration): Job.Registration =
- onCompletion(UnregisterOnCompletion(this, registration))
+ invokeOnCompletion(UnregisterOnCompletion(this, registration))
/**
* Cancels a specified [future] when this job is complete.
*
* This is a shortcut for the following code with slightly more efficient implementation (one fewer object created).
* ```
- * onCompletion { future.cancel(false) }
+ * invokeOnCompletion { future.cancel(false) }
* ```
*/
public fun Job.cancelFutureOnCompletion(future: Future<*>): Job.Registration =
- onCompletion(CancelFutureOnCompletion(this, future))
+ invokeOnCompletion(CancelFutureOnCompletion(this, future))
/**
* @suppress **Deprecated**: `join` is now a member function of `Job`.
@@ -285,7 +290,7 @@
return
}
// directly pass HandlerNode to parent scope to optimize one closure object (see makeNode)
- val newRegistration = parent.onCompletion(CancelOnCompletion(parent, this))
+ val newRegistration = parent.invokeOnCompletion(CancelOnCompletion(parent, this))
registration = newRegistration
// now check our state _after_ registering (see updateState order of actions)
if (isCompleted) newRegistration.unregister()
@@ -336,7 +341,7 @@
// otherwise -- do nothing (it was Empty*)
else -> check(expect is Empty)
}
- // handle onCompletion exceptions
+ // handle invokeOnCompletion exceptions
completionException?.let { handleCompletionException(it) }
// Do other (overridable) processing after completion handlers
afterCompletion(update)
@@ -393,7 +398,9 @@
}
}
- final override fun onCompletion(handler: CompletionHandler): Job.Registration {
+ override fun onCompletion(handler: CompletionHandler): Job.Registration = invokeOnCompletion(handler)
+
+ final override fun invokeOnCompletion(handler: CompletionHandler): Job.Registration {
var nodeCache: JobNode<*>? = null
while (true) { // lock-free loop on state
val state = this.state
@@ -441,7 +448,7 @@
}
private suspend fun joinSuspend() = suspendCancellableCoroutine<Unit> { cont ->
- cont.unregisterOnCompletion(onCompletion(ResumeOnCompletion(this, cont)))
+ cont.unregisterOnCompletion(invokeOnCompletion(ResumeOnCompletion(this, cont)))
}
internal fun removeNode(node: JobNode<*>) {
@@ -475,7 +482,7 @@
}
/**
- * Override to process any exceptions that were encountered while invoking [onCompletion] handlers.
+ * Override to process any exceptions that were encountered while invoking [invokeOnCompletion] handlers.
*/
protected open fun handleCompletionException(closeException: Throwable) {
throw closeException
diff --git a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/NonCancellable.kt b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/NonCancellable.kt
index 83953db..b7e5409 100644
--- a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/NonCancellable.kt
+++ b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/NonCancellable.kt
@@ -46,8 +46,10 @@
/** Always throws [IllegalStateException]. */
override fun getCompletionException(): CancellationException = throw IllegalStateException("This job is always active")
+ override fun onCompletion(handler: CompletionHandler): Job.Registration = invokeOnCompletion(handler)
+
/** Always returns [EmptyRegistration]. */
- override fun onCompletion(handler: CompletionHandler): Job.Registration = EmptyRegistration
+ override fun invokeOnCompletion(handler: CompletionHandler): Job.Registration = EmptyRegistration
/** Always returns `false`. */
override fun cancel(cause: Throwable?): Boolean = false
diff --git a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/ThreadPoolDispatcher.kt b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/ThreadPoolDispatcher.kt
index 2d89807..a439621 100644
--- a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/ThreadPoolDispatcher.kt
+++ b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/ThreadPoolDispatcher.kt
@@ -56,7 +56,7 @@
}
init {
- job.onCompletion { executor.shutdown() }
+ job.invokeOnCompletion { executor.shutdown() }
}
override fun dispatch(context: CoroutineContext, block: Runnable) = executor.execute(block)
diff --git a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/AbstractChannel.kt b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/AbstractChannel.kt
index 06ba63e..b8a58e8 100644
--- a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/AbstractChannel.kt
+++ b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/AbstractChannel.kt
@@ -273,7 +273,7 @@
}
private fun removeReceiveOnCancel(cont: CancellableContinuation<*>, receive: Receive<*>) {
- cont.onCompletion {
+ cont.invokeOnCompletion {
if (cont.isCancelled && receive.remove())
onCancelledReceive()
}