Indexed fill & flush; Non-copy read/write API

  * add indexes to Input.fill & Output.flush to avoid partial reads/writes.
It unlocks the implementation of non-copy API for reading and writing, and
it allows to read into a buffer with a small number of bytes at the start
without additional flush.
  * add `readAvailableTo` and `writeBuffer`
This API reads/writes bytes directly from source to provided buffer without
creating an additional copy.

Author: e5l

.gitignore

@@ -15,3 +15,8 @@ kotlinx-io-native/repo/
 !.idea/codeStyles/*
 
 .gradletasknamecache
+.settings
+.classpath
+
+logs
+

benchmarks/commonMain/src/kotlinx/io/benchmarks/InputReadingBenchmark.kt

@@ -12,9 +12,9 @@ class InputReadingBenchmark {
 
             override fun closeSource() {}
 
-            override fun fill(buffer: Buffer): Int {
+            override fun fill(buffer: Buffer, startIndex: Int, endIndex: Int): Int {
                 val size = buffer.size
-                for (index in 0 until size) {
+                for (index in startIndex until endIndex) {
                     buffer.storeByteAt(index, value++.toByte())
                 }
                 return size

benchmarks/commonMain/src/kotlinx/io/benchmarks/TextDecodingBenchmark.kt

@@ -8,17 +8,19 @@ private val expected = "file content with unicode 🌀 : здороваться
 private val length = expected.length
 
 // @formatter:off
-    private val content = ubyteArrayOf(
-        0x66u,0x69u,0x6cu,0x65u,0x20u,0x63u,0x6fu,0x6eu,0x74u,0x65u,0x6eu,0x74u,0x20u,
-        0x77u,0x69u,0x74u,0x68u,0x20u,0x75u,0x6eu,0x69u,0x63u,0x6fu,0x64u,0x65u,0x20u,0xf0u,0x9fu,
-        0x8cu,0x80u,0x20u,0x3au,0x20u,0xd0u,0xb7u,0xd0u,0xb4u,0xd0u,0xbeu,0xd1u,0x80u,0xd0u,0xbeu,
-        0xd0u,0xb2u,0xd0u,0xb0u,0xd1u,0x82u,0xd1u,0x8cu,0xd1u,0x81u,0xd1u,0x8fu,0x20u,0x3au,0x20u,0xecu,
-        0x97u,0xacu,0xebu,0xb3u,0xb4u,0xecu,0x84u,0xb8u,0xecu,0x9au,0x94u,0x20u,0x3au,0x20u,0xe4u,0xbdu,0xa0u,
-        0xe5u,0xa5u,0xbdu,0x20u,0x3au,0x20u,0xc3u,0xb1u,0xc3u,0xa7u, 0x2eu)
-    // @formatter:on
+private val content = ubyteArrayOf(
+    0x66u, 0x69u, 0x6cu, 0x65u, 0x20u, 0x63u, 0x6fu, 0x6eu, 0x74u, 0x65u, 0x6eu, 0x74u, 0x20u,
+    0x77u, 0x69u, 0x74u, 0x68u, 0x20u, 0x75u, 0x6eu, 0x69u, 0x63u, 0x6fu, 0x64u, 0x65u, 0x20u,
+    0xf0u, 0x9fu, 0x8cu, 0x80u, 0x20u, 0x3au, 0x20u, 0xd0u, 0xb7u, 0xd0u, 0xb4u, 0xd0u, 0xbeu,
+    0xd1u, 0x80u, 0xd0u, 0xbeu, 0xd0u, 0xb2u, 0xd0u, 0xb0u, 0xd1u, 0x82u, 0xd1u, 0x8cu, 0xd1u,
+    0x81u, 0xd1u, 0x8fu, 0x20u, 0x3au, 0x20u, 0xecu, 0x97u, 0xacu, 0xebu, 0xb3u, 0xb4u, 0xecu,
+    0x84u, 0xb8u, 0xecu, 0x9au, 0x94u, 0x20u, 0x3au, 0x20u, 0xe4u, 0xbdu, 0xa0u, 0xe5u, 0xa5u,
+    0xbdu, 0x20u, 0x3au, 0x20u, 0xc3u, 0xb1u, 0xc3u, 0xa7u, 0x2eu
+)
+// @formatter:on
 
 private val bytes = buildBytes {
-    writeArray(content)
+    writeByteArray(content)
 }
 
 @State(Scope.Benchmark)
@@ -44,7 +46,7 @@ class TextDecodingBenchmark {
 */
         return text
     }
-    
+
     @Benchmark
     fun inputTextShort(): String {
         val input = bytes.input()

build.gradle

@@ -10,7 +10,6 @@ buildscript {
 
     dependencies {
         classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
-        classpath "org.jetbrains.kotlinx:atomicfu-gradle-plugin:$atomic_fu_version"
         classpath "org.jetbrains.kotlin:kotlin-allopen:$kotlin_version"
         classpath "org.jetbrains.kotlinx:kotlinx.benchmark.gradle:$benchmarks_version"
         classpath "com.vanniktech:gradle-android-junit-jacoco-plugin:0.15.0"

core/build.gradle

@@ -1,8 +1,8 @@
 plugins {
     id "kotlin-multiplatform"
     id "maven-publish"
-    id "kotlinx-atomicfu"
     id "jacoco"
+    id 'org.jetbrains.dokka' version '0.10.1'
 }
 
 def ideaActive = System.getProperty('idea.active') == 'true'
@@ -131,6 +131,11 @@ kotlin {
     }
 }
 
+dokka {
+    outputFormat = 'gfm'
+    outputDirectory = "$buildDir/dokka"
+}
+
 jacoco {
     toolVersion = "0.8.5"
     reportsDir = file("${buildDir}/jacoco-reports")

core/commonMain/src/kotlinx/io/ByteOrder.common.kt

@@ -1,25 +1,25 @@
 package kotlinx.io
 
 /**
- * Enumeration that represent an endianness of the arbitrary binary data.
- * Endianness refers to the order of bytes within a binary representation of a binary data.
+ * ByteOrder is the enumeration that represents an endianness of the arbitrary binary data.
+ * Endianness refers to the order of bytes within a binary representation.
  */
 public expect enum class ByteOrder {
     /**
-     * Big endian, the most significant byte is at the lowest address.
+     * Big-endian: the most significant byte is at the lowest address.
      */
     BIG_ENDIAN,
 
     /**
-     * Little endian, the least significant byte is at the lowest address.
+     * Little-endian: the least significant byte is at the lowest address.
      */
     LITTLE_ENDIAN;
 
     public companion object {
         /**
-         * The native byte order of the underlying platform.
+         * The byte order of the underlying platform.
          */
-        public val native : ByteOrder
+        public val native: ByteOrder
     }
 }
 

core/commonMain/src/kotlinx/io/Bytes.kt

@@ -2,14 +2,15 @@ package kotlinx.io
 
 import kotlinx.io.buffer.*
 import kotlinx.io.pool.*
+import kotlin.contracts.*
 
 internal typealias BytesPointer = Int
 
 /**
  * Read-only bytes container.
  *
  * Use [input] to create readable [Input].
- * All inputs from a [Bytes] instance are share the same buffers.
+ * All inputs from a [Bytes] instance share the same buffers.
  *
  * ```
  * buildBytes {
@@ -20,28 +21,28 @@ internal typealias BytesPointer = Int
  * 3. example
  */
 class Bytes internal constructor(internal val bufferPool: ObjectPool<Buffer>) : Closeable {
-    private var buffers: Array<Buffer?> = arrayOfNulls(initialPreviewSize)
-    private var limits: IntArray = IntArray(initialPreviewSize)
-    private var head: Int = 0
-    private var tail: Int = 0
+    internal var buffers: Array<Buffer?> = arrayOfNulls(initialPreviewSize)
+    internal var limits: IntArray = IntArray(initialPreviewSize)
+    internal var head: Int = 0
+    internal var tail: Int = 0
 
     /**
-     * Calculate size of [Bytes].
+     * Calculate the size of [Bytes].
      */
     fun size(): Int = size(StartPointer)
 
     /**
      * Create [Input] view on content.
      */
-    fun input(): Input = object : Input(this@Bytes) {
+    fun input(): Input = object : Input(this@Bytes, bufferPool) {
+        override fun fill(buffer: Buffer, startIndex: Int, endIndex: Int): Int = 0
         override fun closeSource() {}
-        override fun fill(buffer: Buffer): Int = 0
     }
 
     override fun toString() = "Bytes($head..$tail)"
 
     /**
-     * Release all data. Every produced input is broken.
+     * Release all data, brokes all input produced by [input()].
      */
     override fun close(): Unit {
         (head until tail).forEach {
@@ -54,7 +55,7 @@ class Bytes internal constructor(internal val bufferPool: ObjectPool<Buffer>) :
 
     internal fun append(buffer: Buffer, limit: Int): Unit {
         if (head > 0) {
-            // if we are appending buffers after some were discarded, 
+            // if we are appending buffers after [discardFirst()],
             // compact arrays so we can store more without allocations
             buffers.copyInto(buffers, 0, head, tail)
             limits.copyInto(limits, 0, head, tail)
@@ -80,28 +81,17 @@ class Bytes internal constructor(internal val bufferPool: ObjectPool<Buffer>) :
         head++
     }
 
-    internal inline fun pointed(pointer: BytesPointer, consumer: (Int) -> Unit): Buffer {
-        // Buffer is returned and not sent to `consumer` because we need to initialize field in Input's constructor
-        val index = pointer + head
-        val buffer = buffers[index] ?: throw NoSuchElementException("There is no buffer at pointer $pointer")
-        val limit = limits[index]
-        consumer(limit)
-        return buffer
-    }
-
     internal fun limit(pointer: BytesPointer): Int = limits[pointer + head]
 
-    internal fun advancePointer(pointer: BytesPointer): BytesPointer = pointer + 1
-
     internal fun isEmpty() = tail == head
 
     internal fun isAfterLast(index: BytesPointer) = head + index >= tail
 
     internal fun size(pointer: BytesPointer): Int {
-        // ???: if Input.ensure operations are frequent enough, consider storing running size in yet another int array
         var sum = 0
-        for (index in (pointer + head) until tail)
+        for (index in (pointer + head) until tail) {
             sum += limits[index]
+        }
         return sum
     }
 
@@ -112,3 +102,17 @@ class Bytes internal constructor(internal val bufferPool: ObjectPool<Buffer>) :
         private const val initialPreviewSize = 1
     }
 }
+
+/**
+ * Get [Buffer] and limit according to [pointer] offset in [Bytes.buffers].
+ */
+internal inline fun Bytes.pointed(pointer: Int, consumer: (buffer: Buffer, limit: Int) -> Unit) {
+    contract {
+        callsInPlace(consumer, kind = InvocationKind.EXACTLY_ONCE)
+    }
+
+    val index = pointer + head
+    val buffer = buffers[index] ?: throw NoSuchElementException("There is no buffer at pointer $pointer.")
+    val limit = limits[index]
+    consumer(buffer, limit)
+}

core/commonMain/src/kotlinx/io/BytesBuilders.kt

@@ -1,7 +1,6 @@
 package kotlinx.io
 
 import kotlinx.io.buffer.*
-import kotlinx.io.buffer.DEFAULT_BUFFER_SIZE
 import kotlin.contracts.*
 
 /**
@@ -15,15 +14,18 @@ fun buildBytes(bufferSize: Int = DEFAULT_BUFFER_SIZE, builder: Output.() -> Unit
     return BytesOutput(bufferSize).apply(builder).bytes()
 }
 
-private class BytesOutput(bufferSize: Int = DEFAULT_BUFFER_SIZE) : Output(bufferSize) {
-    private val bytes = Bytes(bufferPool)
+private class BytesOutput(bufferSize: Int = DEFAULT_BUFFER_SIZE) : Output(
+    if (bufferSize == DEFAULT_BUFFER_SIZE) DefaultBufferPool.Instance else DefaultBufferPool(bufferSize)
+) {
+    private val bytes = Bytes(pool)
 
     fun bytes(): Bytes {
         close()
         return bytes
     }
 
-    override fun flush(source: Buffer, length: Int) {
+    override fun flush(source: Buffer, startIndex: Int, endIndex: Int) {
+        val length = source.compact(startIndex, endIndex)
         bytes.append(source, length)
     }
 

core/commonMain/src/kotlinx/io/Console.common.kt

@@ -1,8 +1,8 @@
 package kotlinx.io
 
 /**
- * Console incorporates all system inputs and outputs in a multiplatform manner.
- * All sources are open by default, ready to read from/write to and cannot be closed.
+ * [Console] incorporates all system inputs and outputs in a multiplatform manner.
+ * All sources are open by default, ready to read from/write to, and cannot be closed.
  */
 public expect object Console {
     /**

core/commonMain/src/kotlinx/io/Exceptions.kt

@@ -1,7 +1,36 @@
 package kotlinx.io
 
+import kotlinx.io.buffer.*
+
 expect open class IOException(message: String, cause: Throwable?) : Exception {
     constructor(message: String)
 }
 
 expect open class EOFException(message: String) : IOException
+
+internal fun checkBufferAndIndexes(buffer: Buffer, startIndex: Int, endIndex: Int) {
+    require(startIndex >= 0) { "Start index ($startIndex) should be positive." }
+    require(endIndex >= startIndex) { "End index ($endIndex) should be greater than start index ($startIndex)." }
+    require(endIndex <= buffer.size) {
+        "End index ($endIndex) cannot be greater than buffer size (${buffer.size})."
+    }
+}
+
+/**
+
+ */
+internal fun checkArrayStartAndLength(array: ByteArray, startIndex: Int, length: Int) {
+    require(startIndex >= 0) { "Start index ($startIndex) should be positive." }
+    require(length >= 0) { "Length ($length) should be positive." }
+    require(startIndex + length <= array.size) {
+        "(start index + length) (${startIndex} + ${length}) cannot be greater than array size (${array.size})."
+    }
+}
+
+internal fun checkSize(size: Int) {
+    require(size >= 0) { "Size ($size) cannot be negative." }
+}
+
+internal fun checkCount(count: Int) {
+    require(count >= 0) { "Count ($count) should be positive." }
+}