kotlinx-io API as a trimmed-down Okio API

[fzhinkin]

As a starting point for #131, kotlinx-io API should be implemented as a trimmed-down version for Okio API. The API should include only core IO primitives and allow to build any other functionality on top of it.

Parts of the Okio API that are likely to be removed include:

• select API;
• hash functions API;
• cursor API;
• ByteStrings (will be added back later).

Some of these APIs provide specific functionality required by particular libraries and apps and could be implemented on top of the existing API; others are unsafe and should be redesigned to reduce possible user issues. It's also clear that these APIs were implemented as part of the core Okio library to squeeze additional performance out of it. To make sure that these APIs can be implemented using kotlinx-io without the loss of performance, the new APIs will be introduced in the future (or, if there will be no other way to implement removed functionality efficiently, it may be added back to the kotlinx-io).

The goal is to provide concise, well-documented and tested API. Core IO primitives API, like sources and sinks, should include as little functionality as possible; everything that could be implemented on top of it should be moved to extension functions or removed.

[SPC-code]

Kotlinx-io Input/Output are much more powerful than okio primitives. Will it be possible to separate API and implementation in this regard? I also would like to see separate API artifact and separate implementation for IO in general.

[qwwdfsad]

I would suggest starting with use cases that you are solving with an API (either Okio and/or obsolete Input/Output) to help us shape the overall direction. The same question stands for the implementation -- what exactly you do want to implement?

[SPC-code]

@qwwdfsad I have two primary use-cases:

• Efficient binary/text data format reading for files and streams alike. For example: https://github.com/SciProgCentre/dataforge-core/blob/dev/dataforge-io/src/commonMain/kotlin/space/kscience/dataforge/io/TaggedEnvelopeFormat.kt
• Efficient streaming serialization/message processing for binary/text data for devices: https://github.com/SciProgCentre/controls.kt/blob/d1e9b0a5a5a4fa9475496b424368e34eaae63b73/controls-core/src/commonMain/kotlin/space/kscience/controls/ports/phrases.kt#L13

The first one already uses ktor-io extensively (I also use my own Binary extension which I need for composite formats. The second one uses buffer pulling and packets, but I am not fully happy with API yet.

[SPC-code]

As for separate API and implementation. It is important since kotlinx-io will probably be a base for a lot of solutions in Kotlin. It is quite possible, that we will want to use something different from okio in future (like it happened many times before with other technologies). I would like to be able to use api-only dependencies and choose implementation details later.

[qwwdfsad]

I have two primary use-cases

These two use cases will be solvable with the proposed API shape and similar performance characteristics, I do not see issues with the proposed Okio-based design right off the bat.

[SPC-code]

Okio Source and Sink are similar to Input and Output. But last time I tried, something did not work as I wanted. I will play with a prototype to report specific problems.

[qwwdfsad]

We are happy to have any feedback about the API, and are keen on addressing known and yet unknown problems, whether they are about API shape, naming or performance characteristics.
We'll do an initial release soon, and I suggest you try it.

Yet please consider being a bit more constructive -- the feedback "This API is more powerful, and it would be nice to address it" is non-actionable for us, and we cannot reasonably evolve based on it