Sink
A sink that facilitates typed data writes and keeps a buffer internally so that caller can write some data without sending it directly to an upstream.
Sink is the main kotlinx-io interface to write data in client's code, any RawSink could be turned into Sink using RawSink.buffered.
Depending on the kind of upstream and the number of bytes written, buffering may improve the performance by hiding the latency of small writes.
Data stored inside the internal buffer could be sent to an upstream using flush, emit, or hintEmit:
flush writes the whole buffer to an upstream and then flushes the upstream.
emit writes all data from the buffer into the upstream without flushing it.
hintEmit hints the source that current write operation is now finished and a part of data from the buffer may be partially emitted into the upstream. The latter is aimed to reduce memory footprint by keeping the buffer as small as possible without excessive writes to the upstream. All write operations implicitly calls hintEmit.
Write methods' behavior and naming conventions
Methods writing a value of some type are usually named write<Type>, like writeByte or writeInt, except methods writing data from a some collection of bytes, like write(ByteArray, Int, Int) or write(source: RawSource, byteCount: Long). In the latter case, if a collection is consumable (i.e., once data was read from it will no longer be available for reading again), write method will consume as many bytes as it was requested to write.
Methods fully consuming its argument are named transferFrom, like transferFrom.
It is recommended to follow the same naming convention for Sink extensions.
Thread-safety guarantees
Until stated otherwise, Sink implementations are not thread safe. If a Sink needs to be accessed from multiple threads, an additional synchronization is required.
Inheritors
Properties
Functions
Returns WritableByteChannel backed by this sink. Closing the channel will also close the sink.
Returns an output stream that writes to this sink. Closing the stream will also close this sink.
Returns an output stream that writes to this sink. Closing the stream will also close this sink.
Hints that the buffer may be partially emitted (see emit) to the underlying sink. The underlying sink will not be explicitly flushed. There are no guarantees that this call will cause emit of buffered data as well as there are no guarantees how many bytes will be emitted.
Writes bytes from source array or its subrange to this sink.
Writes subsequence of data from byteString starting at startIndex and ending at endIndex into a sink.
Writes data from the source into this sink and returns the number of bytes written.
Encodes codePoint in UTF-8 and writes it to this sink.
Writes long to this sink in signed decimal form (i.e., as a string in base 10).
Writes long to this sink in hexadecimal form (i.e., as a string in base 16).
Writes four bytes containing int, in the little-endian order, to this sink.
Writes eight bytes containing long, in the little-endian order, to this sink.
Writes two bytes containing short, in the big-endian order, to this sink.
Writes two bytes containing short, in the little-endian order, to this sink.
Encodes the characters at startIndex up to endIndex from chars in UTF-8 and writes it to this sink.
Encodes the characters at startIndex up to endIndex from string in UTF-8 and writes it to this sink.
Encodes substring of string starting at startIndex and ending at endIndex using charset and writes into this sink.
Provides direct access to the sink's internal buffer and hints its emit before exit.
Writes am unsigned byte to this sink.
Writes four bytes containing int, in the little-endian order, to this sink.
Writes eight bytes containing long, in the big-endian order, to this sink.
Writes eight bytes containing long, in the little-endian order, to this sink.
Writes two bytes containing short, in the big-endian order, to this sink.
Writes two bytes containing short, in the little-endian order, to this sink.