Clarify await and awaitAtLeast contract (#24)

Author: Sergey Mashkov

kotlinx-coroutines-io/common/src/kotlinx/coroutines/io/ByteChannelSequential.kt

@@ -474,6 +474,7 @@ abstract class ByteChannelSequentialBase(initial: IoBuffer, override val autoFlu
 
     override suspend fun await(atLeast: Int): Boolean {
         require(atLeast >= 0) { "atLeast parameter shouldn't be negative: $atLeast"}
+        require(atLeast <= 4088) { "atLeast parameter shouldn't be larger than max buffer size of 4088: $atLeast" }
 
         completeReading()
 

kotlinx-coroutines-io/common/src/kotlinx/coroutines/io/ReadSession.kt

@@ -38,6 +38,7 @@ interface SuspendableReadSession : ReadSession {
      * @return true if there are [atLeast] bytes available or false if end of stream encountered (there still could be
      * bytes available but less than [atLeast])
      * @throws Throwable if the channel has been closed with an exception or cancelled
+     * @throws IllegalArgumentException if [atLeast] is negative to too big (usually bigger that 4088)
      */
     suspend fun await(atLeast: Int = 1): Boolean
 }

kotlinx-coroutines-io/jvm/src/kotlinx/coroutines/io/ByteBufferChannel.kt

@@ -1930,6 +1930,9 @@ internal class ByteBufferChannel(
     }
 
     final override suspend fun awaitAtLeast(n: Int): Boolean {
+        require(n >= 0) { "atLeast parameter shouldn't be negative: $n" }
+        require(n <= 4088) { "atLeast parameter shouldn't be larger than max buffer size of 4088: $n" }
+
         if (state.capacity.availableForRead >= n) {
             if (state.idle || state is ReadWriteBufferState.Writing) setupStateForRead()
             return true
@@ -2464,6 +2467,9 @@ internal class ByteBufferChannel(
         override fun request(skip: Int, atLeast: Int): ByteBuffer? = null
 
         override suspend fun awaitAtLeast(n: Int): Boolean {
+            require(n >= 0) { "atLeast parameter shouldn't be negative: $n" }
+            require(n <= 4088) { "atLeast parameter shouldn't be larger than max buffer size of 4088: $n" }
+
             return false
         }
     }

kotlinx-coroutines-io/jvm/src/kotlinx/coroutines/io/LookAheadSession.kt

@@ -27,6 +27,7 @@ interface LookAheadSession {
 interface LookAheadSuspendSession : LookAheadSession {
     /**
      * Suspend until [n] bytes become available or end of stream encountered (possibly due to exceptional close)
+     * @see SuspendableReadSession.await
      */
     suspend fun awaitAtLeast(n: Int): Boolean
 }