Package io.ktor.utils.io

Types

ByteChannel
interface ByteChannel : ByteReadChannel, ByteWriteChannel

Channel for asynchronous reading and writing of sequences of bytes. This is a buffered single-reader single-writer channel.

ByteChannelSequentialBase
abstract class ByteChannelSequentialBase : 
    ByteChannel,
    ByteReadChannel,
    ByteWriteChannel,
    SuspendableReadSession,
    HasReadSession,
    HasWriteSession

Sequential (non-concurrent) byte channel implementation

ByteChannelSequentialJVM
class ByteChannelSequentialJVM : ByteChannelSequentialBase

ByteReadChannel
expect interface ByteReadChannel

Channel for asynchronous reading of sequences of bytes. This is a single-reader channel.

ByteWriteChannel
expect interface ByteWriteChannel

Channel for asynchronous writing of sequences of bytes. This is a single-writer channel.

LookAheadSession
interface LookAheadSession

LookAheadSuspendSession
interface LookAheadSuspendSession : LookAheadSession

ReadSession
interface ReadSession

ReaderJob
interface ReaderJob : Job

A coroutine job that is reading from a byte channel

ReaderScope
interface ReaderScope : CoroutineScope

SuspendableReadSession
interface SuspendableReadSession : ReadSession

WriterJob
interface WriterJob : Job

A coroutine job that is writing to a byte channel

WriterScope
interface WriterScope : CoroutineScope

WriterSession
interface WriterSession

WriterSuspendSession
interface WriterSuspendSession : WriterSession

Exceptions

ClosedWriteChannelException
class ClosedWriteChannelException : CancellationException

Indicates attempt to write on isClosedForWrite channel that was closed without a cause. A failed channel rethrows the original close cause exception on send attempts.

Type Aliases

CancellationException
typealias CancellationException = CancellationException

ConsumeEachBufferVisitor
typealias ConsumeEachBufferVisitor = (buffer: ByteBuffer, last: Boolean) -> Boolean

Extensions for External Classes

kotlinx.coroutines.CoroutineScope

Properties

EmptyByteReadChannel
val EmptyByteReadChannel: ByteReadChannel

Byte channel that is always empty.

Functions

ByteChannel
expect fun ByteChannel(
    autoFlush: Boolean = false
): ByteChannel

Creates buffered channel for asynchronous reading and writing of sequences of bytes.

ByteReadChannel
expect fun ByteReadChannel(
    content: ByteArray,
    offset: Int = 0,
    length: Int = content.size
): ByteReadChannel

Creates channel for reading from the specified byte array. Please note that it could use content directly or copy it’s bytes depending on the platform

fun ByteReadChannel(
    text: String,
    charset: Charset = Charsets.UTF_8
): ByteReadChannel
fun ByteReadChannel(content: ByteBuffer): ByteReadChannel

Creates channel for reading from the specified byte buffer.

cancel
fun ByteReadChannel.cancel(): Boolean

close
fun ByteWriteChannel.close(): Boolean

Closes this channel with no failure (successfully)

consumeEachBufferRange
suspend fun ByteReadChannel.consumeEachBufferRange(
    visitor: ConsumeEachBufferVisitor
): Unit

For every available bytes range invokes visitor function until it return false or end of stream encountered

consumeEachRemaining
fun LookAheadSession.consumeEachRemaining(
    visitor: (ByteBuffer) -> Boolean
): Unit
suspend fun LookAheadSuspendSession.consumeEachRemaining(
    visitor: suspend (ByteBuffer) -> Boolean
): Unit

copyAndClose
suspend fun ByteReadChannel.copyAndClose(
    dst: ByteWriteChannel,
    limit: Long = Long.MAX_VALUE
): Long

Reads all the bytes from receiver channel and writes them to dst channel and then closes it. Closes dst channel if fails to read or write with cause exception.

copyTo
suspend fun ByteChannelSequentialBase.copyTo(
    dst: ByteChannelSequentialBase,
    limit: Long = Long.MAX_VALUE
): Long
suspend expect fun ByteReadChannel.copyTo(
    dst: ByteWriteChannel,
    limit: Long = Long.MAX_VALUE
): Long

Reads up to limit bytes from receiver channel and writes them to dst channel. Closes dst channel if fails to read or write with cause exception.

discard
suspend fun ByteReadChannel.discard(): Long

Discards all bytes in the channel and suspends until end of stream.

discardExact
suspend fun ByteReadChannel.discardExact(n: Long): Unit

Discards exactly n bytes or fails if not enough bytes in the channel

joinTo
suspend fun ByteChannelSequentialBase.joinTo(
    dst: ByteChannelSequentialBase,
    closeOnEnd: Boolean
): Unit
suspend expect fun ByteReadChannel.joinTo(
    dst: ByteWriteChannel,
    closeOnEnd: Boolean
): Unit

read
suspend fun ByteReadChannel.read(
    desiredSize: Int = 1,
    block: (source: Memory, start: Long, endExclusive: Long) -> Int
): Int

Await until at least desiredSize is available for read or EOF and invoke block function. The block function should never capture a provided Memory instance outside otherwise an undefined behaviour may occur including accidental crash or data corruption. Block function should return number of bytes consumed or 0.

readAvailable
suspend fun ByteReadChannel.readAvailable(
    dst: ByteArray
): Int

readDouble
suspend fun ByteReadChannel.readDouble(
    byteOrder: ByteOrder
): Double

readDoubleLittleEndian
suspend fun ByteReadChannel.readDoubleLittleEndian(): Double

readFloat
suspend fun ByteReadChannel.readFloat(
    byteOrder: ByteOrder
): Float

readFloatLittleEndian
suspend fun ByteReadChannel.readFloatLittleEndian(): Float

readFully
suspend fun ByteReadChannel.readFully(dst: IoBuffer): Unit
suspend fun ByteReadChannel.readFully(dst: ByteArray): Unit

readInt
suspend fun ByteReadChannel.readInt(
    byteOrder: ByteOrder
): Int

readIntLittleEndian
suspend fun ByteReadChannel.readIntLittleEndian(): Int

readLong
suspend fun ByteReadChannel.readLong(
    byteOrder: ByteOrder
): Long

readLongLittleEndian
suspend fun ByteReadChannel.readLongLittleEndian(): Long

readPacket
suspend fun ByteReadChannel.readPacket(
    size: Int
): ByteReadPacket

Reads the specified amount of bytes and makes a byte packet from them. Fails if channel has been closed and not enough bytes available.

readRemaining
suspend fun ByteReadChannel.readRemaining(
    limit: Long
): ByteReadPacket

Reads up to limit bytes and makes a byte packet or until end of stream encountered.

suspend fun ByteReadChannel.readRemaining(): ByteReadPacket

Reads all remaining bytes and makes a byte packet

readShort
suspend fun ByteReadChannel.readShort(
    byteOrder: ByteOrder
): Short

readShortLittleEndian
suspend fun ByteReadChannel.readShortLittleEndian(): Short

readUTF8Line
suspend fun ByteReadChannel.readUTF8Line(): String?

readUTF8LineTo
suspend fun ByteReadChannel.readUTF8LineTo(
    out: Appendable
): Boolean

readUntilDelimiter
suspend fun ByteReadChannel.readUntilDelimiter(
    delimiter: ByteBuffer,
    dst: ByteBuffer
): Int

Reads from the channel to the specified dst byte buffer until one of the following:

reader
fun reader(
    coroutineContext: <ERROR CLASS>,
    channel: ByteChannel,
    parent: Job? = null,
    block: suspend ReaderScope.() -> Unit
): ReaderJob
fun reader(
    coroutineContext: <ERROR CLASS>,
    autoFlush: Boolean = false,
    parent: Job? = null,
    block: suspend ReaderScope.() -> Unit
): ReaderJob

skipDelimiter
suspend fun ByteReadChannel.skipDelimiter(
    delimiter: ByteBuffer
): Unit

write
suspend fun ByteWriteChannel.write(
    desiredSpace: Int = 1,
    block: (freeSpace: Memory, startOffset: Long, endExclusive: Long) -> Int
): Int

Await for desiredSpace will be available for write and invoke block function providing Memory instance and the corresponding range suitable for wiring in the memory. The block function should return number of bytes were written, possibly 0.

writeAvailable
suspend fun ByteWriteChannel.writeAvailable(
    src: ByteArray
): Int

writeBoolean
suspend fun ByteWriteChannel.writeBoolean(b: Boolean): Unit

writeByte
suspend fun ByteWriteChannel.writeByte(b: Int): Unit

writeChar
suspend fun ByteWriteChannel.writeChar(ch: Char): Unit

Writes UTF16 character

writeDouble
suspend fun ByteWriteChannel.writeDouble(
    value: Double,
    byteOrder: ByteOrder
): Unit

writeDoubleLittleEndian
suspend fun ByteWriteChannel.writeDoubleLittleEndian(
    value: Double
): Unit

writeFloat
suspend fun ByteWriteChannel.writeFloat(
    value: Float,
    byteOrder: ByteOrder
): Unit

writeFloatLittleEndian
suspend fun ByteWriteChannel.writeFloatLittleEndian(
    value: Float
): Unit

writeFully
suspend fun ByteWriteChannel.writeFully(src: ByteArray): Unit

writeInt
suspend fun ByteWriteChannel.writeInt(i: Long): Unit
suspend fun ByteWriteChannel.writeInt(
    i: Long,
    byteOrder: ByteOrder
): Unit
suspend fun ByteWriteChannel.writeInt(
    value: Int,
    byteOrder: ByteOrder
): Unit

writeIntLittleEndian
suspend fun ByteWriteChannel.writeIntLittleEndian(
    value: Int
): Unit

writeLong
suspend fun ByteWriteChannel.writeLong(
    value: Long,
    byteOrder: ByteOrder
): Unit

writeLongLittleEndian
suspend fun ByteWriteChannel.writeLongLittleEndian(
    value: Long
): Unit

writePacket
suspend fun ByteWriteChannel.writePacket(
    headerSizeHint: Int = 0,
    builder: BytePacketBuilder.() -> Unit
): Unit

writePacketSuspend
suspend fun ByteWriteChannel.writePacketSuspend(
    builder: suspend BytePacketBuilder.() -> Unit
): Unit

writeShort
suspend fun ByteWriteChannel.writeShort(s: Int): Unit
suspend fun ByteWriteChannel.writeShort(
    s: Int,
    byteOrder: ByteOrder
): Unit
suspend fun ByteWriteChannel.writeShort(
    value: Short,
    byteOrder: ByteOrder
): Unit

writeShortLittleEndian
suspend fun ByteWriteChannel.writeShortLittleEndian(
    value: Short
): Unit

writeStringUtf8
suspend fun ByteWriteChannel.writeStringUtf8(
    s: CharSequence
): Unit
suspend fun ByteWriteChannel.writeStringUtf8(s: String): Unit

writer
fun writer(
    coroutineContext: <ERROR CLASS>,
    channel: ByteChannel,
    parent: Job? = null,
    block: suspend WriterScope.() -> Unit
): WriterJob
fun writer(
    coroutineContext: <ERROR CLASS>,
    autoFlush: Boolean = false,
    parent: Job? = null,
    block: suspend WriterScope.() -> Unit
): WriterJob