Improve documentation on suspended Channel.send behaviour when the channel is closed

Author: elizarov

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

@@ -47,6 +47,11 @@ public interface SendChannel<in E> {
      * or throws [ClosedSendChannelException] if the channel [isClosedForSend] _normally_.
      * It throws the original [close] cause exception if the channel has _failed_.
      *
+     * Note, that closing a channel _after_ this function had suspended does not cause this suspended send invocation
+     * to abort, because closing a channel is conceptually like sending a special "close token" over this channel.
+     * All elements that are sent over the channel are delivered in first-in first-out order. The element that
+     * is being sent will get delivered to receivers before a close token.
+     *
      * 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 send is *atomic* -- when this function
@@ -77,7 +82,7 @@ public interface SendChannel<in E> {
     /**
      * Closes this channel with an optional exceptional [cause].
      * This is an idempotent operation -- repeated invocations of this function have no effect and return `false`.
-     * Conceptually, its sends a special close token of this channel. Immediately after invocation of this function
+     * Conceptually, its sends a special "close token" over this channel. Immediately after invocation of this function
      * [isClosedForSend] starts returning `true`. However, [isClosedForReceive][ReceiveChannel.isClosedForReceive]
      * on the side of [ReceiveChannel] starts returning `true` only after all previously sent elements
      * are received.

kotlinx-coroutines-core/src/test/kotlin/kotlinx/coroutines/experimental/channels/RendezvousChannelTest.kt

@@ -20,6 +20,8 @@ import kotlinx.coroutines.experimental.TestBase
 import kotlinx.coroutines.experimental.launch
 import kotlinx.coroutines.experimental.runBlocking
 import kotlinx.coroutines.experimental.yield
+import org.hamcrest.core.IsEqual
+import org.hamcrest.core.IsNull
 import org.junit.Assert.*
 import org.junit.Test
 
@@ -247,6 +249,34 @@ class RendezvousChannelTest : TestBase() {
         finish(10)
     }
 
+    @Test
+    fun testSuspendSendOnClosedChannel() = runBlocking<Unit> {
+        val q = RendezvousChannel<Int>()
+        expect(1)
+        launch(context) {
+            expect(4)
+            q.send(42) // suspend
+            expect(11)
+        }
+        expect(2)
+        launch(context) {
+            expect(5)
+            q.close()
+            expect(6)
+        }
+        expect(3)
+        yield() // to sender
+        expect(7)
+        yield() // try to resume sender (it will not resume despite the close!)
+        expect(8)
+        assertThat(q.receiveOrNull(), IsEqual(42))
+        expect(9)
+        assertThat(q.receiveOrNull(), IsNull())
+        expect(10)
+        yield() // to sender, it was resumed!
+        finish(12)
+    }
+
     class BadClass {
         override fun equals(other: Any?): Boolean = error("equals")
         override fun hashCode(): Int = error("hashCode")