Caution
⚠ Work-In-Progress.
API may be not completely stable yet!
Benchmarks and complete test coverage are coming.
// in the `build.gradle.kts` of the target module.
plugins {
kotlin("multiplatform") version "2.2.21"
}
dependencies {
implementation("io.github.fluxo-kt:fluxo-io:0.1.0")
}0.1.0 is the latest published version. From 0.2.0 the coordinate becomes
io.github.fluxo-kt:fluxo-io-rad. The rest of this README describes 0.2.0,
which is not published yet: 0.1.0 has only the Rad…Accessor factories
(Rad.forX from Java), without open, slice, share, asAsync or the
adapter modules.
Use only versions that exist in Maven Central or the Central Portal snapshot repository. This module is alpha; do not assume unpublished coordinates are available.
Library provides cross-platform RandomAccessData
abstraction for effective read-only random access to binary data: positional
reads, no-copy slices, and shared handles that free the resource when the
last one closes.
RandomAccessData.open("data.bin").use { rad ->
val header = ByteArray(16)
rad.readFully(header, position = 0)
val body = rad.slice(16) // a view to the end: no copy, nothing to close
}Reads block the calling thread. To suspend instead, wrap any instance:
rad.asAsync(Dispatchers.IO) (JS and Wasm have no Dispatchers.IO; use
Dispatchers.Default). Sources that are async by nature
(AsyncRandomAccessData.open(path) on Node, open(blob) in a browser) never
block while reading; opening a Node file is one quick synchronous call.
| Platform | RandomAccessData.open(path) reads with |
Also |
|---|---|---|
| JVM | FileChannel positional reads |
open(File), open(Path) (also from Java) |
| Android | FileChannel positional reads |
open(ParcelFileDescriptor), open(AssetFileDescriptor) |
| Apple, Linux, Android Native | pread |
|
| Windows (mingw) | ReadFile at an offset |
|
| JS, Wasm-JS | Node fs (Node, Bun, Deno) |
AsyncRandomAccessData.open(path); JS: open(blob) |
| Wasm-WASI | fd_pread under a preopened directory |
|
| All | — | RadByteArrayAccessor(bytes) |
A browser has no file system, so open(path) throws there.
Which one when (JVM/Android):
| API | Use when |
|---|---|
RandomAccessData.open(…) |
Default for files: safe if the file shrinks, any size |
| ByteBufferMmap (memory-mapped file) |
Hot random reads of a file < 2 GiB that nobody truncates |
| ByteBuffer | Data already in a ByteBuffer |
| ByteArray | Data already in memory |
| FileChannel | An open channel or descriptor you hand over |
| RandomAccessFile | An open RandomAccessFile you hand over |
| SeekableByteChannel | Any other seekable channel (e.g. zip file systems) |
| () -> InputStream Factory | Only streams exist; each read may reopen and skip |
| () -> DataInput Factory | Same, for DataInput |
| () -> ReadableByteChannel Factory | Same, for channels |
Tip
On JVM and Android, ByteBuffer reads, transferTo(channel) and an
InputStream view are provided for existing APIs.
Adapter modules, which keep Okio and kotlinx-io out of the core (it depends
only on the Kotlin stdlib, plus AtomicFU off the JVM). Adapters call the core's internal API,
so they must match its version: Gradle aligns them on its own (every module depends on
io.github.fluxo-kt:fluxo-io-bom); with Maven, import that BOM.
io.github.fluxo-kt:fluxo-io-rad-okio:RandomAccessData.open(FileHandle),RandomAccessData.asFileHandle()andRandomAccessData.source(position).io.github.fluxo-kt:fluxo-io-rad-kotlinx-io:RandomAccessData.asRawSource(position).
History notes
The first steps of the implementation were dated 2021-03-31 (2d87ec044f5801cd3ad8cc31ac380b17fa31d44a).
Open-source since 2024-06-16.
- Okio
- Kotlinx IO
- Ktor IO
- DitchOoM Buffer
- Karma Krafts kMMIO (Lightweight KMP MMIO)
Uses SemVer for versioning.
For the versions available, see the tags on this repository.
This project is licensed under the Apache License, Version 2.0 — see the license file for details.