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()
}
diff --git a/kotlinx-coroutines-core/src/test/kotlin/kotlinx/coroutines/experimental/JobTest.kt b/kotlinx-coroutines-core/src/test/kotlin/kotlinx/coroutines/experimental/JobTest.kt
index ef939d8..ca54780 100644
--- a/kotlinx-coroutines-core/src/test/kotlin/kotlinx/coroutines/experimental/JobTest.kt
+++ b/kotlinx-coroutines-core/src/test/kotlin/kotlinx/coroutines/experimental/JobTest.kt
@@ -32,7 +32,7 @@
fun testHandler() {
val job = Job()
var fireCount = 0
- job.onCompletion { fireCount++ }
+ job.invokeOnCompletion { fireCount++ }
check(job.isActive)
assertEquals(0, fireCount)
// cancel once
@@ -50,7 +50,7 @@
val job = Job()
val n = 100
val fireCount = IntArray(n)
- for (i in 0 until n) job.onCompletion { fireCount[i]++ }
+ for (i in 0 until n) job.invokeOnCompletion { fireCount[i]++ }
check(job.isActive)
for (i in 0 until n) assertEquals(0, fireCount[i])
// cancel once
@@ -70,7 +70,7 @@
val fireCount = IntArray(n)
for (i in 0 until n) {
var registration: Job.Registration? = null
- registration = job.onCompletion {
+ registration = job.invokeOnCompletion {
fireCount[i]++
registration!!.unregister()
}
@@ -92,7 +92,7 @@
val job = Job()
val n = 100
val fireCount = IntArray(n)
- val registrations = Array<Job.Registration>(n) { i -> job.onCompletion { fireCount[i]++ } }
+ val registrations = Array<Job.Registration>(n) { i -> job.invokeOnCompletion { fireCount[i]++ } }
check(job.isActive)
fun unreg(i: Int) = i % 4 <= 1
for (i in 0 until n) if (unreg(i)) registrations[i].unregister()
@@ -108,7 +108,7 @@
val n = 100
val fireCount = IntArray(n)
class TestException : Throwable()
- for (i in 0 until n) job.onCompletion {
+ for (i in 0 until n) job.invokeOnCompletion {
fireCount[i]++
throw TestException()
}
@@ -125,7 +125,7 @@
val job = Job()
val n = 10_000_000
var fireCount = 0
- for (i in 0 until n) job.onCompletion { fireCount++ }.unregister()
+ for (i in 0 until n) job.invokeOnCompletion { fireCount++ }.unregister()
}
@Test
diff --git a/kotlinx-coroutines-javafx/src/main/kotlin/kotlinx/coroutines/experimental/javafx/JavaFx.kt b/kotlinx-coroutines-javafx/src/main/kotlin/kotlinx/coroutines/experimental/javafx/JavaFx.kt
index 38a8f5d..ce21513 100644
--- a/kotlinx-coroutines-javafx/src/main/kotlin/kotlinx/coroutines/experimental/javafx/JavaFx.kt
+++ b/kotlinx-coroutines-javafx/src/main/kotlin/kotlinx/coroutines/experimental/javafx/JavaFx.kt
@@ -55,7 +55,7 @@
}
val timeline = Timeline(KeyFrame(Duration.millis(unit.toMillis(time).toDouble()), handler))
timeline.play()
- continuation.onCompletion { timeline.stop() }
+ continuation.invokeOnCompletion { timeline.stop() }
}
private class PulseTimer : AnimationTimer() {
diff --git a/kotlinx-coroutines-javafx/src/test/kotlin/examples/FxExampleApp.kt b/kotlinx-coroutines-javafx/src/test/kotlin/examples/FxExampleApp.kt
index 31af8d8..d861c8c 100644
--- a/kotlinx-coroutines-javafx/src/test/kotlin/examples/FxExampleApp.kt
+++ b/kotlinx-coroutines-javafx/src/test/kotlin/examples/FxExampleApp.kt
@@ -73,7 +73,7 @@
root.children += node
val job = launch(JavaFx, block = block)
animations += job
- job.onCompletion { root.children -= node }
+ job.invokeOnCompletion { root.children -= node }
}
fun doRect() {
diff --git a/kotlinx-coroutines-jdk8/src/main/kotlin/kotlinx/coroutines/experimental/future/Future.kt b/kotlinx-coroutines-jdk8/src/main/kotlin/kotlinx/coroutines/experimental/future/Future.kt
index b289dd8..7717baa 100644
--- a/kotlinx-coroutines-jdk8/src/main/kotlin/kotlinx/coroutines/experimental/future/Future.kt
+++ b/kotlinx-coroutines-jdk8/src/main/kotlin/kotlinx/coroutines/experimental/future/Future.kt
@@ -51,7 +51,7 @@
public fun <T> Deferred<T>.toCompletableFuture(): CompletableFuture<T> {
val future = CompletableFuture<T>()
future.whenComplete { _, exception -> cancel(exception) }
- onCompletion {
+ invokeOnCompletion {
try {
future.complete(getCompleted())
} catch (exception: Exception) {
diff --git a/kotlinx-coroutines-nio/src/main/kotlin/kotlinx/coroutines/experimental/nio/Nio.kt b/kotlinx-coroutines-nio/src/main/kotlin/kotlinx/coroutines/experimental/nio/Nio.kt
index 6f64cf2..0e6d469 100644
--- a/kotlinx-coroutines-nio/src/main/kotlin/kotlinx/coroutines/experimental/nio/Nio.kt
+++ b/kotlinx-coroutines-nio/src/main/kotlin/kotlinx/coroutines/experimental/nio/Nio.kt
@@ -136,7 +136,7 @@
// ---------------- private details ----------------
private fun Channel.closeOnCancel(cont: CancellableContinuation<*>) {
- cont.onCompletion {
+ cont.invokeOnCompletion {
if (cont.isCancelled)
try {
close()
diff --git a/kotlinx-coroutines-swing/src/main/kotlin/kotlinx/coroutines/experimental/swing/Swing.kt b/kotlinx-coroutines-swing/src/main/kotlin/kotlinx/coroutines/experimental/swing/Swing.kt
index 999455c..08cb0da 100644
--- a/kotlinx-coroutines-swing/src/main/kotlin/kotlinx/coroutines/experimental/swing/Swing.kt
+++ b/kotlinx-coroutines-swing/src/main/kotlin/kotlinx/coroutines/experimental/swing/Swing.kt
@@ -41,7 +41,7 @@
isRepeats = false
start()
}
- continuation.onCompletion { timer.stop() }
+ continuation.invokeOnCompletion { timer.stop() }
}
override fun toString() = "Swing"