🔀 SSIO

Streaming Suspend Input Output library for Kotlin Multiplatform.
This is an async IO extension for kotlinx.io based on the async API proposal.

Features

• Supports all Kotlin Multiplatform targets
• AsyncReadOnlyFileSystem interface
• AsyncFileSystem interface
• AsyncCloseable interface
• AsyncRawSource interface
• AsyncRawSink interface
• AsyncSource wrapper for buffering raw async sources
• AwaitPredicate interface for await conditions like exhausted and available
• DiscardingAsyncSink object for voiding data
• RandomAsyncSource object for sourcing an endless pseudo-random byte stream
• AsyncSystemFileSystem global file system instance via the ssio-core module
• AsyncVirtualFileSystem class via the ssio-vfs module
• AsyncNoopFileSystem object via the ssio-noop module

Platforms

The following matrix illustrates what implementations are used for which target & runtime combination
in the ssio-core implementation:

Target	Runtime	Implementation
JVM	JVM	NIO
Android	ART	NIO
Linux	Kotlin/Native	CIO/io_uring*
Windows	Kotlin/Native	CIO
macOS	Kotlin/Native	CIO
iOS	Kotlin/Native	CIO
tvOS	Kotlin/Native	CIO
watchOS	Kotlin/Native	CIO
JS	Browser	OPFS
JS	NodeJS	fs.promises
WASM	Browser	OPFS
WASM	NodeJS	fs.promises

NOTE: Implementations marked with an asterisk* are used only when the underlying system supports them.

Why should I use this over kotlinx.io or java.nio?

The answer is simple: you shouldn't if you don't need a suspend IO API available in your common source set.
If you do, this library is probably what you're looking for.

How to use it

First, add the official Maven Central repository to your settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

Then add a dependency on the library in your root buildscript:

kotlin {
    sourceSets {
        commonMain {
            dependencies {
                implementation("dev.karmakrafts.ssio:ssio-core:<version>")
            }
        }
    }
}

Or, if you are only using Kotlin/JVM, add it to your top-level dependencies block instead.

How to build it

In order to build SSIO, simply clone this project and run the publishToMavenLocal task:

./gradlew publishToMavenLocal

Or on Windows:

gradlew publishToMavenLocal

Extra steps on Linux

Since the library is built against liburing on Linux, you need to have Linux headers available
under /usr/src/linux-headers. If you need to install them, you can use the provided install_linux_headers.sh
script from the root of the repository.
This assumes a Debian based system and requires the following dependencies to be installed:

Ubuntu/PopOS

build-essential make automake autoconf pkg-config pkgconf libtool gcc bison flex

Official build support for other distributions may be requested.