A guide on coroutine contexts, Here context renamed to Unconfined
diff --git a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CoroutineContext.kt b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CoroutineContext.kt
index eed8ab6..3d3d1c0 100644
--- a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CoroutineContext.kt
+++ b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CoroutineContext.kt
@@ -19,15 +19,20 @@
private val COROUTINE_ID = AtomicLong()
/**
- * A coroutine dispatcher that executes initial continuation of the coroutine _right here_ in the current call-frame
+ * A coroutine dispatcher that is not confined to any specific thread.
+ * It executes initial continuation of the coroutine _right here_ in the current call-frame
* and let the coroutine resume in whatever thread that is used by the corresponding suspending function, without
* mandating any specific threading policy.
*/
-public object Here : CoroutineDispatcher() {
+public object Unconfined : CoroutineDispatcher() {
override fun isDispatchNeeded(context: CoroutineContext): Boolean = false
override fun dispatch(context: CoroutineContext, block: Runnable) { throw UnsupportedOperationException() }
}
+@Deprecated(message = "`Here` was renamed to `Unconfined`",
+ replaceWith = ReplaceWith(expression = "Unconfined"))
+public typealias Here = Unconfined
+
/**
* Creates context for the new coroutine with optional support for debugging facilities (when turned on).
*
diff --git a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CoroutineDispatcher.kt b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CoroutineDispatcher.kt
index 51bcc93..a5594b1 100644
--- a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CoroutineDispatcher.kt
+++ b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/CoroutineDispatcher.kt
@@ -9,9 +9,10 @@
* Base class that shall be extended by all coroutine dispatcher implementations.
*
* The following standard implementations are provided by `kotlinx.coroutines`:
- * * [Here] -- starts coroutine execution _right here_ in the current call-frame until the first suspension. On first
- * suspension the coroutine builder function returns. The coroutine will resume in whatever thread that is used by the
- * corresponding suspending function, without mandating any specific threading policy.
+ * * [Unconfined] -- starts coroutine execution in the current call-frame until the first suspension.
+ * On first suspension the coroutine builder function returns.
+ * The coroutine will resume in whatever thread that is used by the
+ * corresponding suspending function, without confining it to any specific thread or pool.
* This in an appropriate choice for IO-intensive coroutines that do not consume CPU resources.
* * [CommonPool] -- immediately returns from the coroutine builder and schedules coroutine execution to
* a common pool of shared background threads.
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 6b5b448..896d669 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
@@ -87,4 +87,8 @@
if (state is CompletedExceptionally) throw state.exception
return state as T
}
+
+ // for nicer debugging
+ override fun toString(): String = "${javaClass.simpleName}{" +
+ (if (isActive) "isActive=true" else "completed=${getState()}") + "}"
}
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 8fa4561..8d767b1 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
@@ -346,6 +346,9 @@
(handler as? JobNode)?.also { require(it.job === this) }
?: InvokeOnCompletion(this, handler)
+ // for nicer debugging
+ override fun toString(): String = "${javaClass.simpleName}{isActive=$isActive}"
+
/**
* Marker interface for active [state][getState] of a job.
*/
diff --git a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Yield.kt b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Yield.kt
index 1499b59..d6be7da 100644
--- a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Yield.kt
+++ b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/Yield.kt
@@ -2,7 +2,7 @@
/**
* Yields a thread (or thread pool) of the current coroutine dispatcher to other coroutines to run.
- * If the coroutine dispatcher does not have its own thread pool (like [Here] dispatcher) then this
+ * If the coroutine dispatcher does not have its own thread pool (like [Unconfined] dispatcher) then this
* function does nothing, but checks if the coroutine [Job] was completed.
* This suspending function is cancellable.
* If the [Job] of the current coroutine is completed when this suspending function is invoked or while