Skip to content

Commit a67388f

Browse files
andrestubbeandrestubbe
committed
docs: upgrade README to 0.1.1 — add Quick Start, API table, benchmark table, demo table, related projects, platform support
1 parent 7193776 commit a67388f

1 file changed

Lines changed: 208 additions & 97 deletions

File tree

‎README.md‎

Lines changed: 208 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,208 @@
1-
# FastHardware 0.1.0 [ALPHA-2026-06-07] — Native Hardware Telemetry API for Java
2-
3-
[![Status](https://img.shields.io/badge/status-0.1.0-brightgreen.svg)](https://github.com/andrestubbe/FastHardware/releases/tag/0.1.0)
4-
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5-
[![Java](https://img.shields.io/badge/Java-17+-blue.svg)](https://www.java.com)
6-
[![Platform](https://img.shields.io/badge/Platform-Windows%2010+-lightgrey.svg)]()
7-
[![JitPack](https://img.shields.io/badge/JitPack-ready-green.svg)](https://jitpack.io/#andrestubbe/FastHardware)
8-
9-
**⚡ A zero-overhead native module for the FastJava ecosystem. Monitor CPU, GPU, RAM, and Disk health directly via native Windows APIs.**
10-
11-
**FastHardware** provides direct access to system performance counters and hardware sensors. By using native Win32/WMI hooks, it delivers accurate telemetry without the performance hit of traditional Java system-querying methods.
12-
13-
[![FastHardware Showcase](docs/screenshot.png)](https://www.youtube.com/watch?v=BZsqQl7WqWk)
14-
15-
16-
---
17-
18-
## Table of Contents
19-
- [Features](#features)
20-
- [Installation](#installation)
21-
- [License](#license)
22-
23-
---
24-
25-
## Features
26-
- **📊 Real-Time Stats**: Monitor CPU usage, GPU temperature, and RAM availability.
27-
- **⚡ Ultra-Fast Queries**: Low-latency hardware status updates.
28-
- **📦 Zero Overhead**: Efficient native implementation bypassing heavy abstractions.
29-
- **🚀 High Accuracy**: Real OS-level data for performance monitoring tools.
30-
31-
---
32-
33-
## Installation
34-
35-
### Option 1: Maven (Recommended)
36-
Add the JitPack repository and the dependencies to your `pom.xml`:
37-
38-
```xml
39-
<repositories>
40-
<repository>
41-
<id>jitpack.io</id>
42-
<url>https://jitpack.io</url>
43-
</repository>
44-
</repositories>
45-
46-
<dependencies>
47-
<!-- FastHardware Library -->
48-
<dependency>
49-
<groupId>com.github.andrestubbe</groupId>
50-
<artifactId>FastHardware</artifactId>
51-
<version>0.1.0</version>
52-
</dependency>
53-
54-
<!-- FastCore (Required Native Loader) -->
55-
<dependency>
56-
<groupId>com.github.andrestubbe</groupId>
57-
<artifactId>FastCore</artifactId>
58-
<version>0.1.0</version>
59-
</dependency>
60-
</dependencies>
61-
```
62-
63-
### Option 2: Gradle (via JitPack)
64-
```groovy
65-
repositories {
66-
maven { url 'https://jitpack.io' }
67-
}
68-
69-
dependencies {
70-
implementation 'com.github.andrestubbe:FastHardware:0.1.0'
71-
implementation 'com.github.andrestubbe:FastCore:0.1.0'
72-
}
73-
```
74-
75-
### Option 3: Direct Download (No Build Tool)
76-
Download the latest JARs directly to add them to your classpath:
77-
78-
1. 📦 **[FastHardware-0.1.0.jar](https://github.com/andrestubbe/FastHardware/releases/download/0.1.0/FastHardware-0.1.0.jar)** (The Core Library)
79-
2. ⚙️ **[FastCore-0.1.0.jar](https://github.com/andrestubbe/FastCore/releases/download/0.1.0/FastCore-0.1.0.jar)** (The Mandatory Native Loader)
80-
81-
> [!IMPORTANT]
82-
> All JARs must be in your classpath for the native JNI calls to function correctly.
83-
84-
---
85-
86-
## Documentation
87-
* **[ARCHITECTURE.md](docs/ARCHITECTURE.md)**: Details on PDH and WMI implementation.
88-
* **[REFERENCE.md](docs/REFERENCE.md)**: Full API and JNI contracts.
89-
* **[ROADMAP.md](docs/ROADMAP.md)**: Future development and milestones.
90-
91-
---
92-
93-
## License
94-
MIT License — See [LICENSE](LICENSE) for details.
95-
96-
---
97-
**Part of the FastJava Ecosystem** — *Making the JVM faster.*
1+
# FastHardware 0.1.1 — Native Hardware Telemetry API for Java
2+
3+
[![Status](https://img.shields.io/badge/status-0.1.1-brightgreen.svg)](https://github.com/andrestubbe/FastHardware/releases/tag/0.1.1)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5+
[![Java](https://img.shields.io/badge/Java-17+-blue.svg)](https://www.java.com)
6+
[![Platform](https://img.shields.io/badge/Platform-Windows%2010+-lightgrey.svg)]()
7+
[![JitPack](https://img.shields.io/badge/JitPack-ready-green.svg)](https://jitpack.io/#andrestubbe/FastHardware)
8+
9+
**⚡ Zero-overhead native hardware telemetry for Java. Monitor CPU usage, CPU temperature, RAM, and GPU temperature directly via Win32 PDH and WMI — no JMX, no process spawning, no bloat.**
10+
11+
**FastHardware** bypasses the JVM's heavy `OperatingSystemMXBean` and shell-based `wmic` calls entirely. By binding directly to Win32 PDH counters and WMI COM objects via JNI, it delivers accurate, low-latency hardware telemetry at native speed.
12+
13+
[![FastHardware Showcase](docs/screenshot.png)](https://www.youtube.com/watch?v=BZsqQl7WqWk)
14+
15+
---
16+
17+
## Table of Contents
18+
- [Features](#features)
19+
- [Quick Start](#quick-start)
20+
- [API Quick Reference](#api-quick-reference)
21+
- [Performance Benchmarks](#performance-benchmarks)
22+
- [Examples & Demos](#examples--demos)
23+
- [Installation](#installation)
24+
- [Documentation](#documentation)
25+
- [Platform Support](#platform-support)
26+
- [Related Projects](#related-projects)
27+
- [License](#license)
28+
29+
---
30+
31+
## Features
32+
33+
- **📊 Real-Time Telemetry** — CPU usage %, per-core CPU usage, CPU temperature, physical RAM, GPU temperature.
34+
- **⚡ Native Win32 Speed** — PDH counters (`\\Processor(_Total)\\% Processor Time`) registered once, polled in microseconds. RAM via `GlobalMemoryStatusEx` (direct kernel table read). Temperature via WMI `MSAcpi_ThermalZoneTemperature` in `ROOT\WMI`.
35+
- **🧊 Zero Overhead** — All JNI calls use primitives (`jlong`, `jdouble`, `jdoubleArray`). No heap allocation per query.
36+
- **📦 Atomic Snapshot** — `getSnapshot()` returns a frozen `HardwareSnapshot` record with all fields captured in a single native round-trip.
37+
- **🔌 FastCore Auto-Load** — `fasthardware.dll` is embedded in the JAR. `FastCore` extracts and loads it at runtime — no manual DLL management.
38+
39+
---
40+
41+
## Quick Start
42+
43+
```java
44+
// 1. Create a hardware monitor instance (initializes PDH + WMI once)
45+
FastHardware hw = FastHardware.create();
46+
47+
// First PDH sample needs ~1s interval to compute CPU rate
48+
Thread.sleep(1100);
49+
50+
// 2. Get an atomic snapshot of all telemetry
51+
HardwareSnapshot snap = hw.getSnapshot();
52+
53+
System.out.printf("CPU: %.1f%%%n", snap.cpuUsagePercent());
54+
System.out.printf("CPU Temp: %.1f°C%n", snap.cpuTemperatureCelsius());
55+
System.out.printf("RAM: %d MB free / %d MB total%n",
56+
snap.freeRamBytes() / 1024 / 1024,
57+
snap.totalRamBytes() / 1024 / 1024);
58+
System.out.printf("GPU Temp: %.1f°C%n", snap.gpuTemperatureCelsius());
59+
```
60+
61+
> [!IMPORTANT]
62+
> PDH CPU counters require **two collection intervals** to compute a rate. Call `hw.getSnapshot()` once, wait ~1 second, then read real values. FastHardware handles this automatically after the first poll.
63+
64+
---
65+
66+
## API Quick Reference
67+
68+
### `FastHardware` (Interface)
69+
70+
| Method | Returns | Description |
71+
|--------|---------|-------------|
72+
| `FastHardware.create()` | `FastHardware` | Initializes the native library and returns a monitor instance. |
73+
| `getSnapshot()` | `HardwareSnapshot` | Atomic read of all telemetry fields in one native call. |
74+
| `getGlobalCpuUsage()` | `double` | CPU usage 0.0–100.0 via PDH `\\Processor(_Total)\\% Processor Time`. |
75+
| `getPerCoreCpuUsage()` | `double[]` | Per-logical-core CPU usage array via PDH. |
76+
| `getTotalMemoryBytes()` | `long` | Total physical RAM via `GlobalMemoryStatusEx`. |
77+
| `getFreeMemoryBytes()` | `long` | Free physical RAM via `GlobalMemoryStatusEx`. |
78+
| `getCpuTemperatureCelsius()` | `double` | CPU package temperature via WMI `MSAcpi_ThermalZoneTemperature` in `ROOT\WMI`. |
79+
| `getGpuTemperatureCelsius()` | `double` | GPU temperature via WMI (discrete GPUs; `0.0` on Intel integrated). |
80+
81+
### `HardwareSnapshot` (Record)
82+
83+
```java
84+
record HardwareSnapshot(
85+
double cpuUsagePercent,
86+
double[] perCoreCpuUsage,
87+
long usedRamBytes,
88+
long totalRamBytes,
89+
double cpuTemperatureCelsius,
90+
double gpuTemperatureCelsius
91+
) {
92+
long freeRamBytes(); // helper: totalRamBytes - usedRamBytes
93+
}
94+
```
95+
96+
---
97+
98+
## Performance Benchmarks
99+
100+
FastHardware native Win32 JNI vs standard Java `OperatingSystemMXBean` / `Runtime`:
101+
102+
| Metric | Java JMX / Runtime | FastHardware Native | Advantage |
103+
|--------|--------------------|---------------------|-----------|
104+
| Full telemetry snapshot | 3× separate MXBean calls | **1× atomic JNI call** | **3× fewer round-trips** |
105+
| CPU usage query | `getSystemLoadAverage()` (1-min rolling) | **PDH instantaneous** | **Real-time vs delayed** |
106+
| Per-core CPU usage | ❌ No API | **`double[]` per logical core** | **FastHardware exclusive** |
107+
| Free RAM (OS-level) | `Runtime.freeMemory()` (JVM heap only) | **`GlobalMemoryStatusEx` (physical)** | **System-wide accuracy** |
108+
| CPU temperature | ❌ No API | **WMI `ROOT\WMI` ACPI sensor** | **FastHardware exclusive** |
109+
| GPU temperature | ❌ No API | **WMI discrete GPU sensor** | **FastHardware exclusive** |
110+
111+
*Run `run-benchmark.bat` for live JMH throughput numbers on your machine.*
112+
113+
---
114+
115+
## Examples & Demos
116+
117+
| Case | File | Launcher | Description |
118+
|------|------|----------|-------------|
119+
| **Live Terminal Dashboard** | [Demo.java](examples/Demo/src/main/java/fasthardware/Demo.java) | `run-demo.bat` | ANSI terminal monitor — CPU%, CPU°C, RAM, GPU°C as live bars + scrolling sparklines. Pure FastHardware, no extra deps. |
120+
| **JMH Benchmark Suite** | [Benchmark.java](examples/Benchmark/src/main/java/fasthardware/benchmark/Benchmark.java) | `run-benchmark.bat` | 7-group JMH throughput suite comparing FastHardware native vs Java JMX/Runtime. |
121+
122+
---
123+
124+
## Installation
125+
126+
### Option 1: Maven (Recommended)
127+
Add the JitPack repository and the dependencies to your `pom.xml`:
128+
129+
```xml
130+
<repositories>
131+
<repository>
132+
<id>jitpack.io</id>
133+
<url>https://jitpack.io</url>
134+
</repository>
135+
</repositories>
136+
137+
<dependencies>
138+
<!-- FastHardware Library -->
139+
<dependency>
140+
<groupId>com.github.andrestubbe</groupId>
141+
<artifactId>FastHardware</artifactId>
142+
<version>0.1.1</version>
143+
</dependency>
144+
145+
<!-- FastCore (Required Native Loader) -->
146+
<dependency>
147+
<groupId>com.github.andrestubbe</groupId>
148+
<artifactId>FastCore</artifactId>
149+
<version>0.1.0</version>
150+
</dependency>
151+
</dependencies>
152+
```
153+
154+
### Option 2: Gradle (via JitPack)
155+
```groovy
156+
repositories {
157+
maven { url 'https://jitpack.io' }
158+
}
159+
160+
dependencies {
161+
implementation 'com.github.andrestubbe:FastHardware:0.1.1'
162+
implementation 'com.github.andrestubbe:FastCore:0.1.0'
163+
}
164+
```
165+
166+
### Option 3: Direct Download (No Build Tool)
167+
1. 📦 **[FastHardware-0.1.1.jar](https://github.com/andrestubbe/FastHardware/releases/download/0.1.1/FastHardware-0.1.1.jar)** — The Core Library
168+
2. ⚙️ **[FastCore-0.1.0.jar](https://github.com/andrestubbe/FastCore/releases/download/0.1.0/fastcore-0.1.0.jar)** — The Mandatory Native Loader
169+
170+
> [!IMPORTANT]
171+
> Both JARs must be on your classpath. FastCore extracts `fasthardware.dll` to `%USERPROFILE%\.fastcore\native\` at runtime.
172+
173+
---
174+
175+
## Documentation
176+
177+
| File | Description |
178+
|------|-------------|
179+
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | Win32 PDH, WMI COM, and JNI boundary details. |
180+
| [REFERENCE.md](docs/REFERENCE.md) | Full API specification and JNI contracts. |
181+
| [COMPILE.md](docs/COMPILE.md) | Build guide for the native DLL from source. |
182+
| [PHILOSOPHY.md](docs/PHILOSOPHY.md) | Why native-first telemetry matters in Java. |
183+
| [CHANGELOG.md](docs/CHANGELOG.md) | Version history. |
184+
| [ROADMAP.md](docs/ROADMAP.md) | Future development milestones. |
185+
186+
---
187+
188+
## Platform Support
189+
190+
| Platform | Status |
191+
|----------|--------|
192+
| Windows 10 / 11 (x64) | ✅ Fully Supported |
193+
| Linux | 🔜 Planned |
194+
| macOS | 🔜 Planned |
195+
196+
---
197+
198+
## Related Projects
199+
200+
- [FastCore](https://github.com/andrestubbe/FastCore) — Native JNI DLL loader for the FastJava ecosystem
201+
- [FastDWM](https://github.com/andrestubbe/FastDWM) — Windows DWM bridge (VSync, title bar theming, WinMM timers)
202+
- [FastGPU](https://github.com/andrestubbe/FastGPU) — Vulkan compute kernel dispatch for Java
203+
- [FastDisplay](https://github.com/andrestubbe/FastDisplay) — Native display refresh rate and resolution detection
204+
- [FastExecution](https://github.com/andrestubbe/FastExecution) — Sub-millisecond precision named loop and delay scheduler
205+
206+
---
207+
208+
**Part of the FastJava Ecosystem** — *Making the JVM faster. Small package. Maximum speed. Zero bloat.* 🚀

0 commit comments

Comments
 (0)