Sink

sealed interface Sink : RawSink(source)

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

Link copied to clipboard

This sink's internal buffer. It contains data written to the sink, but not yet flushed to the upstream.

Functions

Link copied to clipboard

Returns WritableByteChannel backed by this sink. Closing the channel will also close the sink.

Link copied to clipboard
fun Sink.asNSOutputStream(): <Error class: unknown class>

Returns an output stream that writes to this sink. Closing the stream will also close this sink.

Link copied to clipboard

Returns an output stream that writes to this sink. Closing the stream will also close this sink.

Link copied to clipboard

Returns a new sink that buffers writes to the sink. The returned sink will batch writes to the sink. Use this wherever you write to a sink to get ergonomic and efficient access to data.

Link copied to clipboard
expect abstract override fun close()

Pushes all buffered bytes to their final destination and releases the resources held by this sink. It is an error to write a closed sink. It is safe to close a sink more than once.

Link copied to clipboard
abstract fun emit()

Writes all buffered data to the underlying sink if one exists. The underlying sink will not be explicitly flushed.

Link copied to clipboard
abstract override fun flush()

Writes all buffered data to the underlying sink, if one exists. Then the underlying sink is explicitly flushed.

Link copied to clipboard
abstract fun hintEmit()

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.

Link copied to clipboard
abstract fun transferFrom(source: RawSource): Long

Removes all bytes from source and write them to this sink. Returns the number of bytes read which will be 0 if source is exhausted.

Link copied to clipboard
expect abstract fun write(source: Buffer, byteCount: Long)

Removes byteCount bytes from source and appends them to this sink.

abstract fun write(source: RawSource, byteCount: Long)

Removes byteCount bytes from source and write them to this sink.

abstract fun write(source: ByteArray, startIndex: Int = 0, endIndex: Int = source.size)

Writes bytes from source array or its subrange to this sink.

Link copied to clipboard
fun Sink.write(byteString: ByteString, startIndex: Int = 0, endIndex: Int = byteString.size)

Writes subsequence of data from byteString starting at startIndex and ending at endIndex into a sink.

fun Sink.write(source: ByteBuffer): Int

Writes data from the source into this sink and returns the number of bytes written.

Link copied to clipboard
abstract fun writeByte(byte: Byte)

Writes a byte to this sink.

Link copied to clipboard
fun Sink.writeCodePointValue(codePoint: Int)

Encodes codePoint in UTF-8 and writes it to this sink.

Link copied to clipboard

Writes long to this sink in signed decimal form (i.e., as a string in base 10).

Link copied to clipboard
fun Sink.writeDouble(double: Double)

Writes eight bytes of a bit representation of double, in the big-endian order, to this sink. Bit representation of the double corresponds to the IEEE 754 floating-point "double format" bit layout.

Link copied to clipboard

Writes eight bytes of a bit representation of double, in the little-endian order, to this sink. Bit representation of the double corresponds to the IEEE 754 floating-point "double format" bit layout.

Link copied to clipboard
fun Sink.writeFloat(float: Float)

Writes four bytes of a bit representation of float, in the big-endian order, to this sink. Bit representation of the float corresponds to the IEEE 754 floating-point "single format" bit layout.

Link copied to clipboard
fun Sink.writeFloatLe(float: Float)

Writes four bytes of a bit representation of float, in the little-endian order, to this sink. Bit representation of the float corresponds to the IEEE 754 floating-point "single format" bit layout.

Link copied to clipboard

Writes long to this sink in hexadecimal form (i.e., as a string in base 16).

Link copied to clipboard
abstract fun writeInt(int: Int)

Writes four bytes containing int, in the big-endian order, to this sink.

Link copied to clipboard
fun Sink.writeIntLe(int: Int)

Writes four bytes containing int, in the little-endian order, to this sink.

Link copied to clipboard
abstract fun writeLong(long: Long)

Writes eight bytes containing long, in the big-endian order, to this sink.

Link copied to clipboard
fun Sink.writeLongLe(long: Long)

Writes eight bytes containing long, in the little-endian order, to this sink.

Link copied to clipboard
abstract fun writeShort(short: Short)

Writes two bytes containing short, in the big-endian order, to this sink.

Link copied to clipboard
fun Sink.writeShortLe(short: Short)

Writes two bytes containing short, in the little-endian order, to this sink.

Link copied to clipboard
fun Sink.writeString(chars: CharSequence, startIndex: Int = 0, endIndex: Int = chars.length)

Encodes the characters at startIndex up to endIndex from chars in UTF-8 and writes it to this sink.

fun Sink.writeString(string: String, startIndex: Int = 0, endIndex: Int = string.length)

Encodes the characters at startIndex up to endIndex from string in UTF-8 and writes it to this sink.

fun Sink.writeString(string: String, charset: Charset, startIndex: Int = 0, endIndex: Int = string.length)

Encodes substring of string starting at startIndex and ending at endIndex using charset and writes into this sink.

Link copied to clipboard

Provides direct access to the sink's internal buffer and hints its emit before exit.

Link copied to clipboard
fun Sink.writeUByte(byte: UByte)

Writes am unsigned byte to this sink.

Link copied to clipboard
fun Sink.writeUInt(int: UInt)

Writes four bytes containing int, in the big-endian order, to this sink.

Link copied to clipboard

Writes four bytes containing int, in the little-endian order, to this sink.

Link copied to clipboard
fun Sink.writeULong(long: ULong)

Writes eight bytes containing long, in the big-endian order, to this sink.

Link copied to clipboard

Writes eight bytes containing long, in the little-endian order, to this sink.

Link copied to clipboard
fun Sink.writeUShort(short: UShort)

Writes two bytes containing short, in the big-endian order, to this sink.

Link copied to clipboard

Writes two bytes containing short, in the little-endian order, to this sink.