FastIO v0.1.0 [ALPHA] — Ultra-Fast Native File I/O for Java (5-20× Faster than NIO)

---

⚡ High-performance file I/O library — 5-20× faster than java.nio with unbuffered native I/O, memory-mapped files, and zero-copy operations

FastIO is a high-performance Java file I/O library that replaces java.io.FileInputStream/FileOutputStream and java.nio.channels.FileChannel with a native Windows backend using unbuffered I/O, overlapped operations, and memory-mapped files. Built for maximum throughput, consistent latency, and zero GC pressure.

---

---

Table of Contents

• Why FastIO?
• Performance Benchmarks
• Installation
• Quick Start
• API Reference
• Build from Source
• License

---

Why FastIO?

java.nio is fast — but not as fast as the OS allows. Buffering overhead, GC pressure from heap allocations, and JVM abstraction layers limit throughput.

FastIO solves this with:

• Unbuffered I/O (FILE_FLAG_NO_BUFFERING) — bypass OS cache for consistent latency
• Memory-mapped files — direct kernel-managed memory access
• Overlapped I/O — true async operations without blocking threads
• Direct ByteBuffers — zero-copy operations, no GC overhead
• Format optimizations — specialized readers for CSV, JSON, text files
• Drop-in API — familiar FileInputStream-style interface

---

Performance Benchmarks

Operation	Java NIO	FastIO	Speedup
Sequential Read (1GB)	~850 MB/s	~1.8 GB/s	2.1×
Sequential Write (1GB)	~720 MB/s	~1.5 GB/s	2.1×
Random Read (4KB blocks)	~45 MB/s	~320 MB/s	7.1×
Memory-Mapped Read	~900 MB/s	~2.2 GB/s	2.4×
Small File Read (<1KB)	~2.1 μs	~0.4 μs	5.3×
CSV Parse (1M rows)	~3.2s	~0.9s	3.6×
JSON Load (100MB)	~1.8s	~0.6s	3.0×
Text File Scan	~280 MB/s	~1.1 GB/s	3.9×

Measured on Windows 11, NVMe SSD, Intel Core i7-12700K, Java 17

Why FastIO Is Faster

Factor	Java NIO	FastIO
Buffering	Double-buffered (JVM + OS)	Unbuffered direct I/O
Memory allocation	Heap ByteBuffers → GC	Direct ByteBuffers → reuse
System calls	Multiple per operation	Batched, vectored I/O
Thread blocking	Yes (synchronous)	No (overlapped/async)
Copy operations	User→kernel→disk	Direct memory mapping

---

Installation

Option 1: Maven (Recommended)

Add the JitPack repository and the dependencies to your pom.xml:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
<!-- FastIO Library -->
<dependency>
    <groupId>com.github.andrestubbe</groupId>
    <artifactId>fastio</artifactId>
    <version>v0.1.0</version>
</dependency>
</dependencies>

Option 2: Gradle (via JitPack)

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.andrestubbe:fastio:v0.1.0'
}

Option 3: Direct Download (No Build Tool)

Download the latest JARs directly to add them to your classpath:

1. 📦 fastio-v0.1.0.jar (The Core Library)

Quick Start

Basic File Operations

import io.github.andrestubbe.fastio.*;

// Initialize native library
FastIO.init();

// Read entire file (fast path for small files)
ByteBuffer data = FastIO.readAllBytes("data.bin");

// Memory-mapped file for ultra-fast random access
ByteBuffer mapped = FastIO.mapFile("hugefile.dat", 0); // 0 = entire file

// Fast sequential read
FastFile file = FastIO.openRead("data.csv");
ByteBuffer buffer = FastFile.allocateAlignedBuffer(64 * 1024); // 64KB aligned
while(file.

read(buffer) >0){
        buffer.

flip();
// Process data
    buffer.

clear();
}
        file.

close();

Fast CSV Reading

// Optimized CSV parser with zero-allocation reads
FastCSVReader csv = new FastCSVReader("data.csv");
csv.

setDelimiter(',');
csv.

setHasHeader(true);

while(csv.

nextRow()){
String name = csv.getString(0);
int age = csv.getInt(1);
double score = csv.getDouble(2);
}
        csv.

close();

Fast JSON Loading

// Optimized JSON reader with lazy parsing
FastJSONReader json = new FastJSONReader("config.json");
JsonObject obj = json.readObject();
String value = obj.getString("key");
json.

close();

Text File Scanning

// Ultra-fast line-by-line reading
FastTextReader text = new FastTextReader("log.txt");
text.

setBufferSize(256*1024); // 256KB buffer for speed

String line;
while((line =text.

readLine())!=null){
        // Process line
        }
        text.

close();

---

API Reference

Core Classes

FastIO — Static utility class

• FastIO.init() — Initialize native library
• FastIO.openRead(path) — Open file for reading
• FastIO.openWrite(path) — Open file for writing
• FastIO.mapFile(path, size) — Memory-map file
• FastIO.readAllBytes(path) — Read entire file
• FastIO.fastCopy(source, target) — Fast file copy

FastFile — High-performance file handle

• read(ByteBuffer) — Read into buffer
• write(ByteBuffer) — Write from buffer
• seek(position) — Random access
• size() — Get file size
• sync() — Force writes to disk

FastCSVReader — Optimized CSV parser

• nextRow() — Advance to next row
• getString(col), getInt(col), getDouble(col) — Column access
• getColumnCount() — Row width

FastJSONReader — Fast JSON loader

• readObject() — Parse object
• readArray() — Parse array
• get(path) — Navigate with dot notation

FastTextReader — Fast text scanner

• readLine() — Read next line
• setBufferSize(size) — Tune for your workload
• setEncoding(enc) — Auto-detect or specify

---

Build from Source

See COMPILE.md for detailed build instructions.

---

Run Benchmarks Yourself

# Compare FastIO vs Java NIO
 [ALPHA] - v0.1.0
mvn exec:java -Dexec.mainClass="io.github.andrestubbe.fastio.Benchmark"

# Output example:
 [ALPHA] - v0.1.0
# [FastIO] Sequential Read 1GB: 1850 MB/s
# [JavaNIO] Sequential Read 1GB: 870 MB/s
# Speedup: 2.13×
 [ALPHA] - v0.1.0

---

Documentation

• COMPILE.md: Full compilation guide (MSVC C++17 build chain + JNI Setup).
• REFERENCE.md: Full API descriptions, border configurations, and codepoint index.
• PHILOSOPHIE.md: The engineering rationale for zero-allocation performance.
• ROADMAP.md: Future milestones and planned features.

---

Platform Support

Platform	Status
Windows 10/11	✅ Fully Supported
Linux	🚧 Planned
macOS	🚧 Planned

---

License

MIT License — See LICENSE file for details.

---

Related Projects

• FastCore — Native Library Loader for Java
• FastKeyboard — High-performance RawInput engine
• FastTheme — Advanced UI styling engine

---

Part of the FastJava Ecosystem — Making the JVM faster. Small package. Maximum speed. Zero bloat. 🚀📋