A trimmed-down API

[fzhinkin]

Reduced kotlinx-io API shape by removing all niche and specific APIs.

Moved as many functions as possible to extensions, improved test coverage, and added documentation.

Docs generated for current branch are here: https://fzhinkin.github.io/kotlinx-io-dokka-docs-preview/

What changed compared to the previous preview version, in detail:

• removed select API;
• removed ByteStrings;
• removed hash functions API;
• added unsigned integer types support;
• Sink::writeByte and Sink::writeShort now accept Byte and Short instead of Int;
• Sink, Source, and Buffer no longer implement ByteChannels on JVM; functions returning wrappers around instances of these classes and implementing ByteChannels were provided instead;
• introduced DelicateIoApi annotation, marked Sink::buffer, Sink::emitCompleteSegments, and Source::buffer with it;
• enabled code coverage collection using Kover;
• enabled Dokka for documentation;
• turned on explicit API mode.

Some issues were not addressed yet:

• choose and document consistent behavior when it comes to throwing exceptions (Improve and explicitly document policies regarding exception throwing #138);
• choose new naming for read/write methods (Inconsistent and confusing Sink/Source read/write-methods naming #137).
• readFully behaves inconsistently with other read methods in case of thrown exception (Source::readFully inconsistent with other read methods #139).

What's out of this change's scope and will be resolved later:

• performance;
• ByteStrings;
• replacement for cursor API.

Closes #132

[whyoleg]

I think it's better to return the buffered source itself from the Source::buffered / Sink::buffered instead of introducing a deprecated method.

May be then it will be sufficient to do something like this:

public fun RawSource.buffered(): Source = when(this) {
    is Source -> this
    else      -> RealSource(this)
}

(same for sink)

[swankjesse]

@whyoleg I recommendation against a feature to prevent multiple buffer wrappers. We were occasionally tempted to do this for Okio!

The runtime cost of redundant buffering is nearly zero. (This is a consequence of how data is moved and not copied between layers.)

And it creates quite surprising behaviour consequences. For example it makes code that forgets to call ‘emit()’ or ‘flush()’ work sometimes when it shouldn’t.

[fzhinkin]

@whyoleg I recommendation against a feature to prevent multiple buffer wrappers. We were occasionally tempted to do this for Okio!

The runtime cost of redundant buffering is nearly zero. (This is a consequence of how data is moved and not copied between layers.)

And it creates quite surprising behaviour consequences. For example it makes code that forgets to call ‘emit()’ or ‘flush()’ work sometimes when it shouldn’t.

For me, it seems like both modes are legit - one may want to always wrap a Source into another Source, at least for testing, while in some cases, it may add an overhead (yeah, copying segments between buffers is fast, but the cost is non zero).
I think we can leave old behavior for now and discuss alternatives in a separate issue.

[whyoleg]

@swankjesse after looking for a while on examples in kdoc of flush and emit in Okio - I'm now thinking, that you are right that it will be not really expected behaviour if we will just return same object.

[shanshin]

Waiting for completion

[whyoleg]

@fzhinkin can you update preview documentation (https://github.com/fzhinkin/kotlinx-io-dokka-docs-preview) after all latest changes - it's much more easier to check all available public API there as members and extensions are there in one list and sorted by name ?

[fzhinkin]

@fzhinkin can you update preview documentation (https://github.com/fzhinkin/kotlinx-io-dokka-docs-preview) after all latest changes - it's much more easier to check all available public API there as members and extensions are there in one list and sorted by name ?

@whyoleg done, thanks for reminding me!

[qwwdfsad]

Great job!

Left a few minor comments, feel free to address them as you see fit

[qwwdfsad]

It seemed like this method was useful even without explicit asynchrony (and was, in fact, not related to coroutines-based cancellation); I might be mistaken though, anyway worth initiating the discussion