Merge branch 'master' into dependabot/maven/org.sonatype.central-central-publishing-maven-plugin-0.11.0

Author: namanONcode

.github/workflows/benchmark.yml

@@ -94,7 +94,7 @@ jobs:
           python scripts/generate-graph.py zthread-benchmark/target/benchmark.json
 
       - name: Commit Updated Data
-        uses: stefanzweifel/git-auto-commit-action@v5
+        uses: stefanzweifel/git-auto-commit-action@v7
         with:
           commit_message: "docs(benchmark): auto-update performance charts and README"
           file_pattern: "README.md assets/benchmark_graph.svg zthread-benchmark/charts/* zthread-benchmark/benchmark.md"

.gitignore

@@ -41,4 +41,7 @@ Thumbs.db
 
 # Logs & Temporary files
 logs/
-*.tmp
+*.tmp
+
+# Agent / Tools
+.agents/

wiki/API.md

@@ -0,0 +1,46 @@
+# API Reference
+
+Because zThread is an event loop library, its API consists of Java interfaces rather than REST endpoints. This page outlines the core public interfaces developers use to interact with the runtime.
+
+## ZRuntime
+
+`ZRuntime` is the primary interface for starting the loop, posting events, and registering handlers.
+
+### `void start()`
+* **Purpose:** Starts the background event loop thread.
+* **Side effects:** Spawns a new thread that will block in native code (`epoll_wait`) until events occur.
+
+### `void shutdown()`
+* **Purpose:** Signals the event loop to stop processing and exit gracefully.
+
+### `<T> void on(Class<T> eventType, Consumer<T> handler)`
+* **Purpose:** Registers a callback handler for a specific event class.
+* **Parameters:**
+  * `eventType`: The class type of the event.
+  * `handler`: The consumer function to execute when the event is processed by the loop.
+
+### `boolean post(Object event)`
+* **Purpose:** Inserts an event into the MPSC ring buffer and wakes up the event loop if it is sleeping.
+* **Parameters:** 
+  * `event`: The object to pass to the registered handler.
+* **Return value:** `true` if the event was successfully queued, `false` if the buffer is full (or throws an exception depending on backpressure configuration).
+
+### `boolean tryPost(Object event)`
+* **Purpose:** A non-blocking variant of `post` that returns `false` immediately if the ring buffer is at capacity, allowing the caller to handle backpressure without exceptions.
+
+## ZRuntimeBuilder
+
+A fluent builder accessed via `ZRuntime.builder()`.
+
+* `threadName(String name)`: Sets the name of the background thread.
+* `bufferSize(int size)`: Sets the capacity of the MPSC ring buffer (must be a power of two).
+* `maxEventsPerPoll(int max)`: Configures how many events `epoll_wait` can retrieve in a single wakeup.
+* `metricsEnabled(boolean enabled)`: Toggles internal JMX/micrometer metrics.
+* `build()`: Uses `ServiceLoader` to locate the `zthread-linux` implementation and returns a configured `ZRuntime`.
+
+## ZEventFlux (zthread-reactor)
+
+Provides integration with Project Reactor.
+
+### `static <T> Flux<T> fromRuntime(ZRuntime runtime, Class<T> eventType)`
+* **Purpose:** Creates a reactive `Flux` that emits items whenever the underlying `ZRuntime` processes an event of `eventType`.

wiki/Architecture.md

@@ -0,0 +1,64 @@
+# Architecture
+
+zThread uses a layered architecture to isolate the public Java API from the underlying native Linux mechanisms. The framework relies on the Java Foreign Function & Memory (FFM) API to avoid JNI overhead.
+
+## High-level architecture
+
+The system consists of two primary boundaries:
+1. **User Space (Java):** Where the developer registers handlers, posts events, and configures the runtime.
+2. **Kernel Space (Linux):** Where the event loop thread sleeps (`epoll_wait`) until an event occurs on a file descriptor.
+
+```mermaid
+graph TD
+    subgraph Java Application
+        A[Producer Thread 1] -->|post| Q(MPSC Ring Buffer)
+        B[Producer Thread 2] -->|post| Q
+        H[Event Handlers]
+    end
+
+    subgraph zThread Runtime
+        Q -->|eventfd signal| EL(Event Loop Thread)
+        EL -->|dispatch| H
+        NP(Native Poller) -->|epoll_wait| EL
+    end
+
+    subgraph Linux Kernel
+        EP[epoll instance]
+        EF[eventfd]
+        TF[timerfd]
+        IF[inotify]
+        EF --> EP
+        TF --> EP
+        IF --> EP
+        EP -->|wake| NP
+    end
+```
+
+## Layered architecture
+
+### 1. The Core API (`zthread-core`)
+Provides interface definitions that application developers interact with. It contains no OS-specific logic.
+* `ZRuntime`: The main interface for starting the loop and posting events.
+* `ZRuntimeBuilder`: Fluent builder for configuration.
+* `ZRuntimeFactory`: SPI interface used by the builder to discover the native implementation at runtime.
+
+### 2. The Linux Implementation (`zthread-linux`)
+Implements the core interfaces using native calls.
+* `LinuxRuntime`: The concrete implementation of `ZRuntime`.
+* `LinuxEventLoop`: A dedicated thread that continuously polls for events and drains the MPSC ring buffer.
+* `LinuxNativePoller`: The FFM bridge that links to `libc.so` (or `libc.so.6`). It handles memory segments for `epoll_event` structs and invokes `epoll_create1`, `epoll_ctl`, and `epoll_wait`.
+
+## Request flow
+
+When a producer thread calls `runtime.post(event)`:
+
+1. **Insertion:** The event is written into a lock-free Multi-Producer Single-Consumer (MPSC) Ring Buffer.
+2. **Wakeup Signal:** If the event loop thread is currently parked in the kernel (`epoll_wait`), the producer writes an 8-byte integer to an `eventfd`. 
+3. **Kernel Wakeup:** The kernel detects activity on the `eventfd`, wakes the event loop thread, and returns control to `LinuxNativePoller`.
+4. **Drain & Dispatch:** The event loop reads the `eventfd` to clear the signal, then drains the entire MPSC ring buffer, passing each event to its registered handler sequentially.
+
+## Component responsibilities
+
+* **MPSC Ring Buffer:** Handles high-throughput, thread-safe queuing of events from multiple producer threads without locking.
+* **Native Poller:** Manages native off-heap memory allocation for Linux structures and executes exact syscalls via FFM.
+* **Event Dispatcher:** Maintains a map of event types to `Consumer<T>` handlers and executes them when the loop drains the buffer.

wiki/Authentication.md

@@ -0,0 +1,7 @@
+# Authentication
+
+*Note: This document is included for structural completeness.*
+
+zThread is a low-level event dispatch and concurrency library. It does not handle user sessions, login flows, OAuth, JWTs, or role-based access control.
+
+Any authentication or authorization middleware must be implemented at the application layer above the zThread runtime.

wiki/Configuration.md

@@ -0,0 +1,28 @@
+# Configuration
+
+Configuration for a zThread instance is handled via the `ZRuntimeBuilder` and stored immutably in `ZRuntimeConfig`. There are no external environment variables or properties files required by the library itself.
+
+## ZRuntimeConfig Options
+
+| Option | Required | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `threadName` | No | `zthread-event-loop` | The name given to the background event loop thread. |
+| `bufferSize` | No | `4096` | The capacity of the MPSC ring buffer. Must be positive; the builder automatically rounds this to a minimum of `64`. |
+| `maxEventsPerPoll` | No | `64` | The maximum number of events retrieved from the kernel per `epoll_wait` call. |
+| `metricsEnabled` | No | `true` | Whether internal performance metrics collection is enabled. |
+| `debugEnabled` | No | `false` | Whether debug-level internal logging is printed. |
+
+### Usage Example
+
+```java
+ZRuntime runtime = ZRuntime.builder()
+    .threadName("my-app-worker")
+    .bufferSize(8192)
+    .maxEventsPerPoll(128)
+    .metricsEnabled(false)
+    .build();
+```
+
+### Security Notes
+
+The configuration options do not manage secrets or sensitive data. However, setting `bufferSize` excessively high in an environment with many concurrent event loops could lead to `OutOfMemoryError` conditions, as the buffer is allocated upfront.

wiki/Contributing.md

@@ -0,0 +1,29 @@
+# Contributing
+
+We welcome contributions to zThread! This guide covers how to submit code, report bugs, and align with our development standards.
+
+## Reporting Bugs
+
+Please use the GitHub Issue tracker to report bugs. Include:
+* Your OS version and kernel.
+* Your JDK version.
+* A clear, reproducible code example if possible.
+
+## Pull Request Process
+
+1. **Fork and Branch:** Create a fork of the repository and create a feature branch (`feature/your-feature` or `fix/issue-description`).
+2. **Write Tests:** Ensure your new feature is covered by unit tests. If you modified native interactions, add an integration test.
+3. **Format Code:** Run `./mvnw spotless:apply` to ensure your code matches the Google Java Format and includes the Apache 2.0 license header.
+4. **Pass Checks:** Run `./mvnw clean verify -Pquality` to verify that Checkstyle, PMD, and SpotBugs pass.
+5. **Submit PR:** Open a Pull Request against the `main` branch. 
+
+## Commit Conventions
+
+While not strictly enforced via tooling, we appreciate clean, descriptive commit messages.
+
+* Use the imperative mood: "Fix bug in ring buffer" rather than "Fixed bug".
+* If your commit resolves an issue, include `Fixes #123` in the description.
+
+## Development Environment Setup
+
+See [Development Workflow](Development) for details on the required JDK, Maven commands, and debugging tools.

wiki/Database.md

@@ -0,0 +1,9 @@
+# Database
+
+*Note: This document is included for structural completeness.*
+
+zThread is an in-memory, native event loop library. It does not interact with databases, contain a schema, or manage persistent entities. 
+
+If you are using zThread to build a database driver or an application that connects to a database, you must manage your own connection pools (e.g., HikariCP) and ensure that blocking database I/O operations are offloaded to a separate thread pool. 
+
+Because the zThread event loop (`ZRuntime`) runs on a single thread, performing synchronous database calls inside a zThread event handler will stall the entire event loop and prevent other events from being processed.

wiki/Deployment.md

@@ -0,0 +1,30 @@
+# Deployment
+
+*Note: As zThread is a library, "deployment" refers to publishing artifacts to Maven Central, not deploying a service to a cloud provider like Kubernetes.*
+
+## Release Process
+
+Artifacts are published to the Sonatype OSSRH (Open Source Software Repository Hosting) and synced to Maven Central.
+
+The project uses the Maven Release Profile and the Sonatype Central Publishing Plugin to automate this process.
+
+### Build and Deploy Command
+
+To release a new version to Maven Central, project maintainers run:
+
+```bash
+./mvnw clean deploy -Prelease --batch-mode --no-transfer-progress
+```
+
+### The `release` Profile
+
+The `-Prelease` flag activates the `release` Maven profile defined in the root `pom.xml`. This profile attaches the following plugins to the build lifecycle:
+
+1. **`maven-source-plugin`:** Generates `-sources.jar`.
+2. **`maven-javadoc-plugin`:** Generates `-javadoc.jar`.
+3. **`maven-gpg-plugin`:** Cryptographically signs all artifacts (JARs, POMs) with the maintainer's GPG key.
+4. **`central-publishing-maven-plugin`:** Uploads the signed artifacts and automates the release process on Sonatype.
+
+### CI/CD
+
+Release processes are handled manually or via the `Release` GitHub Action (`.github/workflows/release.yml`), which requires the `MAVEN_USERNAME`, `MAVEN_PASSWORD`, and GPG secret keys to be configured as repository secrets.

wiki/Development.md

@@ -0,0 +1,54 @@
+# Development Workflow
+
+This page outlines the local development setup, coding standards, and common tasks for contributors working on the zThread codebase.
+
+## Prerequisites
+* **OS:** A Linux environment (natively or via WSL2) is required because the library depends on kernel-specific features (`epoll`, `eventfd`).
+* **Java:** JDK 25.
+* **Maven:** Included via the Maven Wrapper (`./mvnw`).
+
+## Coding Standards
+
+The project enforces strict code quality and formatting rules. Before submitting a pull request, ensure your code passes the quality profile.
+
+### Linting and Formatting
+
+Run the quality check profile:
+```bash
+./mvnw clean verify -Pquality
+```
+
+This runs the following plugins:
+1. **Spotless:** Enforces Google Java Format and prepends the Apache 2.0 license header.
+2. **Checkstyle:** Validates naming conventions, import ordering, and Javadoc presence.
+3. **PMD:** Scans for potential bugs, dead code, and suboptimal performance patterns.
+4. **SpotBugs:** Analyzes bytecode for common bug patterns.
+
+If Spotless fails due to formatting, you can automatically fix it with:
+```bash
+./mvnw spotless:apply
+```
+
+## Local Workflow
+
+1. **Build and test:**
+   ```bash
+   ./mvnw clean verify --enable-native-access=ALL-UNNAMED
+   ```
+
+2. **Run benchmarks:**
+   ```bash
+   cd zthread-benchmark
+   ../mvnw clean package
+   java --enable-native-access=ALL-UNNAMED -jar target/benchmarks.jar
+   ```
+
+## Debugging
+
+Because zThread utilizes the FFM API, segmentation faults can occur if off-heap memory is mismanaged or accessed after it has been freed. 
+
+To debug native memory issues, you can run the JVM with:
+```bash
+java -XX:NativeMemoryTracking=detail --enable-native-access=ALL-UNNAMED ...
+```
+For deep native stack traces, attach `gdb` to the Java process.