Channel pseudo-constructor is replaced with top-level fun

Author: elizarov

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

@@ -25,6 +25,8 @@ import kotlin.concurrent.withLock
  * Channel with array buffer of a fixed [capacity].
  * Sender suspends only when buffer is fully and receiver suspends only when buffer is empty.
  *
+ * This channel is created by `Channel(capacity)` factory function invocation.
+ *
  * This implementation uses lock to protect the buffer, which is held only during very short buffer-update operations.
  * The lists of suspended senders or receivers are lock-free.
  */

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

@@ -19,6 +19,8 @@ package kotlinx.coroutines.experimental.channels
 import kotlinx.coroutines.experimental.CancellationException
 import kotlinx.coroutines.experimental.CoroutineScope
 import kotlinx.coroutines.experimental.Job
+import kotlinx.coroutines.experimental.channels.Channel.Factory.CONFLATED
+import kotlinx.coroutines.experimental.channels.Channel.Factory.UNLIMITED
 import kotlinx.coroutines.experimental.selects.SelectBuilder
 import kotlinx.coroutines.experimental.selects.SelectInstance
 import kotlinx.coroutines.experimental.selects.select
@@ -243,45 +245,57 @@ public interface ChannelIterator<out E> {
  * Conceptually, a channel is similar to [BlockingQueue][java.util.concurrent.BlockingQueue],
  * but it has suspending operations instead of blocking ones and it can be closed.
  *
- * See [Channel()][Channel.invoke] factory function for the description of available channel implementations.
+ * See `Channel(capacity)` factory function for the description of available channel implementations.
  */
 public interface Channel<E> : SendChannel<E>, ReceiveChannel<E> {
     /**
-     * Factory for channels.
+     * Constants for channel factory function `Channel()`.
      */
     public companion object Factory {
         /**
-         * Requests channel with unlimited capacity buffer in [Channel()][invoke] factory function --
+         * Requests channel with unlimited capacity buffer in `Channel(...)` factory function --
          * the [LinkedListChannel] gets created.
          */
         public const val UNLIMITED = Int.MAX_VALUE
 
         /**
-         * Requests conflated channel in [Channel()][invoke] factory function --
+         * Requests conflated channel in `Channel(...)` factory function --
          * the [ConflatedChannel] gets created.
          */
         public const val CONFLATED = -1
 
         /**
          * Creates a channel with the specified buffer capacity (or without a buffer by default).
-         *
-         * The resulting channel type depends on the specified [capacity] parameter:
-         * * when `capacity` is 0 (default) -- creates [RendezvousChannel] without a buffer;
-         * * when `capacity` is [UNLIMITED] -- creates [LinkedListChannel] with buffer of unlimited size;
-         * * when `capacity` is [CONFLATED] -- creates [ConflatedChannel] that conflates back-to-back sends;
-         * * when `capacity` is positive, but less than [UNLIMITED] -- creates [ArrayChannel] with a buffer of the specified `capacity`;
-         * * otherwise -- throws [IllegalArgumentException].
+         * @suppress **Deprecated**
          */
-        public operator fun <E> invoke(capacity: Int = 0): Channel<E> =
-            when (capacity) {
-                0 -> RendezvousChannel()
-                UNLIMITED -> LinkedListChannel()
-                CONFLATED -> ConflatedChannel()
-                else -> ArrayChannel(capacity)
-            }
+        @Deprecated("Replaced with top-level function", level = DeprecationLevel.HIDDEN)
+        public operator fun <E> invoke(capacity: Int = 0): Channel<E> = Channel(capacity)
     }
 }
 
+/**
+ * Creates a channel without a buffer -- [RendezvousChannel].
+ */
+public fun <E> Channel(): Channel<E> = RendezvousChannel<E>()
+
+/**
+ * Creates a channel with the specified buffer capacity (or without a buffer by default).
+ *
+ * The resulting channel type depends on the specified [capacity] parameter:
+ * * when `capacity` is 0 -- creates [RendezvousChannel] without a buffer;
+ * * when `capacity` is [Channel.UNLIMITED] -- creates [LinkedListChannel] with buffer of unlimited size;
+ * * when `capacity` is [Channel.CONFLATED] -- creates [ConflatedChannel] that conflates back-to-back sends;
+ * * when `capacity` is positive, but less than [UNLIMITED] -- creates [ArrayChannel] with a buffer of the specified `capacity`;
+ * * otherwise -- throws [IllegalArgumentException].
+ */
+public fun <E> Channel(capacity: Int): Channel<E> =
+    when (capacity) {
+        0 -> RendezvousChannel()
+        UNLIMITED -> LinkedListChannel()
+        CONFLATED -> ConflatedChannel()
+        else -> ArrayChannel(capacity)
+    }
+
 /**
  * Indicates attempt to [send][SendChannel.send] on [isClosedForSend][SendChannel.isClosedForSend] channel
  * that was closed _normally_. A _failed_ channel rethrows the original [close][SendChannel.close] cause

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

@@ -26,6 +26,8 @@ import kotlinx.coroutines.experimental.selects.SelectInstance
  * while previously sent elements **are lost**.
  * Sender to this channel never suspends and [offer] always returns `true`.
  *
+ * This channel is created by `Channel(Channel.CONFLATED)` factory function invocation.
+ *
  * This implementation is fully lock-free.
  */
 public open class ConflatedChannel<E> : AbstractChannel<E>() {

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

@@ -23,6 +23,8 @@ import kotlinx.coroutines.experimental.selects.SelectInstance
  * Channel with linked-list buffer of a unlimited capacity (limited only by available memory).
  * Sender to this channel never suspends and [offer] always returns `true`.
  *
+ * This channel is created by `Channel(Channel.UNLIMITED)` factory function invocation.
+ *
  * This implementation is fully lock-free.
  */
 public open class LinkedListChannel<E> : AbstractChannel<E>() {

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

@@ -21,6 +21,8 @@ package kotlinx.coroutines.experimental.channels
  * to receiver only when [send] and [receive] invocations meet in time (rendezvous), so [send] suspends
  * until another coroutine invokes [receive] and [receive] suspends until another coroutine invokes [send].
  *
+ * Use `Channel()` factory function to conveniently create an instance of rendezvous channel.
+ *
  * This implementation is fully lock-free.
  */
 public open class RendezvousChannel<E> : AbstractChannel<E>() {