or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

byte-order-operations.mdchannel-factories.mdchannel-interfaces.mdchannel-operations.mdcharacter-encoding.mdindex.mdobject-pooling.md
tile.json

tessl/gradle-io-ktor--ktor-io

Ktor I/O module providing asynchronous byte channel operations, character encoding, and object pooling for multiplatform applications.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes

pkg:gradle/io.ktor/ktor-io@3.2.x

To install, run

npx @tessl/cli install tessl/gradle-io-ktor--ktor-io@3.2.0

index.mddocs/

Ktor I/O

Ktor I/O provides asynchronous I/O primitives for Kotlin multiplatform applications, specifically designed for non-blocking byte stream operations. This module implements byte channels, buffer management, and streaming operations built on top of kotlinx-io.

Package Information

  • Package Name: io.ktor:ktor-io
  • Package Type: gradle
  • Language: Kotlin
  • Installation: implementation("io.ktor:ktor-io:3.2.0")

Core Imports

import io.ktor.utils.io.*

For specific functionality:

import io.ktor.utils.io.ByteReadChannel
import io.ktor.utils.io.ByteWriteChannel
import io.ktor.utils.io.ByteChannel
import io.ktor.utils.io.charsets.Charsets
import io.ktor.utils.io.pool.ObjectPool
import io.ktor.utils.io.bits.reverseByteOrder

Basic Usage

import io.ktor.utils.io.*
import kotlinx.coroutines.*

suspend fun basicChannelUsage() {
    // Create a byte channel for reading and writing
    val channel = ByteChannel()
    
    // Write data asynchronously
    launch {
        channel.writeStringUtf8("Hello, World!")
        channel.flushAndClose()
    }
    
    // Read data asynchronously
    val text = channel.readUTF8Line()
    println(text) // "Hello, World!"
}

// Create a read channel from existing data
suspend fun readFromData() {
    val readChannel = ByteReadChannel("Sample text data")
    val content = readChannel.toByteArray()
    println(String(content)) // "Sample text data"
}

Architecture

Ktor I/O is built around several key components:

  • Channel Interfaces: Core abstractions for reading (ByteReadChannel) and writing (ByteWriteChannel) byte streams
  • Channel Implementations: Concrete implementations like ByteChannel for sequential I/O operations
  • Extension Operations: Rich set of convenience methods for common I/O operations (read/write primitives, text handling)
  • Character Encoding: Support for various character encodings and charset operations
  • Object Pooling: Memory-efficient object reuse patterns for high-performance scenarios
  • Byte Order Operations: Utilities for handling different byte orderings and bit manipulation

Capabilities

Channel Interfaces

Core channel abstractions for asynchronous byte I/O operations. These provide the foundation for all streaming operations in Ktor.

interface ByteReadChannel {
    val closedCause: Throwable?
    val isClosedForRead: Boolean
    suspend fun awaitContent(min: Int = 1): Boolean
    fun cancel(cause: Throwable?)
    
    companion object {
        val Empty: ByteReadChannel
    }
}

interface ByteWriteChannel {
    val isClosedForWrite: Boolean
    val closedCause: Throwable?
    suspend fun flush()
    suspend fun flushAndClose()
    fun cancel(cause: Throwable?)
}

interface BufferedByteWriteChannel : ByteWriteChannel {
    fun flushWriteBuffer()
    fun close()
}

Channel Interfaces

Channel Operations

Comprehensive set of read and write operations for primitive types, byte arrays, and text content. Essential for actual data transfer through channels.

// Read operations
suspend fun ByteReadChannel.readByte(): Byte
suspend fun ByteReadChannel.readInt(): Int
suspend fun ByteReadChannel.readLong(): Long
suspend fun ByteReadChannel.readUTF8Line(max: Int = Int.MAX_VALUE): String?
suspend fun ByteReadChannel.toByteArray(): ByteArray
suspend fun ByteReadChannel.copyTo(channel: ByteWriteChannel): Long

// Write operations  
suspend fun ByteWriteChannel.writeByte(value: Byte)
suspend fun ByteWriteChannel.writeInt(value: Int)
suspend fun ByteWriteChannel.writeLong(value: Long)
suspend fun ByteWriteChannel.writeStringUtf8(value: String)
suspend fun ByteWriteChannel.writeByteArray(array: ByteArray)

Channel Operations

Channel Factories

Factory functions and constructors for creating various types of byte channels from different data sources.

fun ByteReadChannel(content: ByteArray, offset: Int = 0, length: Int = content.size): ByteReadChannel
fun ByteReadChannel(text: String, charset: Charset = Charsets.UTF_8): ByteReadChannel
class ByteChannel(autoFlush: Boolean = false) : ByteReadChannel, BufferedByteWriteChannel

Channel Factories

Character Encoding

Character encoding and decoding support with charset management for text processing operations.

expect abstract class Charset
expect object Charsets {
    val UTF_8: Charset
    val ISO_8859_1: Charset
    fun isSupported(name: String): Boolean
    fun forName(name: String): Charset
}

expect abstract class CharsetEncoder
expect abstract class CharsetDecoder

Character Encoding

Object Pooling

Memory-efficient object pooling system for reusing expensive objects like byte arrays.

interface ObjectPool<T : Any> {
    val capacity: Int
    fun borrow(): T
    fun recycle(instance: T)
    fun dispose()
}

val ByteArrayPool: ObjectPool<ByteArray>

Object Pooling

Byte Order Operations

Utilities for byte order manipulation and bit-level operations for handling different endianness.

fun Short.reverseByteOrder(): Short
fun Int.reverseByteOrder(): Int
fun Long.reverseByteOrder(): Long
fun Float.reverseByteOrder(): Float
fun Double.reverseByteOrder(): Double

val Short.highByte: Byte
val Short.lowByte: Byte
val Int.highShort: Short
val Int.lowShort: Short

Byte Order Operations

Types

// Exception types
open class ClosedByteChannelException : IOException()
class ClosedWriteChannelException : ClosedByteChannelException()
class ClosedReadChannelException : ClosedByteChannelException()
class ConcurrentIOException : IllegalStateException()
open class MalformedInputException(message: String) : IOException()
class TooLongLineException(message: String) : MalformedInputException(message)

// Line ending mode
value class LineEndingMode {
    companion object {
        val CR: LineEndingMode
        val LF: LineEndingMode  
        val CRLF: LineEndingMode
        val Any: LineEndingMode
    }
    
    operator fun contains(other: LineEndingMode): Boolean
    operator fun plus(other: LineEndingMode): LineEndingMode
}

// Utility wrappers
class CountedByteReadChannel(delegate: ByteReadChannel) : ByteReadChannel {
    val totalBytesRead: Long
}

class CountedByteWriteChannel(delegate: ByteWriteChannel) : ByteWriteChannel {
    val totalBytesWritten: Long
}