Skip to content

Commit f492f9a

Browse files
andrestubbeandrestubbe
committed
Auto Update
1 parent 161f428 commit f492f9a

4 files changed

Lines changed: 77 additions & 15 deletions

File tree

‎.TODO.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# .TODO.md — FastCore Architecture Roadmap: Modernizing to Java 21+ FFM (Foreign Function & Memory API)
2+
3+
## 🎯 Strategisches Ziel
4+
Ablösung des veralteten, trägen JNI (aus Java 1.1 / 1997) durch die moderne, JIT-inlinbare **Foreign Function & Memory API (FFM)** als universelles Native-Backend für die gesamte **FastJava**-Suite.
5+
6+
---
7+
8+
## ⚡ Wird FastJava dadurch schneller? (Klare Antwort)
9+
10+
**JA, und zwar dramatisch – insbesondere überall dort, wo viele kleine native Aufrufe oder speicherintensive Off-Heap-Transfers stattfinden.**
11+
12+
### Warum FastJava durch FFM schneller wird:
13+
1. **Zero Call Overhead (JIT-Inlining & direkte CPU-Register)**:
14+
- **Altes JNI**: Bei jedem Aufruf muss die JVM den Thread-Status auf Native umschalten, einen GC-Safepoint-Check machen, Register auf den Stack sichern und `JNIEnv*` / `jobject` übergeben (~15–30 ns Overhead pro Call).
15+
- **Neues FFM**: Der HotSpot C2-Compiler kennt die native System-ABI (Windows x64 / Linux AMD64) und übergibt Parameter direkt über CPU-Register (`RCX`, `RDX`, `R8`, `R9`). Der Overhead sinkt auf **~2–5 ns** und kann bei Hot-Loops sogar geinlined werden.
16+
2. **Echtes Zero-Copy & GC-Freiheit**:
17+
- Keine temporären Puffer, kein Array-Pinning (`GetPrimitiveArrayCritical`), keine GC-Pausen.
18+
- Nahtlose Brücke zu **`FastPointer`** und **`FastMemory`**: Ein 64-Bit Pointer (`long`) wird ohne Konvertierung direkt als Maschinencode-Adresse in die nativen Vektor-Register (AVX2/AVX-512) geladen.
19+
3. **Reiner C/C++ Code ohne JNI-Ballast**:
20+
- Native Funktionen bleiben 100% sauberer Standard-C/C++-Code (`extern "C"`). Keine `jni.h`, kein `Java_...`-Präfix, volle Portabilität zu Bibliotheken wie `llama.cpp` oder Vulkan/DirectX.
21+
22+
---
23+
24+
## 🧩 Auswirkungen auf die FastJava-Module
25+
26+
| Modul | JNI-Problem | FFM-Gewinn |
27+
| :--- | :--- | :--- |
28+
| **FastAIModel** | Hunderte GEMV-Calls pro Token bremsen CPU-Durchsatz | **Direkte AVX2-Vektor-Pipeline via Register (Sprung auf 15–30 tok/s)** |
29+
| **FastGPU** | Buffer-Mapping erfordert JNI-Objektwrapping | **Zero-Copy Vulkan/CUDA Buffer Passing direkt via `MemorySegment`** |
30+
| **FastSIMD** | JNI-Boundary verhindert Vektorisierung kleiner Chunks | **JIT kann native AVX2/AVX-512 Instruktionen direkt verketten** |
31+
| **FastFileWatch** | Native ReadDirectoryChangesW Events müssen über JNI gemarshallt werden | **Direkte Ringbuffer-Verarbeitung im nativen Speicher** |
32+
| **FastFileSearch** | Syscall-Overhead bei Millionen von Pfadprüfungen | **Direkter nativer Index-Zugriff ohne JVM-Stackwechsel** |
33+
34+
---
35+
36+
## 🛠️ Architektur-Plan: FastCore Modernisierung
37+
38+
### Phase 1: Validierung in FastAIModel (Aktueller Stand)
39+
- [x] Proof-of-Concept des FFM-Backends in `fastaimodel-streaming` (`NativeGemvBackend`).
40+
- [x] Native AVX2/FMA Kernels (`fastai_streaming_kernels.dll`).
41+
- [x] Benchmarking gegen reine Java- und Ollama-Inferenz.
42+
43+
### Phase 2: FastCore Modularisierung (Java 17 vs. 21)
44+
Da `FastCore` aktuell auf Java 17 zielt, FFM aber ab Java 21 LTS stabil ist:
45+
- **Option A (Multi-Release JAR / Submodul `fastcore-ffm`)**:
46+
- Basis `FastCore` bleibt kompatibel mit Java 17 (JNI-Fallback).
47+
- `fastcore-ffm` wird aktiv, wenn JVM $\ge$ 21 läuft.
48+
- **Option B (FastCore Upgrade auf Java 21 LTS)**:
49+
- Hebt FastCore direkt auf Java 21 LTS an (empfohlen für maximale Einfachheit und Performance).
50+
51+
### Phase 3: Universelle FastCore FFM-API
52+
Bereitstellung von Standard-Helfern in `FastCore`:
53+
```java
54+
// Universeller nativer Funktionsaufruf ohne JNI
55+
MethodHandle fn = FastCore.lookup("fastkernel.dll", "vector_dot", FunctionDescriptor.of(...));
56+
57+
// Direkte Konvertierung von FastPointer zu MemorySegment
58+
MemorySegment seg = FastCore.asSegment(fastPointer, sizeBytes);
59+
```
60+
61+
---
62+
63+
*Erstellt: 2026-09-13 — FastJava Core Architecture Team*

‎README.md‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414

1515
By eliminating legacy JNI marshaling overhead, FastCore allows Java applications to execute raw C/C++ SIMD kernels, GPU compute pipelines, and system routines at bare-metal speeds (~2–5 ns transition overhead) with zero heap allocations.
1616

17-
[**Watch Showcase (YouTube)**](https://www.youtube.com/watch?v=BZsqQl7WqWk) | Watch JMH Benchmark (YouTube)
17+
[**Watch Demo (YouTube)**](https://www.youtube.com/watch?v=BZsqQl7WqWk) | Watch JMH Benchmark (YouTube)
1818

1919
[![Showcase](docs/screenshot.png)](https://www.youtube.com/watch?v=BZsqQl7WqWk)
2020

@@ -115,10 +115,10 @@ FastCore is rigorously benchmarked using **OpenJDK JMH** to guarantee zero-overh
115115

116116
```text
117117
Benchmark Mode Cnt Score Units
118-
JMH_FastCore.benchmarkPlatformDetection thrpt 3 428,190,412.1 ops/s
119-
JMH_FastCore.benchmarkLibraryFileNameGeneration thrpt 3 89,450,210.4 ops/s
120-
JMH_FastCore.benchmarkFfmMemorySegmentConversion thrpt 3 312,840,119.8 ops/s
121-
JMH_FastCore.benchmarkFfmLinkerQuery thrpt 3 541,209,881.0 ops/s
118+
Benchmark.benchmarkPlatformDetection thrpt 3 428,190,412.1 ops/s
119+
Benchmark.benchmarkLibraryFileNameGeneration thrpt 3 89,450,210.4 ops/s
120+
Benchmark.benchmarkFfmMemorySegmentConversion thrpt 3 312,840,119.8 ops/s
121+
Benchmark.benchmarkFfmLinkerQuery thrpt 3 541,209,881.0 ops/s
122122
```
123123

124124
### JNI vs. FFM Comparison
@@ -206,10 +206,9 @@ dependencies {
206206

207207
### Option 3: Direct Download (No Build Tool)
208208

209-
Download pre-compiled release JARs directly from [GitHub Releases](https://github.com/andrestubbe/FastCore/releases/tag/0.1.1):
209+
Download the release JAR directly from [GitHub Releases](https://github.com/andrestubbe/FastCore/releases/tag/0.1.1):
210210

211211
* ⚙️ **[FastCore-0.1.1.jar](https://github.com/andrestubbe/FastCore/releases/download/0.1.1/FastCore-0.1.1.jar)** (Core Library with FFM & JNI Engine)
212-
* 📦 **[FastCore-0.1.1-sources.jar](https://github.com/andrestubbe/FastCore/releases/download/0.1.1/FastCore-0.1.1-sources.jar)** (Full Java Source Archive)
213212

214213
---
215214

@@ -218,7 +217,7 @@ Download pre-compiled release JARs directly from [GitHub Releases](https://githu
218217
| Benchmark / Demo Case | Description | Java Source | Launcher |
219218
| :--- | :--- | :--- | :--- |
220219
| **Platform & FFM Linker Showcase** | Validates OS architecture detection, library filename resolution, and FFM Linker readiness. | [Demo.java](examples/Demo/src/main/java/fastcore/Demo.java) | `run-demo.bat` |
221-
| **Official JMH Benchmark** | Measures throughput for platform detection, filename synthesis, and memory segment conversion. | [JMH_FastCore.java](examples/Benchmark/src/main/java/fastcore/benchmark/JMH_FastCore.java) | `run-benchmark.bat` |
220+
| **Official JMH Benchmark** | Measures throughput for platform detection, filename synthesis, and memory segment conversion. | [Benchmark.java](examples/Benchmark/src/main/java/fastcore/benchmark/Benchmark.java) | `run-benchmark.bat` |
222221

223222
---
224223

@@ -237,9 +236,9 @@ Download pre-compiled release JARs directly from [GitHub Releases](https://githu
237236
| Platform | JNI Loader | FFM Native Linker |
238237
| :--- | :--- | :--- |
239238
| **Windows 10/11 (x64)** | ✅ Supported | ✅ Fully Supported (MSVC ABI) |
240-
| **Windows 11 (ARM64)** | 🔗 Supported | 🔗 Supported |
241-
| **Linux (x86_64)** | 🔗 Ready | 🔗 Ready (glibc / System V AMD64) |
242-
| **macOS (Apple Silicon M1-M4)** | 🔗 Ready | 🔗 Ready (Darwin ARM64) |
239+
| **Windows 11 (ARM64)** | 🚧 Planned | 🚧 Planned |
240+
| **Linux (x86_64)** | 🚧 Planned | 🚧 Planned |
241+
| **macOS (Apple Silicon M1-M4)** | 🚧 Planned | 🚧 Planned |
243242

244243
---
245244

‎docs/REFERENCE.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -65,9 +65,9 @@ When `loadLibrary` or `resolveLibraryPath` is called, FastCore probes in strict
6565
| OS / Architecture | Status | JNI Loading | FFM Downcalls |
6666
| :--- | :--- | :--- | :--- |
6767
| **Windows 10/11 (x64)** | ✅ Supported | Full | Full (MSVC ABI) |
68-
| **Windows 11 (ARM64)** | 🔗 Ready | Full | Full (ARM64 ABI) |
69-
| **Linux (x86_64 / glibc)** | 🔗 Ready | Full | Full (System V AMD64) |
70-
| **macOS (Apple Silicon / M1-M4)** | 🔗 Ready | Full | Full (Darwin ARM64) |
68+
| **Windows 11 (ARM64)** | 🚧 Planned | In Development | In Development |
69+
| **Linux (x86_64 / glibc)** | 🚧 Planned | In Development | In Development (System V AMD64) |
70+
| **macOS (Apple Silicon / M1-M4)** | 🚧 Planned | In Development | In Development (Darwin ARM64) |
7171

7272
---
7373

examples/Benchmark/src/main/java/fastcore/benchmark/JMH_FastCore.java renamed to examples/Benchmark/src/main/java/fastcore/benchmark/Benchmark.java

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
@Warmup(iterations = 2, time = 1, timeUnit = TimeUnit.SECONDS)
1414
@Measurement(iterations = 3, time = 1, timeUnit = TimeUnit.SECONDS)
1515
@Fork(1)
16-
public class JMH_FastCore {
16+
public class Benchmark {
1717

1818
private long sampleNativeAddress;
1919

0 commit comments

Comments
 (0)