ByteChannel

interface ByteChannel : ByteReadChannel, ByteWriteChannel

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

Read operations can be invoked concurrently with write operations, but multiple reads or multiple writes cannot be invoked concurrently with themselves. Exceptions are close and flush which can be invoked concurrently with any other operations and between themselves at any time.

Inherited Properties

autoFlush

abstract val autoFlush: Boolean

Returns true if channel flushes automatically all pending bytes after every write function call. If false then flush only happens at manual flush invocation or when the buffer is full.

availableForRead

abstract val availableForRead: Int

Returns number of bytes that can be read without suspension. Read operations do no suspend and return immediately when this number is at least the number of bytes requested for read.

availableForWrite

abstract val availableForWrite: Int

Returns number of bytes that can be written without suspension. Write operations do no suspend and return immediately when this number is at least the number of bytes requested for write.

closedCause

abstract val closedCause: Throwable?

An closure cause exception or null if closed successfully or not yet closed

isClosedForRead

abstract val isClosedForRead: Boolean

Returns true if the channel is closed and no remaining bytes are available for read. It implies that availableForRead is zero.

isClosedForWrite

abstract val isClosedForWrite: Boolean

readByteOrder

abstract var readByteOrder: ByteOrder

Byte order that is used for multi-byte read operations (such as readShort, readInt, readLong, readFloat, and readDouble).

totalBytesRead

abstract val totalBytesRead: Long

Number of bytes read from the channel. It is not guaranteed to be atomic so could be updated in the middle of long running read operation.

totalBytesWritten

abstract val totalBytesWritten: Long

Number of bytes written to the channel. It is not guaranteed to be atomic so could be updated in the middle of write operation.

writeByteOrder

abstract var writeByteOrder: ByteOrder

Byte order that is used for multi-byte write operations (such as writeShort, writeInt, writeLong, writeFloat, and writeDouble).

Inherited Functions

cancel

abstract fun cancel(cause: Throwable? = null): Boolean

Close channel with optional cause cancellation. Unlike ByteWriteChannel.close that could close channel normally, cancel does always close with error so any operations on this channel will always fail and all suspensions will be resumed with exception.

close

abstract fun close(cause: Throwable? = null): Boolean

Closes this channel with an optional exceptional cause. It flushes all pending write bytes (via flush). This is an idempotent operation – repeated invocations of this function have no effect and return false.

consumeEachBufferRange

abstract suspend fun consumeEachBufferRange(
    visitor: ConsumeEachBufferVisitor
): Unit

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

discard

abstract suspend fun discard(
    max: Long = Long.MAX_VALUE
): Long

Discard up to max bytes

flush

abstract fun flush(): Unit

Flushes all pending write bytes making them available for read.

lookAhead

abstract fun <R> lookAhead(
    visitor: LookAheadSession.() -> R
): R

lookAheadSuspend

abstract suspend fun <R> lookAheadSuspend(
    visitor: suspend LookAheadSuspendSession.() -> R
): R

read

abstract suspend fun read(
    min: Int = 1,
    block: (ByteBuffer) -> Unit
): Unit

Invokes block when it will be possible to read at least min bytes providing byte buffer to it so lambda can read from the buffer up to ByteBuffer.remaining bytes. If there are no min bytes available then the invocation could suspend until the requirement will be met.

readAvailable

abstract suspend fun readAvailable(
    dst: ByteArray,
    offset: Int,
    length: Int
): Int

Reads all available bytes to dst buffer and returns immediately or suspends if no bytes available

open suspend fun readAvailable(dst: ByteArray): Int
abstract suspend fun readAvailable(dst: ByteBuffer): Int
abstract suspend fun readAvailable(dst: BufferView): Int

readBoolean

abstract suspend fun readBoolean(): Boolean

Reads a boolean value (suspending if no bytes available yet) or fails if channel has been closed and not enough bytes.

readByte

abstract suspend fun readByte(): Byte

Reads a byte (suspending if no bytes available yet) or fails if channel has been closed and not enough bytes.

readDouble

abstract suspend fun readDouble(): Double

Reads double number (suspending if not enough bytes available) or fails if channel has been closed and not enough bytes.

readFloat

abstract suspend fun readFloat(): Float

Reads float number (suspending if not enough bytes available) or fails if channel has been closed and not enough bytes.

readFully

abstract suspend fun readFully(
    dst: ByteArray,
    offset: Int,
    length: Int
): Unit

Reads all length bytes to dst buffer or fails if channel has been closed. Suspends if not enough bytes available.

open suspend fun readFully(dst: ByteArray): Unit
abstract suspend fun readFully(dst: ByteBuffer): Int

readInt

abstract suspend fun readInt(): Int

Reads an int number (suspending if not enough bytes available) or fails if channel has been closed and not enough bytes.

readLong

abstract suspend fun readLong(): Long

Reads a long number (suspending if not enough bytes available) or fails if channel has been closed and not enough bytes.

readPacket

abstract suspend fun readPacket(
    size: Int,
    headerSizeHint: Int = 0
): 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. Accepts headerSizeHint to be provided, see WritePacket.

readShort

abstract suspend fun readShort(): Short

Reads a short number (suspending if not enough bytes available) or fails if channel has been closed and not enough bytes.

readUTF8LineTo

abstract suspend fun <A> readUTF8LineTo(
    out: A,
    limit: Int = Int.MAX_VALUE
): Boolean

Reads a line of UTF-8 characters to the specified out buffer up to limit characters. Supports both CR-LF and LF line endings. Throws an exception if the specified limit has been exceeded.

write

abstract suspend fun write(
    min: Int = 1,
    block: (ByteBuffer) -> Unit
): Unit

Invokes block when it will be possible to write at least min bytes providing byte buffer to it so lambda can write to the buffer up to ByteBuffer.remaining bytes. If there are no min bytes spaces available then the invocation could suspend until the requirement will be met.

writeAvailable

abstract suspend fun writeAvailable(
    src: ByteArray,
    offset: Int,
    length: Int
): Int

Writes as much as possible and only suspends if buffer is full

open suspend fun writeAvailable(src: ByteArray): Int
abstract suspend fun writeAvailable(src: ByteBuffer): Int
abstract suspend fun writeAvailable(src: BufferView): Int

writeByte

abstract suspend fun writeByte(b: Byte): Unit

Writes byte and suspends until written. Crashes if channel get closed while writing.

writeDouble

abstract suspend fun writeDouble(d: Double): Unit

Writes double number and suspends until written. Crashes if channel get closed while writing.

writeFloat

abstract suspend fun writeFloat(f: Float): Unit

Writes float number and suspends until written. Crashes if channel get closed while writing.

writeFully

abstract suspend fun writeFully(
    src: ByteArray,
    offset: Int,
    length: Int
): Unit

Writes all src bytes and suspends until all bytes written. Causes flush if buffer filled up or when autoFlush Crashes if channel get closed while writing.

open suspend fun writeFully(src: ByteArray): Unit
abstract suspend fun writeFully(src: ByteBuffer): Unit
abstract suspend fun writeFully(src: BufferView): Unit

writeInt

abstract suspend fun writeInt(i: Int): Unit

Writes int number and suspends until written. Crashes if channel get closed while writing.

writeLong

abstract suspend fun writeLong(l: Long): Unit

Writes long number and suspends until written. Crashes if channel get closed while writing.

writePacket

abstract suspend fun writePacket(
    packet: ByteReadPacket
): Unit

Writes a packet fully or fails if channel get closed before the whole packet has been written

writeShort

abstract suspend fun writeShort(s: Short): Unit

Writes short number and suspends until written. Crashes if channel get closed while writing.

writeSuspendSession

abstract suspend fun writeSuspendSession(
    visitor: suspend WriterSuspendSession.() -> Unit
): Unit

writeWhile

abstract suspend fun writeWhile(
    block: (ByteBuffer) -> Boolean
): Unit

Invokes block for every free buffer until it return false. It will also suspend every time when no free space available for write.

Extension Functions

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 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.

copyTo

suspend fun ByteReadChannel.copyTo(
    out: OutputStream,
    limit: Long = Long.MAX_VALUE
): Long

Copies up to limit bytes from this byte channel to out stream suspending on read channel and blocking on output

copyTo

suspend fun ByteReadChannel.copyTo(
    channel: WritableByteChannel,
    limit: Long = Long.MAX_VALUE
): Long

Copy up to limit bytes to blocking NIO channel. Copying to non-blocking channel requires selection and not supported. It does suspend if no data available in byte channel but may block if destination NIO channel blocks.

suspend fun ByteReadChannel.copyTo(
    pipe: Pipe,
    limit: Long = Long.MAX_VALUE
): Long

Copy up to limit bytes to blocking pipe. A shortcut to copyTo function with NIO channel destination

joinTo

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

readASCIILine

suspend fun ByteReadChannel.readASCIILine(
    estimate: Int = 16,
    limit: Int = Int.MAX_VALUE
): String?

readLine

suspend fun ByteReadChannel.readLine(
    estimate: Int = 16,
    limit: Int = Int.MAX_VALUE
): String?

readRemaining

suspend fun ByteReadChannel.readRemaining(
    limit: Int = Int.MAX_VALUE
): ByteReadPacket

Reads all the bytes from receiver channel and builds a packet that is returned unless the specified limit exceeded. It will simply stop reading and return packet of size limit in this case

readUTF8Line

suspend fun ByteReadChannel.readUTF8Line(
    estimate: Int = 16,
    limit: Int = Int.MAX_VALUE
): String?

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:

skipDelimiter

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

toInputStream

fun ByteReadChannel.toInputStream(
    parent: Job? = null
): InputStream

Create blocking java.io.InputStream for this channel that does block every time the channel suspends at read Similar to do reading in runBlocking however you can pass it to regular blocking API

toOutputStream

fun ByteWriteChannel.toOutputStream(
    parent: Job? = null
): OutputStream

Create blocking java.io.OutputStream for this channel that does block every time the channel suspends at write Similar to do reading in runBlocking however you can pass it to regular blocking API

write

suspend fun ByteWriteChannel.write(src: ByteArray): Unit
suspend fun ByteWriteChannel.write(
    src: ByteArray,
    offset: Int,
    length: Int
): Unit

See java.io.DataOutput.write

writeBoolean

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

writeByte

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

writeBytes

suspend fun ByteWriteChannel.writeBytes(s: String): Unit

See java.io.DataOutput.writeBytes

writeChar

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

Writes UTF16 character

writeChars

suspend fun ByteWriteChannel.writeChars(s: String): Unit

See java.io.DataOutput.writeChars

writeInt

suspend fun ByteWriteChannel.writeInt(i: Long): Unit

writePacket

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

writePacketSuspend

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

writeShort

suspend fun ByteWriteChannel.writeShort(s: Int): Unit

writeStringUtf8

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

writeUTF

suspend fun ByteWriteChannel.writeUTF(s: String): Unit

See java.io.DataOutput.writeUTF