Mutex is moved to sync subpackage

elizarov · elizarov · commit f8fc4782f8e7 · 2017-02-22T11:37:48.000+03:00
diff --git a/kotlinx-coroutines-core/README.md b/kotlinx-coroutines-core/README.md
@@ -8,7 +8,7 @@ Coroutine builder functions:
 | ------------- | ------------- | ---------------- | ---------------
 | [launch]      | [Job]         | [CoroutineScope] | Launches coroutine that does not have any result 
 | [async]       | [Deferred]    | [CoroutineScope] | Returns a single value with the future result
-| [produce]     | [ProducerJob] | [ProducerScope]  | Produces a stream of elements
+| [kotlinx.coroutines.experimental.channels.produce]     | [kotlinx.coroutines.experimental.channels.ProducerJob] | [kotlinx.coroutines.experimental.channels.ProducerScope]  | Produces a stream of elements
 | [runBlocking] | `T`           | [CoroutineScope] | Blocks the thread while the coroutine runs
 
 Coroutine dispatchers implementing [CoroutineDispatcher]:
@@ -25,8 +25,8 @@ Synchronization primitives for coroutines:
 
 | **Name**   | **Suspending functions**                                    | **Description**
 | ---------- | ----------------------------------------------------------- | ---------------
-| [Mutex]    | [lock][Mutex.lock]                                          | Mutual exclusion 
-| [Channel]  | [send][SendChannel.send], [receive][ReceiveChannel.receive] | Communication channel (aka queue or exchanger)
+| [Mutex][kotlinx.coroutines.experimental.sync.Mutex]          | [lock][kotlinx.coroutines.experimental.sync.Mutex.lock]                                          | Mutual exclusion 
+| [Channel][kotlinx.coroutines.experimental.channels.Channel]  | [send][kotlinx.coroutines.experimental.channels.SendChannel.send], [receive][kotlinx.coroutines.experimental.channels.ReceiveChannel.receive] | Communication channel (aka queue or exchanger)
 
 Top-level suspending functions:
 
@@ -41,10 +41,10 @@ Top-level suspending functions:
 
 | **Receiver**     | **Suspending function**                       | **Select clause**                                | **Non-suspending version**
 | ---------------- | --------------------------------------------- | ------------------------------------------------ | --------------------------
-| [Deferred]       | [await][Deferred.await]                       | [onAwait][SelectBuilder.onAwait]                 | [isCompleted][Deferred.isCompleted]
-| [SendChannel]    | [send][SendChannel.send]                      | [onSend][SelectBuilder.onSend]                   | [offer][SendChannel.offer]
-| [ReceiveChannel] | [receive][ReceiveChannel.receive]             | [onReceive][SelectBuilder.onReceive]             | [poll][ReceiveChannel.poll]
-| [ReceiveChannel] | [receiveOrNull][ReceiveChannel.receiveOrNull] | [onReceiveOrNull][SelectBuilder.onReceiveOrNull] | [poll][ReceiveChannel.poll]
+| [Deferred]       | [await][Deferred.await]                       | [onAwait][kotlinx.coroutines.experimental.selects.SelectBuilder.onAwait]                 | [isCompleted][Job.isCompleted]
+| [SendChannel][kotlinx.coroutines.experimental.channels.SendChannel]    | [send][kotlinx.coroutines.experimental.channels.SendChannel.send]                      | [onSend][kotlinx.coroutines.experimental.selects.SelectBuilder.onSend]                   | [offer][kotlinx.coroutines.experimental.channels.SendChannel.offer]
+| [ReceiveChannel][kotlinx.coroutines.experimental.channels.ReceiveChannel] | [receive][kotlinx.coroutines.experimental.channels.ReceiveChannel.receive]             | [onReceive][kotlinx.coroutines.experimental.selects.SelectBuilder.onReceive]             | [poll][kotlinx.coroutines.experimental.channels.ReceiveChannel.poll]
+| [ReceiveChannel][kotlinx.coroutines.experimental.channels.ReceiveChannel] | [receiveOrNull][kotlinx.coroutines.experimental.channels.ReceiveChannel.receiveOrNull] | [onReceiveOrNull][kotlinx.coroutines.experimental.selects.SelectBuilder.onReceiveOrNull] | [poll][kotlinx.coroutines.experimental.channels.ReceiveChannel.poll]
 
 Cancellation support for user-defined suspending functions is available with [suspendCancellableCoroutine]
 helper function. [NonCancellable] job object is provided to suppress cancellation with 
@@ -58,6 +58,10 @@ debugging facilities.
 
 General-purpose coroutine builders, contexts, and helper functions.
 
+# Package kotlinx.coroutines.experimental.sync
+
+Synchronization primitives (mutex).
+
 # Package kotlinx.coroutines.experimental.channels
 
 Channels -- non-blocking primitives for communicating a stream of elements between coroutines.
@@ -81,30 +85,34 @@ Select expression to perform multiple suspending operations simultaneously until
 [newFixedThreadPoolContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-fixed-thread-pool-context.html
 [java.util.concurrent.Executor.toCoroutineDispatcher]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/to-coroutine-dispatcher.html
 [Unconfined]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-unconfined/index.html
-[Mutex]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-mutex/index.html
-[Mutex.lock]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/lock.html
 [delay]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/delay.html
 [yield]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/yield.html
 [run]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/run.html
 [withTimeout]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/with-timeout.html
+[Deferred.await]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/await.html
+[Job.isCompleted]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/is-completed.html
 [suspendCancellableCoroutine]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/suspend-cancellable-coroutine.html
 [NonCancellable]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/-non-cancellable/index.html
 [newCoroutineContext]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental/new-coroutine-context.html
+<!--- INDEX kotlinx.coroutines.experimental.sync -->
+[kotlinx.coroutines.experimental.sync.Mutex]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.sync/-mutex/index.html
+[kotlinx.coroutines.experimental.sync.Mutex.lock]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.sync/lock.html
 <!--- INDEX kotlinx.coroutines.experimental.channels -->
-[produce]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/produce.html
-[ProducerJob]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-producer-job/index.html
-[ProducerScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-producer-scope/index.html
-[Channel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-channel/index.html
-[SendChannel.send]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/send.html
-[ReceiveChannel.receive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/receive.html
-[SendChannel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-send-channel/index.html
-[SendChannel.offer]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/offer.html
-[ReceiveChannel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-receive-channel/index.html
-[ReceiveChannel.poll]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/poll.html
-[ReceiveChannel.receiveOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/receive-or-null.html
+[kotlinx.coroutines.experimental.channels.produce]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/produce.html
+[kotlinx.coroutines.experimental.channels.ProducerJob]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-producer-job/index.html
+[kotlinx.coroutines.experimental.channels.ProducerScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-producer-scope/index.html
+[kotlinx.coroutines.experimental.channels.Channel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-channel/index.html
+[kotlinx.coroutines.experimental.channels.SendChannel.send]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/send.html
+[kotlinx.coroutines.experimental.channels.ReceiveChannel.receive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/receive.html
+[kotlinx.coroutines.experimental.channels.SendChannel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-send-channel/index.html
+[kotlinx.coroutines.experimental.channels.SendChannel.offer]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/offer.html
+[kotlinx.coroutines.experimental.channels.ReceiveChannel]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/-receive-channel/index.html
+[kotlinx.coroutines.experimental.channels.ReceiveChannel.poll]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/poll.html
+[kotlinx.coroutines.experimental.channels.ReceiveChannel.receiveOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.channels/receive-or-null.html
 <!--- INDEX kotlinx.coroutines.experimental.selects -->
 [kotlinx.coroutines.experimental.selects.select]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.selects/select.html
-[SelectBuilder.onSend]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.selects/on-send.html
-[SelectBuilder.onReceive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.selects/on-receive.html
-[SelectBuilder.onReceiveOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.selects/on-receive-or-null.html
+[kotlinx.coroutines.experimental.selects.SelectBuilder.onAwait]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.selects/on-await.html
+[kotlinx.coroutines.experimental.selects.SelectBuilder.onSend]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.selects/on-send.html
+[kotlinx.coroutines.experimental.selects.SelectBuilder.onReceive]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.selects/on-receive.html
+[kotlinx.coroutines.experimental.selects.SelectBuilder.onReceiveOrNull]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.experimental.selects/on-receive-or-null.html
 <!--- END -->
diff --git a/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/sync/Mutex.kt b/kotlinx-coroutines-core/src/main/kotlin/kotlinx/coroutines/experimental/sync/Mutex.kt
@@ -14,8 +14,9 @@
  * limitations under the License.
  */
 
-package kotlinx.coroutines.experimental
+package kotlinx.coroutines.experimental.sync
 
+import kotlinx.coroutines.experimental.*
 import kotlinx.coroutines.experimental.internal.LockFreeLinkedListHead
 import kotlinx.coroutines.experimental.internal.LockFreeLinkedListNode
 import java.util.concurrent.atomic.AtomicReferenceFieldUpdater
@@ -26,18 +27,57 @@ import java.util.concurrent.atomic.AtomicReferenceFieldUpdater
  * Mutex has two states: _locked_ and _unlocked_.
  * It is **non-reentrant**, that is invoking [lock] even from the same thread/coroutine that currently holds
  * the lock still suspends the invoker.
- *
- * @param locked initial state of the mutex
  */
-public class Mutex(locked: Boolean = false) {
+public interface Mutex {
+    /**
+     * Factory for [Mutex] instances.
+     */
+    public companion object Factory {
+        /**
+         * Creates new [Mutex] instance.
+         * @param locked initial state of the mutex.
+         */
+        public operator fun invoke(locked: Boolean = false) : Mutex = MutexImpl(locked)
+    }
+
+    /**
+     * Returns `true` when this mutex is locked.
+     */
+    public val isLocked: Boolean
+
+    /**
+     * Tries to lock this mutex, returning `false` if this mutex is already locked.
+     */
+    public fun tryLock(): Boolean
+
+    /**
+     * Locks this mutex, suspending caller while the mutex is locked.
+     *
+     * This suspending function is cancellable. If the [Job] of the current coroutine is completed while this
+     * function is suspended, this function immediately resumes with [CancellationException].
+     * Cancellation of suspended lock invocation is *atomic* -- when this function
+     * throws [CancellationException] it means that the mutex was not locked.
+     *
+     * Note, that this function does not check for cancellation when it is not suspended.
+     * Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed.
+     */
+    public suspend fun lock()
+
+    /**
+     * Unlocks this mutex. Throws [IllegalStateException] if invoked on a mutex that is not locked.
+     */
+    public fun unlock()
+}
+
+private class MutexImpl(locked: Boolean) : Mutex {
     // State is: Empty | UnlockOp | LockFreeLinkedListHead (queue of Waiter objects)
     @Volatile
     private var state: Any? = if (locked) EmptyLocked else EmptyUnlocked // shared objects while we have no waiters
 
     private companion object {
         @JvmStatic
-        val STATE: AtomicReferenceFieldUpdater<Mutex, Any?> =
-            AtomicReferenceFieldUpdater.newUpdater(Mutex::class.java, Any::class.java, "state")
+        val STATE: AtomicReferenceFieldUpdater<MutexImpl, Any?> =
+            AtomicReferenceFieldUpdater.newUpdater(MutexImpl::class.java, Any::class.java, "state")
 
         @JvmStatic
         val EmptyLocked = Empty(true)
@@ -50,15 +90,9 @@ public class Mutex(locked: Boolean = false) {
 
     }
 
-    /**
-     * Returns `true` when this mutex is locked.
-     */
-    public val isLocked: Boolean get() = isLocked(state)
+    public override val isLocked: Boolean get() = isLocked(state)
 
-    /**
-     * Tries to lock this mutex, returning `false` if this mutex is already locked.
-     */
-    public fun tryLock(): Boolean {
+    public override fun tryLock(): Boolean {
         while (true) { // lock-free loop on state
             val state = this.state
             when (state) {
@@ -72,18 +106,7 @@ public class Mutex(locked: Boolean = false) {
         }
     }
 
-    /**
-     * Locks this mutex, suspending caller while the mutex is locked.
-     *
-     * This suspending function is cancellable. If the [Job] of the current coroutine is completed while this
-     * function is suspended, this function immediately resumes with [CancellationException].
-     * Cancellation of suspended lock invocation is *atomic* -- when this function
-     * throws [CancellationException] it means that the mutex was not locked.
-     *
-     * Note, that this function does not check for cancellation when it is not suspended.
-     * Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed.
-     */
-    public suspend fun lock() {
+    public override suspend fun lock() {
         // fast-path -- try lock
         if (tryLock()) return
         // slow-path -- suspend
@@ -126,10 +149,7 @@ public class Mutex(locked: Boolean = false) {
         }
     }
 
-    /**
-     * Unlocks this mutex. Throws [IllegalStateException] if invoked on a mutex that is not locked.
-     */
-    public fun unlock() {
+    public override fun unlock() {
         while (true) { // lock-free loop on state
             val state = this.state
             when (state) {
@@ -159,7 +179,7 @@ public class Mutex(locked: Boolean = false) {
     }
 
     private class Empty(val locked: Boolean) {
-        override fun toString(): String = "Empty[${if (locked) "Locked" else "Unlocked"}]";
+        override fun toString(): String = "Empty[${if (locked) "Locked" else "Unlocked"}]"
     }
 
     private class Waiter(val cont: CancellableContinuation<Unit>) : LockFreeLinkedListNode()
@@ -175,7 +195,7 @@ public class Mutex(locked: Boolean = false) {
              */
             val success = queue.isEmpty
             val update: Any = if (success) EmptyUnlocked else queue
-            STATE.compareAndSet(this@Mutex, this@UnlockOp, update)
+            STATE.compareAndSet(this@MutexImpl, this@UnlockOp, update)
             /*
                 `helpComplete` invocation from the original `unlock` invocation may be coming too late, when
                 some other thread had already helped to complete it (either successfully or not).
diff --git a/kotlinx-coroutines-core/src/test/kotlin/guide/example-select-04.kt b/kotlinx-coroutines-core/src/test/kotlin/guide/example-select-04.kt
@@ -18,7 +18,8 @@
 package guide.select.example04
 
 import kotlinx.coroutines.experimental.*
-import kotlinx.coroutines.experimental.selects.select
+import kotlinx.coroutines.experimental.channels.*
+import kotlinx.coroutines.experimental.selects.*
 import java.util.*
 
 fun asyncString(time: Int) = async(CommonPool) {
diff --git a/kotlinx-coroutines-core/src/test/kotlin/guide/example-select-05.kt b/kotlinx-coroutines-core/src/test/kotlin/guide/example-select-05.kt
@@ -18,10 +18,8 @@
 package guide.select.example05
 
 import kotlinx.coroutines.experimental.*
-import kotlinx.coroutines.experimental.channels.Channel
-import kotlinx.coroutines.experimental.channels.ReceiveChannel
-import kotlinx.coroutines.experimental.channels.produce
-import kotlinx.coroutines.experimental.selects.select
+import kotlinx.coroutines.experimental.channels.*
+import kotlinx.coroutines.experimental.selects.*
 
 fun switchMapDeferreds(input: ReceiveChannel<Deferred<String>>) = produce<String>(CommonPool) {
     var current = input.receive() // will start with first received deferred value
diff --git a/kotlinx-coroutines-core/src/test/kotlin/kotlinx/coroutines/experimental/sync/MutexTest.kt b/kotlinx-coroutines-core/src/test/kotlin/kotlinx/coroutines/experimental/sync/MutexTest.kt
@@ -14,8 +14,9 @@
  * limitations under the License.
  */
 
-package kotlinx.coroutines.experimental
+package kotlinx.coroutines.experimental.sync
 
+import kotlinx.coroutines.experimental.*
 import org.junit.Assert.*
 import org.junit.Test
 
