Roman Elizarov | f16fd27 | 2017-02-07 11:26:00 +0300 | [diff] [blame] | 1 | /* |
Roman Elizarov | 1f74a2d | 2018-06-29 19:19:45 +0300 | [diff] [blame^] | 2 | * Copyright 2016-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. |
Roman Elizarov | f16fd27 | 2017-02-07 11:26:00 +0300 | [diff] [blame] | 3 | */ |
| 4 | |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 5 | package kotlinx.coroutines.experimental.channels |
| 6 | |
Roman Elizarov | 89f8ff7 | 2018-03-14 13:39:03 +0300 | [diff] [blame] | 7 | import kotlinx.coroutines.experimental.* |
Roman Elizarov | f2a710a | 2017-07-21 18:33:59 +0300 | [diff] [blame] | 8 | import kotlinx.coroutines.experimental.channels.Channel.Factory.CONFLATED |
| 9 | import kotlinx.coroutines.experimental.channels.Channel.Factory.UNLIMITED |
Roman Elizarov | 89f8ff7 | 2018-03-14 13:39:03 +0300 | [diff] [blame] | 10 | import kotlinx.coroutines.experimental.selects.* |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 11 | |
| 12 | /** |
| 13 | * Sender's interface to [Channel]. |
| 14 | */ |
| 15 | public interface SendChannel<in E> { |
| 16 | /** |
| 17 | * Returns `true` if this channel was closed by invocation of [close] and thus |
Roman Elizarov | 9556242 | 2017-09-27 17:41:01 +0300 | [diff] [blame] | 18 | * the [send] and [offer] attempts throws exception. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 19 | */ |
| 20 | public val isClosedForSend: Boolean |
| 21 | |
| 22 | /** |
| 23 | * Returns `true` if the channel is full (out of capacity) and the [send] attempt will suspend. |
| 24 | * This function returns `false` for [isClosedForSend] channel. |
| 25 | */ |
| 26 | public val isFull: Boolean |
| 27 | |
| 28 | /** |
Roman Elizarov | 1216e91 | 2017-02-22 09:57:06 +0300 | [diff] [blame] | 29 | * Adds [element] into to this channel, suspending the caller while this channel [isFull], |
Roman Elizarov | 9556242 | 2017-09-27 17:41:01 +0300 | [diff] [blame] | 30 | * or throws exception if the channel [isClosedForSend] (see [close] for details). |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 31 | * |
Roman Elizarov | 4e60132 | 2017-03-17 12:46:36 +0300 | [diff] [blame] | 32 | * Note, that closing a channel _after_ this function had suspended does not cause this suspended send invocation |
| 33 | * to abort, because closing a channel is conceptually like sending a special "close token" over this channel. |
| 34 | * All elements that are sent over the channel are delivered in first-in first-out order. The element that |
| 35 | * is being sent will get delivered to receivers before a close token. |
| 36 | * |
Roman Elizarov | d82b3a9 | 2017-06-23 21:52:08 +0300 | [diff] [blame] | 37 | * This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 38 | * function is suspended, this function immediately resumes with [CancellationException]. |
Roman Elizarov | a74eb5f | 2017-05-11 20:15:18 +0300 | [diff] [blame] | 39 | * |
| 40 | * *Cancellation of suspended send is atomic* -- when this function |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 41 | * throws [CancellationException] it means that the [element] was not sent to this channel. |
Roman Elizarov | a74eb5f | 2017-05-11 20:15:18 +0300 | [diff] [blame] | 42 | * As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may |
| 43 | * continue to execute even after it was cancelled from the same thread in the case when this send operation |
| 44 | * was already resumed and the continuation was posted for execution to the thread's queue. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 45 | * |
| 46 | * Note, that this function does not check for cancellation when it is not suspended. |
| 47 | * Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed. |
Roman Elizarov | 1216e91 | 2017-02-22 09:57:06 +0300 | [diff] [blame] | 48 | * |
Roman Elizarov | db0e22d | 2017-08-29 18:15:57 +0300 | [diff] [blame] | 49 | * This function can be used in [select] invocation with [onSend] clause. |
Roman Elizarov | 1216e91 | 2017-02-22 09:57:06 +0300 | [diff] [blame] | 50 | * Use [offer] to try sending to this channel without waiting. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 51 | */ |
| 52 | public suspend fun send(element: E) |
| 53 | |
| 54 | /** |
Roman Elizarov | db0e22d | 2017-08-29 18:15:57 +0300 | [diff] [blame] | 55 | * Clause for [select] expression of [send] suspending function that selects when the element that is specified |
| 56 | * as parameter is sent to the channel. When the clause is selected the reference to this channel |
| 57 | * is passed into the corresponding block. |
| 58 | * |
Roman Elizarov | 9556242 | 2017-09-27 17:41:01 +0300 | [diff] [blame] | 59 | * The [select] invocation fails with exception if the channel [isClosedForSend] (see [close] for details). |
Roman Elizarov | db0e22d | 2017-08-29 18:15:57 +0300 | [diff] [blame] | 60 | */ |
| 61 | public val onSend: SelectClause2<E, SendChannel<E>> |
| 62 | |
| 63 | /** |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 64 | * Adds [element] into this queue if it is possible to do so immediately without violating capacity restrictions |
| 65 | * and returns `true`. Otherwise, it returns `false` immediately |
Roman Elizarov | 9556242 | 2017-09-27 17:41:01 +0300 | [diff] [blame] | 66 | * or throws exception if the channel [isClosedForSend] (see [close] for details). |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 67 | */ |
| 68 | public fun offer(element: E): Boolean |
| 69 | |
| 70 | /** |
Roman Elizarov | f6fed2a | 2017-02-03 19:12:09 +0300 | [diff] [blame] | 71 | * Closes this channel with an optional exceptional [cause]. |
| 72 | * This is an idempotent operation -- repeated invocations of this function have no effect and return `false`. |
Roman Elizarov | b555d91 | 2017-08-17 21:01:33 +0300 | [diff] [blame] | 73 | * Conceptually, its sends a special "close token" over this channel. |
| 74 | * |
| 75 | * Immediately after invocation of this function |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 76 | * [isClosedForSend] starts returning `true`. However, [isClosedForReceive][ReceiveChannel.isClosedForReceive] |
| 77 | * on the side of [ReceiveChannel] starts returning `true` only after all previously sent elements |
| 78 | * are received. |
Roman Elizarov | f6fed2a | 2017-02-03 19:12:09 +0300 | [diff] [blame] | 79 | * |
Roman Elizarov | 9556242 | 2017-09-27 17:41:01 +0300 | [diff] [blame] | 80 | * A channel that was closed without a [cause] throws [ClosedSendChannelException] on attempts to send or receive. |
| 81 | * A channel that was closed with non-null [cause] is called a _failed_ channel. Attempts to send or |
| 82 | * receive on a failed channel throw the specified [cause] exception. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 83 | */ |
Roman Elizarov | f6fed2a | 2017-02-03 19:12:09 +0300 | [diff] [blame] | 84 | public fun close(cause: Throwable? = null): Boolean |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 85 | } |
| 86 | |
| 87 | /** |
| 88 | * Receiver's interface to [Channel]. |
| 89 | */ |
| 90 | public interface ReceiveChannel<out E> { |
| 91 | /** |
| 92 | * Returns `true` if this channel was closed by invocation of [close][SendChannel.close] on the [SendChannel] |
Roman Elizarov | f6fed2a | 2017-02-03 19:12:09 +0300 | [diff] [blame] | 93 | * side and all previously sent items were already received, so that the [receive] attempt |
| 94 | * throws [ClosedReceiveChannelException]. If the channel was closed because of the exception, it |
| 95 | * is considered closed, too, but it is called a _failed_ channel. All suspending attempts to receive |
| 96 | * an element from a failed channel throw the original [close][SendChannel.close] cause exception. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 97 | */ |
| 98 | public val isClosedForReceive: Boolean |
| 99 | |
| 100 | /** |
| 101 | * Returns `true` if the channel is empty (contains no elements) and the [receive] attempt will suspend. |
| 102 | * This function returns `false` for [isClosedForReceive] channel. |
| 103 | */ |
| 104 | public val isEmpty: Boolean |
| 105 | |
| 106 | /** |
| 107 | * Retrieves and removes the element from this channel suspending the caller while this channel [isEmpty] |
| 108 | * or throws [ClosedReceiveChannelException] if the channel [isClosedForReceive]. |
Roman Elizarov | f6fed2a | 2017-02-03 19:12:09 +0300 | [diff] [blame] | 109 | * If the channel was closed because of the exception, it is called a _failed_ channel and this function |
| 110 | * throws the original [close][SendChannel.close] cause exception. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 111 | * |
Roman Elizarov | d82b3a9 | 2017-06-23 21:52:08 +0300 | [diff] [blame] | 112 | * This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 113 | * function is suspended, this function immediately resumes with [CancellationException]. |
Roman Elizarov | a74eb5f | 2017-05-11 20:15:18 +0300 | [diff] [blame] | 114 | * |
| 115 | * *Cancellation of suspended receive is atomic* -- when this function |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 116 | * throws [CancellationException] it means that the element was not retrieved from this channel. |
Roman Elizarov | a74eb5f | 2017-05-11 20:15:18 +0300 | [diff] [blame] | 117 | * As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may |
| 118 | * continue to execute even after it was cancelled from the same thread in the case when this receive operation |
| 119 | * was already resumed and the continuation was posted for execution to the thread's queue. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 120 | * |
| 121 | * Note, that this function does not check for cancellation when it is not suspended. |
| 122 | * Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed. |
Roman Elizarov | 1216e91 | 2017-02-22 09:57:06 +0300 | [diff] [blame] | 123 | * |
Roman Elizarov | db0e22d | 2017-08-29 18:15:57 +0300 | [diff] [blame] | 124 | * This function can be used in [select] invocation with [onReceive] clause. |
Roman Elizarov | 1216e91 | 2017-02-22 09:57:06 +0300 | [diff] [blame] | 125 | * Use [poll] to try receiving from this channel without waiting. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 126 | */ |
| 127 | public suspend fun receive(): E |
| 128 | |
| 129 | /** |
Roman Elizarov | db0e22d | 2017-08-29 18:15:57 +0300 | [diff] [blame] | 130 | * Clause for [select] expression of [receive] suspending function that selects with the element that |
| 131 | * is received from the channel. |
Roman Elizarov | 9556242 | 2017-09-27 17:41:01 +0300 | [diff] [blame] | 132 | * The [select] invocation fails with exception if the channel |
| 133 | * [isClosedForReceive] (see [close][SendChannel.close] for details). |
Roman Elizarov | db0e22d | 2017-08-29 18:15:57 +0300 | [diff] [blame] | 134 | */ |
| 135 | public val onReceive: SelectClause1<E> |
| 136 | |
| 137 | /** |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 138 | * Retrieves and removes the element from this channel suspending the caller while this channel [isEmpty] |
Roman Elizarov | 9556242 | 2017-09-27 17:41:01 +0300 | [diff] [blame] | 139 | * or returns `null` if the channel is [closed][isClosedForReceive] without cause |
Roman Elizarov | f6fed2a | 2017-02-03 19:12:09 +0300 | [diff] [blame] | 140 | * or throws the original [close][SendChannel.close] cause exception if the channel has _failed_. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 141 | * |
Roman Elizarov | d82b3a9 | 2017-06-23 21:52:08 +0300 | [diff] [blame] | 142 | * This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 143 | * function is suspended, this function immediately resumes with [CancellationException]. |
Roman Elizarov | a74eb5f | 2017-05-11 20:15:18 +0300 | [diff] [blame] | 144 | * |
| 145 | * *Cancellation of suspended receive is atomic* -- when this function |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 146 | * throws [CancellationException] it means that the element was not retrieved from this channel. |
Roman Elizarov | a74eb5f | 2017-05-11 20:15:18 +0300 | [diff] [blame] | 147 | * As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may |
| 148 | * continue to execute even after it was cancelled from the same thread in the case when this receive operation |
| 149 | * was already resumed and the continuation was posted for execution to the thread's queue. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 150 | * |
| 151 | * Note, that this function does not check for cancellation when it is not suspended. |
| 152 | * Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed. |
Roman Elizarov | 1216e91 | 2017-02-22 09:57:06 +0300 | [diff] [blame] | 153 | * |
Roman Elizarov | db0e22d | 2017-08-29 18:15:57 +0300 | [diff] [blame] | 154 | * This function can be used in [select] invocation with [onReceiveOrNull] clause. |
Roman Elizarov | 1216e91 | 2017-02-22 09:57:06 +0300 | [diff] [blame] | 155 | * Use [poll] to try receiving from this channel without waiting. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 156 | */ |
| 157 | public suspend fun receiveOrNull(): E? |
| 158 | |
| 159 | /** |
Roman Elizarov | db0e22d | 2017-08-29 18:15:57 +0300 | [diff] [blame] | 160 | * Clause for [select] expression of [receiveOrNull] suspending function that selects with the element that |
| 161 | * is received from the channel or selects with `null` if if the channel |
Roman Elizarov | 9556242 | 2017-09-27 17:41:01 +0300 | [diff] [blame] | 162 | * [isClosedForReceive] without cause. The [select] invocation fails with |
Roman Elizarov | db0e22d | 2017-08-29 18:15:57 +0300 | [diff] [blame] | 163 | * the original [close][SendChannel.close] cause exception if the channel has _failed_. |
| 164 | */ |
| 165 | public val onReceiveOrNull: SelectClause1<E?> |
| 166 | |
| 167 | /** |
Roman Elizarov | 9556242 | 2017-09-27 17:41:01 +0300 | [diff] [blame] | 168 | * Retrieves and removes the element from this channel, or returns `null` if this channel [isEmpty] |
| 169 | * or is [isClosedForReceive] without cause. |
| 170 | * It throws the original [close][SendChannel.close] cause exception if the channel has _failed_. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 171 | */ |
Roman Elizarov | 7b2d8b0 | 2017-02-02 20:09:14 +0300 | [diff] [blame] | 172 | public fun poll(): E? |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 173 | |
| 174 | /** |
| 175 | * Returns new iterator to receive elements from this channels using `for` loop. |
Roman Elizarov | 9556242 | 2017-09-27 17:41:01 +0300 | [diff] [blame] | 176 | * Iteration completes normally when the channel is [isClosedForReceive] without cause and |
Roman Elizarov | f6fed2a | 2017-02-03 19:12:09 +0300 | [diff] [blame] | 177 | * throws the original [close][SendChannel.close] cause exception if the channel has _failed_. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 178 | */ |
| 179 | public operator fun iterator(): ChannelIterator<E> |
Roman Elizarov | b555d91 | 2017-08-17 21:01:33 +0300 | [diff] [blame] | 180 | |
| 181 | /** |
| 182 | * Cancels reception of remaining elements from this channel. This function closes the channel with |
| 183 | * the specified cause (unless it was already closed) and removes all buffered sent elements from it. |
| 184 | * This function returns `true` if the channel was not closed previously, or `false` otherwise. |
| 185 | * |
| 186 | * Immediately after invocation of this function [isClosedForReceive] and |
| 187 | * [isClosedForSend][SendChannel.isClosedForSend] |
| 188 | * on the side of [SendChannel] start returning `true`, so all attempts to send to this channel |
| 189 | * afterwards will throw [ClosedSendChannelException], while attempts to receive will throw |
| 190 | * [ClosedReceiveChannelException] if it was cancelled without a cause. |
| 191 | * A channel that was cancelled with non-null [cause] is called a _failed_ channel. Attempts to send or |
| 192 | * receive on a failed channel throw the specified [cause] exception. |
| 193 | */ |
| 194 | public fun cancel(cause: Throwable? = null): Boolean |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 195 | } |
| 196 | |
| 197 | /** |
| 198 | * Iterator for [ReceiveChannel]. Instances of this interface are *not thread-safe* and shall not be used |
| 199 | * from concurrent coroutines. |
| 200 | */ |
| 201 | public interface ChannelIterator<out E> { |
| 202 | /** |
| 203 | * Returns `true` if the channel has more elements suspending the caller while this channel |
Roman Elizarov | f6fed2a | 2017-02-03 19:12:09 +0300 | [diff] [blame] | 204 | * [isEmpty][ReceiveChannel.isEmpty] or returns `false` if the channel |
Roman Elizarov | 9556242 | 2017-09-27 17:41:01 +0300 | [diff] [blame] | 205 | * [isClosedForReceive][ReceiveChannel.isClosedForReceive] without cause. |
Roman Elizarov | f6fed2a | 2017-02-03 19:12:09 +0300 | [diff] [blame] | 206 | * It throws the original [close][SendChannel.close] cause exception if the channel has _failed_. |
| 207 | * |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 208 | * This function retrieves and removes the element from this channel for the subsequent invocation |
| 209 | * of [next]. |
| 210 | * |
Roman Elizarov | d82b3a9 | 2017-06-23 21:52:08 +0300 | [diff] [blame] | 211 | * This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 212 | * function is suspended, this function immediately resumes with [CancellationException]. |
Roman Elizarov | a74eb5f | 2017-05-11 20:15:18 +0300 | [diff] [blame] | 213 | * |
| 214 | * *Cancellation of suspended receive is atomic* -- when this function |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 215 | * throws [CancellationException] it means that the element was not retrieved from this channel. |
Roman Elizarov | a74eb5f | 2017-05-11 20:15:18 +0300 | [diff] [blame] | 216 | * As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may |
| 217 | * continue to execute even after it was cancelled from the same thread in the case when this receive operation |
| 218 | * was already resumed and the continuation was posted for execution to the thread's queue. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 219 | * |
| 220 | * Note, that this function does not check for cancellation when it is not suspended. |
| 221 | * Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed. |
| 222 | */ |
| 223 | public suspend operator fun hasNext(): Boolean |
| 224 | |
| 225 | /** |
| 226 | * Retrieves and removes the element from this channel suspending the caller while this channel |
| 227 | * [isEmpty][ReceiveChannel.isEmpty] or throws [ClosedReceiveChannelException] if the channel |
Roman Elizarov | 9556242 | 2017-09-27 17:41:01 +0300 | [diff] [blame] | 228 | * [isClosedForReceive][ReceiveChannel.isClosedForReceive] without cause. |
Roman Elizarov | f6fed2a | 2017-02-03 19:12:09 +0300 | [diff] [blame] | 229 | * It throws the original [close][SendChannel.close] cause exception if the channel has _failed_. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 230 | * |
Roman Elizarov | d82b3a9 | 2017-06-23 21:52:08 +0300 | [diff] [blame] | 231 | * This suspending function is cancellable. If the [Job] of the current coroutine is cancelled or completed while this |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 232 | * function is suspended, this function immediately resumes with [CancellationException]. |
Roman Elizarov | a74eb5f | 2017-05-11 20:15:18 +0300 | [diff] [blame] | 233 | * |
| 234 | * *Cancellation of suspended receive is atomic* -- when this function |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 235 | * throws [CancellationException] it means that the element was not retrieved from this channel. |
Roman Elizarov | a74eb5f | 2017-05-11 20:15:18 +0300 | [diff] [blame] | 236 | * As a side-effect of atomic cancellation, a thread-bound coroutine (to some UI thread, for example) may |
| 237 | * continue to execute even after it was cancelled from the same thread in the case when this receive operation |
| 238 | * was already resumed and the continuation was posted for execution to the thread's queue. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 239 | * |
| 240 | * Note, that this function does not check for cancellation when it is not suspended. |
| 241 | * Use [yield] or [CoroutineScope.isActive] to periodically check for cancellation in tight loops if needed. |
| 242 | */ |
| 243 | public suspend operator fun next(): E |
| 244 | } |
| 245 | |
| 246 | /** |
| 247 | * Channel is a non-blocking primitive for communication between sender using [SendChannel] and receiver using [ReceiveChannel]. |
| 248 | * Conceptually, a channel is similar to [BlockingQueue][java.util.concurrent.BlockingQueue], |
| 249 | * but it has suspending operations instead of blocking ones and it can be closed. |
Roman Elizarov | 4b0ef7b | 2017-04-17 12:39:29 +0300 | [diff] [blame] | 250 | * |
Roman Elizarov | f2a710a | 2017-07-21 18:33:59 +0300 | [diff] [blame] | 251 | * See `Channel(capacity)` factory function for the description of available channel implementations. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 252 | */ |
Roman Elizarov | 7b2d8b0 | 2017-02-02 20:09:14 +0300 | [diff] [blame] | 253 | public interface Channel<E> : SendChannel<E>, ReceiveChannel<E> { |
| 254 | /** |
Roman Elizarov | f2a710a | 2017-07-21 18:33:59 +0300 | [diff] [blame] | 255 | * Constants for channel factory function `Channel()`. |
Roman Elizarov | 7b2d8b0 | 2017-02-02 20:09:14 +0300 | [diff] [blame] | 256 | */ |
| 257 | public companion object Factory { |
| 258 | /** |
Roman Elizarov | f2a710a | 2017-07-21 18:33:59 +0300 | [diff] [blame] | 259 | * Requests channel with unlimited capacity buffer in `Channel(...)` factory function -- |
Roman Elizarov | 3aed4ee | 2017-03-06 12:21:05 +0300 | [diff] [blame] | 260 | * the [LinkedListChannel] gets created. |
Roman Elizarov | 2ad0e94 | 2017-02-28 19:14:08 +0300 | [diff] [blame] | 261 | */ |
| 262 | public const val UNLIMITED = Int.MAX_VALUE |
| 263 | |
| 264 | /** |
Roman Elizarov | f2a710a | 2017-07-21 18:33:59 +0300 | [diff] [blame] | 265 | * Requests conflated channel in `Channel(...)` factory function -- |
Roman Elizarov | 3aed4ee | 2017-03-06 12:21:05 +0300 | [diff] [blame] | 266 | * the [ConflatedChannel] gets created. |
| 267 | */ |
| 268 | public const val CONFLATED = -1 |
| 269 | |
| 270 | /** |
Roman Elizarov | 8385ec9 | 2017-05-11 18:32:52 +0300 | [diff] [blame] | 271 | * Creates a channel with the specified buffer capacity (or without a buffer by default). |
Roman Elizarov | f2a710a | 2017-07-21 18:33:59 +0300 | [diff] [blame] | 272 | * @suppress **Deprecated** |
Roman Elizarov | 7b2d8b0 | 2017-02-02 20:09:14 +0300 | [diff] [blame] | 273 | */ |
Roman Elizarov | f2a710a | 2017-07-21 18:33:59 +0300 | [diff] [blame] | 274 | @Deprecated("Replaced with top-level function", level = DeprecationLevel.HIDDEN) |
| 275 | public operator fun <E> invoke(capacity: Int = 0): Channel<E> = Channel(capacity) |
Roman Elizarov | 7b2d8b0 | 2017-02-02 20:09:14 +0300 | [diff] [blame] | 276 | } |
| 277 | } |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 278 | |
| 279 | /** |
Roman Elizarov | f2a710a | 2017-07-21 18:33:59 +0300 | [diff] [blame] | 280 | * Creates a channel without a buffer -- [RendezvousChannel]. |
| 281 | */ |
| 282 | public fun <E> Channel(): Channel<E> = RendezvousChannel<E>() |
| 283 | |
| 284 | /** |
| 285 | * Creates a channel with the specified buffer capacity (or without a buffer by default). |
| 286 | * |
| 287 | * The resulting channel type depends on the specified [capacity] parameter: |
| 288 | * * when `capacity` is 0 -- creates [RendezvousChannel] without a buffer; |
| 289 | * * when `capacity` is [Channel.UNLIMITED] -- creates [LinkedListChannel] with buffer of unlimited size; |
| 290 | * * when `capacity` is [Channel.CONFLATED] -- creates [ConflatedChannel] that conflates back-to-back sends; |
| 291 | * * when `capacity` is positive, but less than [UNLIMITED] -- creates [ArrayChannel] with a buffer of the specified `capacity`; |
| 292 | * * otherwise -- throws [IllegalArgumentException]. |
| 293 | */ |
| 294 | public fun <E> Channel(capacity: Int): Channel<E> = |
| 295 | when (capacity) { |
| 296 | 0 -> RendezvousChannel() |
| 297 | UNLIMITED -> LinkedListChannel() |
| 298 | CONFLATED -> ConflatedChannel() |
| 299 | else -> ArrayChannel(capacity) |
| 300 | } |
| 301 | |
| 302 | /** |
Roman Elizarov | f6fed2a | 2017-02-03 19:12:09 +0300 | [diff] [blame] | 303 | * Indicates attempt to [send][SendChannel.send] on [isClosedForSend][SendChannel.isClosedForSend] channel |
Roman Elizarov | 9556242 | 2017-09-27 17:41:01 +0300 | [diff] [blame] | 304 | * that was closed without a cause. A _failed_ channel rethrows the original [close][SendChannel.close] cause |
Roman Elizarov | f6fed2a | 2017-02-03 19:12:09 +0300 | [diff] [blame] | 305 | * exception on send attempts. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 306 | */ |
Roman Elizarov | a197d6d | 2017-02-20 16:11:40 +0300 | [diff] [blame] | 307 | public class ClosedSendChannelException(message: String?) : CancellationException(message) |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 308 | |
| 309 | /** |
| 310 | * Indicates attempt to [receive][ReceiveChannel.receive] on [isClosedForReceive][ReceiveChannel.isClosedForReceive] |
Roman Elizarov | 9556242 | 2017-09-27 17:41:01 +0300 | [diff] [blame] | 311 | * channel that was closed without a cause. A _failed_ channel rethrows the original [close][SendChannel.close] cause |
Roman Elizarov | f6fed2a | 2017-02-03 19:12:09 +0300 | [diff] [blame] | 312 | * exception on receive attempts. |
Roman Elizarov | 187eace | 2017-01-31 09:39:58 +0300 | [diff] [blame] | 313 | */ |
Roman Elizarov | f6fed2a | 2017-02-03 19:12:09 +0300 | [diff] [blame] | 314 | public class ClosedReceiveChannelException(message: String?) : NoSuchElementException(message) |