ByteWriteChannel

expect interface ByteWriteChannel

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

Operations on this channel cannot be invoked concurrently, unless explicitly specified otherwise in description. Exceptions are close and flush.

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.

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

isClosedForWrite

abstract val isClosedForWrite: Boolean

Returns true is channel has been closed and attempting to write to the channel will cause an exception.

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

Functions

close

abstract fun close(cause: Throwable?): 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.

flush

abstract fun flush(): Unit

Flushes all pending write bytes making them available for read.

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

abstract suspend fun writeAvailable(src: IoBuffer): Int
abstract suspend fun writeAvailable(src: ByteBuffer): 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.

abstract suspend fun writeFully(src: IoBuffer): Unit
abstract suspend fun writeFully(src: ByteBuffer): 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

bufferedWriter

fun ByteWriteChannel.bufferedWriter(
    charset: Charset = Charsets.UTF_8
): BufferedWriter

Open a buffered writer to the channel

close

Closes this channel with no failure (successfully)

deflated

fun ByteWriteChannel.deflated(
    gzip: Boolean = true,
    pool: ObjectPool<ByteBuffer> = KtorDefaultPool,
    coroutineContext: <ERROR CLASS> = Dispatchers.Unconfined
): ByteWriteChannel

Launch a coroutine on coroutineContext that does deflate compression optionally doing CRC and writing GZIP header and trailer if gzip = true

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

use

fun ByteWriteChannel.use(
    block: ByteWriteChannel.() -> Unit
): Unit

Executes block on ByteWriteChannel and close it down correctly whether an exception

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.

write

suspend fun ByteWriteChannel.write(
    string: String,
    charset: Charset = Charsets.UTF_8
): Unit

Write a string in the specified charset

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 ByteWriteChannel.writer(
    charset: Charset = Charsets.UTF_8
): Writer

Open a writer to the channel

Inheritors

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