Job.onCompletion is renamed to Job.invokeOnCompletion for consistency

Author: elizarov

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CancellableContinuation.kt

@@ -125,7 +125,7 @@ public inline suspend fun <T> suspendCancellableCoroutine(
  * @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 ---------------
 

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Deferred.kt

@@ -71,7 +71,7 @@ public interface Deferred<out T> : Job {
      * [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 @@ private open class DeferredCoroutine<T>(
 
     @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)

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Job.kt

@@ -96,15 +96,20 @@ public interface Job : CoroutineContext.Element {
     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 interface Job : CoroutineContext.Element {
     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 @@ public interface Job : CoroutineContext.Element {
 }
 
 /**
- * Handler for [Job.onCompletion].
+ * Handler for [Job.invokeOnCompletion].
  */
 public typealias CompletionHandler = (Throwable?) -> Unit
 
@@ -168,22 +173,22 @@ public typealias CancellationException = java.util.concurrent.CancellationExcept
  *
  * 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 @@ public open class JobSupport(active: Boolean) : AbstractCoroutineContextElement(
             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 @@ public open class JobSupport(active: Boolean) : AbstractCoroutineContextElement(
             // 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 @@ public open class JobSupport(active: Boolean) : AbstractCoroutineContextElement(
         }
     }
 
-    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 @@ public open class JobSupport(active: Boolean) : AbstractCoroutineContextElement(
     }
 
     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 @@ public open class JobSupport(active: Boolean) : AbstractCoroutineContextElement(
     }
 
     /**
-     * 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

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/NonCancellable.kt

@@ -46,8 +46,10 @@ object NonCancellable : AbstractCoroutineContextElement(Job), Job {
     /** 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

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/ThreadPoolDispatcher.kt

@@ -56,7 +56,7 @@ private class ThreadPoolDispatcher(
     }
 
     init {
-        job.onCompletion { executor.shutdown() }
+        job.invokeOnCompletion { executor.shutdown() }
     }
 
     override fun dispatch(context: CoroutineContext, block: Runnable) = executor.execute(block)

kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/channels/AbstractChannel.kt

@@ -273,7 +273,7 @@ public abstract class AbstractChannel<E> : Channel<E> {
     }
 
     private fun removeReceiveOnCancel(cont: CancellableContinuation<*>, receive: Receive<*>) {
-        cont.onCompletion {
+        cont.invokeOnCompletion {
             if (cont.isCancelled && receive.remove())
                 onCancelledReceive()
         }

kotlinx-coroutines-core/src/test/kotlin/kotlinx/coroutines/experimental/JobTest.kt

@@ -32,7 +32,7 @@ class JobTest {
     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 @@ class JobTest {
         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 @@ class JobTest {
         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 @@ class JobTest {
         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 @@ class JobTest {
         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 @@ class JobTest {
         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

kotlinx-coroutines-javafx/src/main/kotlin/kotlinx/coroutines/experimental/javafx/JavaFx.kt

@@ -55,7 +55,7 @@ object JavaFx : CoroutineDispatcher(), Delay {
         }
         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() {

kotlinx-coroutines-javafx/src/test/kotlin/examples/FxExampleApp.kt

@@ -73,7 +73,7 @@ class FxTestApp : Application() {
         root.children += node
         val job = launch(JavaFx, block = block)
         animations += job
-        job.onCompletion { root.children -= node }
+        job.invokeOnCompletion { root.children -= node }
     }
 
     fun doRect() {

kotlinx-coroutines-jdk8/src/main/kotlin/kotlinx/coroutines/experimental/future/Future.kt

@@ -51,7 +51,7 @@ public fun <T> future(context: CoroutineContext = CommonPool, block: suspend ()
 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) {