🚀 JPyRust: High-Performance Universal AI Bridge

"The Ultimate Python AI Integration for Java: Reducing 7s latency to 0.04s."

🇰🇷 한국어 버전 (Korean Version)

---

💡 Introduction

JPyRust is a hybrid architecture designed to bridge the gap between Java's robustness and Python's AI ecosystem. It enables Spring Boot applications to execute heavy AI models (YOLO, PyTorch, TensorFlow) with near-native performance.

Unlike slow ProcessBuilder or high-latency HTTP APIs, JPyRust leverages Rust JNI and Shared Memory (SHMEM) to achieve sub-millisecond communication.

🌟 Why JPyRust?

• 🚀 Zero-Latency: Uses System RAM (Shared Memory) instead of HTTP/Sockets.
• 🔄 True Parallelism: v1.3.0 supports Multi-Instance architecture (1 Java App connects to N Python Processes).
• 🛠️ Zero-Config: Auto-installs a secluded Embedded Python environment. No pip install hell.
• 🛡️ Crash-Proof: Rust monitors Python health and auto-restarts workers if they crash.

---

🏗️ Architecture (v1.3.0)

With the v1.3.0 update, JPyRust has moved from a generic Singleton pattern to a Multi-Instance Object-Oriented Architecture. This allows a single Java application to control multiple independent AI workers (e.g., Multi-Channel CCTV processing).

🧩 System Component Diagram

graph TD
    subgraph JavaApp [☕ Java Application Layer]
        style JavaApp fill:#f9f2f4,stroke:#333,stroke-width:2px
        J1["Camera 1 Bridge<br>(Instance ID: cam1)"]
        J2["Camera 2 Bridge<br>(Instance ID: cam2)"]
    end

    subgraph NativeLayer [🦀 Rust JNI Layer]
        style NativeLayer fill:#e8f4f8,stroke:#333,stroke-width:2px
        R1["BridgeState A<br>{Ptr: 0x7FA...}"]
        R2["BridgeState B<br>{Ptr: 0x81B...}"]
    end

    subgraph PythonLayer [🐍 Embedded Python Layer]
        style PythonLayer fill:#edfbec,stroke:#333,stroke-width:2px
        P1["Python Worker A<br>(PID: 1001)"]
        P2["Python Worker B<br>(PID: 1002)"]
    end

    J1 -- "JNI Call (nativePtr)" --> R1
    J2 -- "JNI Call (nativePtr)" --> R2
    
    R1 <== "⚡ SHMEM (Images)" ==> P1
    R2 <== "⚡ SHMEM (Images)" ==> P2
    
    P1 -- "JSON Result" --> R1
    P2 -- "JSON Result" --> R2

Loading

⚡ Execution Sequence

sequenceDiagram
    participant Java as ☕ Java (Spring)
    participant Rust as 🦀 Rust (JNI)
    participant Py as 🐍 Python (Worker)

    Note over Java, Py: Initialization Phase
    Java->>Rust: new JPyRustBridge("cam1").initialize()
    Rust->>Rust: Allocate BridgeState (Heap)
    Rust->>Py: Spawn Process (arg: --instance-id cam1)
    Py->>Py: Setup ~/.jpyrust/cam1/
    Py-->>Rust: Signal "READY"
    Rust-->>Java: Return nativePtr (Handle)

    Note over Java, Py: Inference Phase (Loop)
    Java->>Rust: processImage(ptr, image_bytes)
    Rust->>Rust: Write to Shared Memory
    Rust->>Py: Send Signal (IPC)
    Py->>Py: Read SHMEM -> YOLO Inference
    Py-->>Rust: Return JSON Result
    Rust-->>Java: Return Result String

Loading

---

⚡ Performance Benchmark

Architecture	Communication	Latency (Avg)	Throughput	Stability
CLI (ProcessBuilder)	Stdin/Stdout	~1,500ms	🔴 Low	🔴 Low (JVM Blocking)
HTTP (FastAPI/Flask)	REST API	~100ms	🟡 Medium	🟢 High
JPyRust v1.3.0	Shared Memory	🟢 ~40ms	🟢 High (Parallel)	🟢 High (Isolated)

Benchmark Env: Ryzen 5 5600X, 32GB RAM, NVIDIA RTX 3060, YOLOv8n Model

---

🚀 Quick Start

1. Installation (Gradle)

Add the JitPack repository and dependency to your build.gradle.kts:

repositories {
    maven { url = uri("[https://jitpack.io](https://jitpack.io)") }
}

dependencies {
    // Latest stable version
    implementation("com.github.farmer0010:JPyRust:v1.3.0")
}

2. Usage (Java)

Important: As of v1.3.0, static methods are removed. You must instantiate JPyRustBridge.

import com.jpyrust.JPyRustBridge;

public class VisionService {
    
    public void startDetection() {
        // 1. Create independent instances for each camera
        JPyRustBridge cam1 = new JPyRustBridge("cam1");
        JPyRustBridge cam2 = new JPyRustBridge("cam2");

        // 2. Initialize (Spawns workers in ~/.jpyrust/camX)
        cam1.initialize(); 
        cam2.initialize(); 

        // 3. Process Images (Thread-Safe)
        // arg: (imageData, length, width, height, channels)
        byte[] result1 = cam1.processImage(imgData1, len1, 640, 480, 3);
        byte[] result2 = cam2.processImage(imgData2, len2, 640, 480, 3);
        
        System.out.println("Cam1 Result: " + new String(result1));
    }
}

---

🛠️ Configuration & Troubleshooting

🔧 1. UnsatisfiedLinkError / DLL Not Found

• Cause: Java cannot find the native library.
• Fix: The library is automatically extracted to AppData/Local/Temp. If it fails, ensure jpyrust.dll (Windows) or libjpyrust.so (Linux) is in your library path.

🛡️ 2. WinError 5 (Access Denied)

• Cause: Windows Security permissions on Shared Memory.
• Fix: JPyRust v1.2+ uses explicit SECURITY_ATTRIBUTES with SDDL D:(A;;GA;;;WD) to allow Full Access to the Python child process. No manual action required.

🐍 3. Python Dependency Issues

• JPyRust includes a portable embedded Python. It bootstraps itself in ~/.jpyrust/python_dist.
• If libraries are missing, check requirements.txt in the resource folder.

---

📜 Version History

• v1.3.0 (Latest) 🚀

  • Major Refactor: Switched to Multi-Instance Architecture.
  • Breaking Change: Removed static methods; added Constructor-based instantiation.
  • Feature: Isolated working directories per instance (~/.jpyrust/cam1).

• v1.2.0

  • Performance: Restored Shared Memory (SHMEM) on Windows via Win32 API.
  • Security: Fixed WinError 5 using custom Security Descriptors.

• v1.1.0

  • Initial Windows Support & File-based IPC fallback.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

_{Built with 🦀 Rust & ☕ Java by Farmer0010 (JPyRust Team).}