Deprecate SendChannel.offer and ReceiveChannel.poll, replace their usages along the codebase (#2644)

* Deprecate SendChannel.offer and replace its usages along the codebase
* Deprecate ReceiveChannel.poll and replace its usages along the codebase

Co-authored-by: Roman Elizarov <elizarov@gmail.com>

Addresses #974

11 files changed, 72 insertions, 95 deletions

diff --git a/kotlinx-coroutines-core/common/test/channels/ArrayChannelTest.kt b/kotlinx-coroutines-core/common/test/channels/ArrayChannelTest.kt
index 3900c2db..632fd292 100644
--- a/kotlinx-coroutines-core/common/test/channels/ArrayChannelTest.kt
+++ b/kotlinx-coroutines-core/common/test/channels/ArrayChannelTest.kt
@@ -86,31 +86,31 @@ class ArrayChannelTest : TestBase() {
     }
 
     @Test
-    fun testOfferAndPoll() = runTest {
+    fun testTryOp() = runTest {
         val q = Channel<Int>(1)
-        assertTrue(q.offer(1))
+        assertTrue(q.trySend(1).isSuccess)
         expect(1)
         launch {
             expect(3)
-            assertEquals(1, q.poll())
+            assertEquals(1, q.tryReceive().getOrNull())
             expect(4)
-            assertNull(q.poll())
+            assertNull(q.tryReceive().getOrNull())
             expect(5)
             assertEquals(2, q.receive()) // suspends
             expect(9)
-            assertEquals(3, q.poll())
+            assertEquals(3, q.tryReceive().getOrNull())
             expect(10)
-            assertNull(q.poll())
+            assertNull(q.tryReceive().getOrNull())
             expect(11)
         }
         expect(2)
         yield()
         expect(6)
-        assertTrue(q.offer(2))
+        assertTrue(q.trySend(2).isSuccess)
         expect(7)
-        assertTrue(q.offer(3))
+        assertTrue(q.trySend(3).isSuccess)
         expect(8)
-        assertFalse(q.offer(4))
+        assertFalse(q.trySend(4).isSuccess)
         yield()
         finish(12)
     }
@@ -157,7 +157,7 @@ class ArrayChannelTest : TestBase() {
         val capacity = 42
         val channel = Channel<Int>(capacity)
         repeat(4) {
-            channel.offer(-1)
+            channel.trySend(-1)
         }
         repeat(4) {
             channel.receiveCatching().getOrNull()
diff --git a/kotlinx-coroutines-core/common/test/channels/BasicOperationsTest.kt b/kotlinx-coroutines-core/common/test/channels/BasicOperationsTest.kt
index a64284ae..8962acc3 100644
--- a/kotlinx-coroutines-core/common/test/channels/BasicOperationsTest.kt
+++ b/kotlinx-coroutines-core/common/test/channels/BasicOperationsTest.kt
@@ -15,8 +15,8 @@ class BasicOperationsTest : TestBase() {
     }
 
     @Test
-    fun testOfferAfterClose() = runTest {
-        TestChannelKind.values().forEach { kind -> testOffer(kind) }
+    fun testTrySendAfterClose() = runTest {
+        TestChannelKind.values().forEach { kind -> testTrySend(kind) }
     }
 
     @Test
@@ -39,7 +39,7 @@ class BasicOperationsTest : TestBase() {
             }
         }
         expect(1)
-        channel.offer(42)
+        channel.trySend(42)
         expect(2)
         channel.close(AssertionError())
         finish(4)
@@ -80,28 +80,6 @@ class BasicOperationsTest : TestBase() {
         }
     }
 
-    private suspend fun testReceiveCatchingException(kind: TestChannelKind) = coroutineScope {
-        val channel = kind.create<Int>()
-        val d = async(NonCancellable) {
-            channel.receive()
-        }
-
-        yield()
-        channel.close(TestException())
-        assertTrue(channel.isClosedForReceive)
-
-        assertFailsWith<TestException> { channel.poll() }
-        try {
-            channel.receiveCatching().getOrThrow()
-            expectUnreached()
-        } catch (e: TestException) {
-            // Expected
-        }
-
-        d.join()
-        assertTrue(d.getCancellationException().cause is TestException)
-    }
-
     @Suppress("ReplaceAssertBooleanWithAssertEquality")
     private suspend fun testReceiveCatching(kind: TestChannelKind) = coroutineScope {
         reset()
@@ -131,22 +109,21 @@ class BasicOperationsTest : TestBase() {
         finish(6)
     }
 
-    private suspend fun testOffer(kind: TestChannelKind) = coroutineScope {
+    private suspend fun testTrySend(kind: TestChannelKind) = coroutineScope {
         val channel = kind.create<Int>()
         val d = async { channel.send(42) }
         yield()
         channel.close()
 
         assertTrue(channel.isClosedForSend)
-        try {
-            channel.offer(2)
-            fail()
-        } catch (e: ClosedSendChannelException) {
-            if (!kind.isConflated) {
-                assertEquals(42, channel.receive())
+        channel.trySend(2)
+            .onSuccess { expectUnreached() }
+            .onFailure {
+                assertTrue { it is  ClosedSendChannelException}
+                if (!kind.isConflated) {
+                    assertEquals(42, channel.receive())
+                }
             }
-        }
-
         d.await()
     }
 
diff --git a/kotlinx-coroutines-core/common/test/channels/ChannelBufferOverflowTest.kt b/kotlinx-coroutines-core/common/test/channels/ChannelBufferOverflowTest.kt
index 41f60479..0b9a0fdb 100644
--- a/kotlinx-coroutines-core/common/test/channels/ChannelBufferOverflowTest.kt
+++ b/kotlinx-coroutines-core/common/test/channels/ChannelBufferOverflowTest.kt
@@ -11,30 +11,30 @@ class ChannelBufferOverflowTest : TestBase() {
     @Test
     fun testDropLatest() = runTest {
         val c = Channel<Int>(2, BufferOverflow.DROP_LATEST)
-        assertTrue(c.offer(1))
-        assertTrue(c.offer(2))
-        assertTrue(c.offer(3)) // overflows, dropped
+        assertTrue(c.trySend(1).isSuccess)
+        assertTrue(c.trySend(2).isSuccess)
+        assertTrue(c.trySend(3).isSuccess) // overflows, dropped
         c.send(4) // overflows dropped
         assertEquals(1, c.receive())
-        assertTrue(c.offer(5))
-        assertTrue(c.offer(6)) // overflows, dropped
+        assertTrue(c.trySend(5).isSuccess)
+        assertTrue(c.trySend(6).isSuccess) // overflows, dropped
         assertEquals(2, c.receive())
         assertEquals(5, c.receive())
-        assertEquals(null, c.poll())
+        assertEquals(null, c.tryReceive().getOrNull())
     }
 
     @Test
     fun testDropOldest() = runTest {
         val c = Channel<Int>(2, BufferOverflow.DROP_OLDEST)
-        assertTrue(c.offer(1))
-        assertTrue(c.offer(2))
-        assertTrue(c.offer(3)) // overflows, keeps 2, 3
+        assertTrue(c.trySend(1).isSuccess)
+        assertTrue(c.trySend(2).isSuccess)
+        assertTrue(c.trySend(3).isSuccess) // overflows, keeps 2, 3
         c.send(4) // overflows, keeps 3, 4
         assertEquals(3, c.receive())
-        assertTrue(c.offer(5))
-        assertTrue(c.offer(6)) // overflows, keeps 5, 6
+        assertTrue(c.trySend(5).isSuccess)
+        assertTrue(c.trySend(6).isSuccess) // overflows, keeps 5, 6
         assertEquals(5, c.receive())
         assertEquals(6, c.receive())
-        assertEquals(null, c.poll())
+        assertEquals(null, c.tryReceive().getOrNull())
     }
-}
\ No newline at end of file
+}
diff --git a/kotlinx-coroutines-core/common/test/channels/ConflatedBroadcastChannelTest.kt b/kotlinx-coroutines-core/common/test/channels/ConflatedBroadcastChannelTest.kt
index 856a66fb..a8c2a29c 100644
--- a/kotlinx-coroutines-core/common/test/channels/ConflatedBroadcastChannelTest.kt
+++ b/kotlinx-coroutines-core/common/test/channels/ConflatedBroadcastChannelTest.kt
@@ -42,7 +42,7 @@ class ConflatedBroadcastChannelTest : TestBase() {
         launch(start = CoroutineStart.UNDISPATCHED) {
             expect(2)
             val sub = broadcast.openSubscription()
-            assertNull(sub.poll())
+            assertNull(sub.tryReceive().getOrNull())
             expect(3)
             assertEquals("one", sub.receive()) // suspends
             expect(6)
diff --git a/kotlinx-coroutines-core/common/test/channels/ConflatedChannelTest.kt b/kotlinx-coroutines-core/common/test/channels/ConflatedChannelTest.kt
index 87194f72..370fd5b9 100644
--- a/kotlinx-coroutines-core/common/test/channels/ConflatedChannelTest.kt
+++ b/kotlinx-coroutines-core/common/test/channels/ConflatedChannelTest.kt
@@ -12,14 +12,14 @@ open class ConflatedChannelTest : TestBase() {
         Channel<T>(Channel.CONFLATED)
     
     @Test
-    fun testBasicConflationOfferPoll() {
+    fun testBasicConflationOfferTryReceive() {
         val q = createConflatedChannel<Int>()
-        assertNull(q.poll())
-        assertTrue(q.offer(1))
-        assertTrue(q.offer(2))
-        assertTrue(q.offer(3))
-        assertEquals(3, q.poll())
-        assertNull(q.poll())
+        assertNull(q.tryReceive().getOrNull())
+        assertTrue(q.trySend(1).isSuccess)
+        assertTrue(q.trySend(2).isSuccess)
+        assertTrue(q.trySend(3).isSuccess)
+        assertEquals(3, q.tryReceive().getOrNull())
+        assertNull(q.tryReceive().getOrNull())
     }
 
     @Test
diff --git a/kotlinx-coroutines-core/common/test/channels/LinkedListChannelTest.kt b/kotlinx-coroutines-core/common/test/channels/LinkedListChannelTest.kt
index cdec8a77..501affb4 100644
--- a/kotlinx-coroutines-core/common/test/channels/LinkedListChannelTest.kt
+++ b/kotlinx-coroutines-core/common/test/channels/LinkedListChannelTest.kt
@@ -12,12 +12,12 @@ class LinkedListChannelTest : TestBase() {
     fun testBasic() = runTest {
         val c = Channel<Int>(Channel.UNLIMITED)
         c.send(1)
-        check(c.offer(2))
+        assertTrue(c.trySend(2).isSuccess)
         c.send(3)
         check(c.close())
         check(!c.close())
         assertEquals(1, c.receive())
-        assertEquals(2, c.poll())
+        assertEquals(2, c.tryReceive().getOrNull())
         assertEquals(3, c.receiveCatching().getOrNull())
         assertNull(c.receiveCatching().getOrNull())
     }
diff --git a/kotlinx-coroutines-core/common/test/channels/RendezvousChannelTest.kt b/kotlinx-coroutines-core/common/test/channels/RendezvousChannelTest.kt
index ab0292a8..c83813e4 100644
--- a/kotlinx-coroutines-core/common/test/channels/RendezvousChannelTest.kt
+++ b/kotlinx-coroutines-core/common/test/channels/RendezvousChannelTest.kt
@@ -80,26 +80,26 @@ class RendezvousChannelTest : TestBase() {
     }
 
     @Test
-    fun testOfferAndPool() = runTest {
+    fun testTrySendTryReceive() = runTest {
         val q = Channel<Int>(Channel.RENDEZVOUS)
-        assertFalse(q.offer(1))
+        assertFalse(q.trySend(1).isSuccess)
         expect(1)
         launch {
             expect(3)
-            assertNull(q.poll())
+            assertNull(q.tryReceive().getOrNull())
             expect(4)
             assertEquals(2, q.receive())
             expect(7)
-            assertNull(q.poll())
+            assertNull(q.tryReceive().getOrNull())
             yield()
             expect(9)
-            assertEquals(3, q.poll())
+            assertEquals(3, q.tryReceive().getOrNull())
             expect(10)
         }
         expect(2)
         yield()
         expect(5)
-        assertTrue(q.offer(2))
+        assertTrue(q.trySend(2).isSuccess)
         expect(6)
         yield()
         expect(8)
diff --git a/kotlinx-coroutines-core/common/test/flow/channels/ChannelBuildersFlowTest.kt b/kotlinx-coroutines-core/common/test/flow/channels/ChannelBuildersFlowTest.kt
index f93d0399..4763d13b 100644
--- a/kotlinx-coroutines-core/common/test/flow/channels/ChannelBuildersFlowTest.kt
+++ b/kotlinx-coroutines-core/common/test/flow/channels/ChannelBuildersFlowTest.kt
@@ -166,15 +166,15 @@ class ChannelBuildersFlowTest : TestBase() {
 
         var expected = 0
         launch {
-            assertTrue(channel.offer(1)) // Handed to the coroutine
-            assertTrue(channel.offer(2)) // Buffered
-            assertFalse(channel.offer(3)) // Failed to offer
+            assertTrue(channel.trySend(1).isSuccess) // Handed to the coroutine
+            assertTrue(channel.trySend(2).isSuccess) // Buffered
+            assertFalse(channel.trySend(3).isSuccess) // Failed to offer
             channel.send(3)
             yield()
             assertEquals(1, expected)
-            assertTrue(channel.offer(4)) // Handed to the coroutine
-            assertTrue(channel.offer(5)) // Buffered
-            assertFalse(channel.offer(6))  // Failed to offer
+            assertTrue(channel.trySend(4).isSuccess) // Handed to the coroutine
+            assertTrue(channel.trySend(5).isSuccess) // Buffered
+            assertFalse(channel.trySend(6).isSuccess)  // Failed to offer
             channel.send(6)
             assertEquals(2, expected)
         }
diff --git a/kotlinx-coroutines-core/common/test/flow/channels/ChannelFlowTest.kt b/kotlinx-coroutines-core/common/test/flow/channels/ChannelFlowTest.kt
index 31a929b2..f197a214 100644
--- a/kotlinx-coroutines-core/common/test/flow/channels/ChannelFlowTest.kt
+++ b/kotlinx-coroutines-core/common/test/flow/channels/ChannelFlowTest.kt
@@ -12,9 +12,9 @@ class ChannelFlowTest : TestBase() {
     @Test
     fun testRegular() = runTest {
         val flow = channelFlow {
-            assertTrue(offer(1))
-            assertTrue(offer(2))
-            assertTrue(offer(3))
+            assertTrue(trySend(1).isSuccess)
+            assertTrue(trySend(2).isSuccess)
+            assertTrue(trySend(3).isSuccess)
         }
         assertEquals(listOf(1, 2, 3), flow.toList())
     }
@@ -22,9 +22,9 @@ class ChannelFlowTest : TestBase() {
     @Test
     fun testBuffer() = runTest {
         val flow = channelFlow {
-            assertTrue(offer(1))
-            assertTrue(offer(2))
-            assertFalse(offer(3))
+            assertTrue(trySend(1).isSuccess)
+            assertTrue(trySend(2).isSuccess)
+            assertFalse(trySend(3).isSuccess)
         }.buffer(1)
         assertEquals(listOf(1, 2), flow.toList())
     }
@@ -32,10 +32,10 @@ class ChannelFlowTest : TestBase() {
     @Test
     fun testConflated() = runTest {
         val flow = channelFlow {
-            assertTrue(offer(1))
-            assertTrue(offer(2))
-            assertTrue(offer(3))
-            assertTrue(offer(4))
+            assertTrue(trySend(1).isSuccess)
+            assertTrue(trySend(2).isSuccess)
+            assertTrue(trySend(3).isSuccess)
+            assertTrue(trySend(4).isSuccess)
         }.buffer(Channel.CONFLATED)
         assertEquals(listOf(1, 4), flow.toList()) // two elements in the middle got conflated
     }
@@ -43,7 +43,7 @@ class ChannelFlowTest : TestBase() {
     @Test
     fun testFailureCancelsChannel() = runTest {
         val flow = channelFlow {
-            offer(1)
+            trySend(1)
             invokeOnClose {
                 expect(2)
             }
diff --git a/kotlinx-coroutines-core/common/test/flow/sharing/ShareInFusionTest.kt b/kotlinx-coroutines-core/common/test/flow/sharing/ShareInFusionTest.kt
index 371d0147..85a17ba0 100644
--- a/kotlinx-coroutines-core/common/test/flow/sharing/ShareInFusionTest.kt
+++ b/kotlinx-coroutines-core/common/test/flow/sharing/ShareInFusionTest.kt
@@ -42,7 +42,7 @@ class ShareInFusionTest : TestBase() {
         val flow = channelFlow {
             // send a batch of 10 elements using [offer]
             for (i in 1..10) {
-                assertTrue(offer(i)) // offer must succeed, because buffer
+                assertTrue(trySend(i).isSuccess) // offer must succeed, because buffer
             }
             send(0) // done
         }.buffer(10) // request a buffer of 10
@@ -53,4 +53,4 @@ class ShareInFusionTest : TestBase() {
             .collect { i -> expect(i + 1) }
         finish(12)
     }
-}
\ No newline at end of file
+}
diff --git a/kotlinx-coroutines-core/common/test/flow/sharing/ShareInTest.kt b/kotlinx-coroutines-core/common/test/flow/sharing/ShareInTest.kt
index 42cdb1e1..db69e2bc 100644
--- a/kotlinx-coroutines-core/common/test/flow/sharing/ShareInTest.kt
+++ b/kotlinx-coroutines-core/common/test/flow/sharing/ShareInTest.kt
@@ -167,11 +167,11 @@ class ShareInTest : TestBase() {
                 subs += shared
                     .onEach { value -> // only the first threshold subscribers get the value
                         when (i) {
-                            in 1..threshold -> log.offer("sub$i: $value")
+                            in 1..threshold -> log.trySend("sub$i: $value")
                             else -> expectUnreached()
                         }
                     }
-                    .onCompletion { log.offer("sub$i: completion") }
+                    .onCompletion { log.trySend("sub$i: completion") }
                     .launchIn(this)
                 checkStartTransition(i)
             }
@@ -210,4 +210,4 @@ class ShareInTest : TestBase() {
             stop()
         }
     }
-}
\ No newline at end of file
+}