JavaToGpu

JavaToGpu lets you write a restricted Java method, mark it as a GPU kernel, and run it through the OpenCL runtime.

It is currently a public alpha / developer preview. Use it for experiments, examples, compiler/runtime integration, and early GPU-kernel prototyping. Do not treat the API or generated launcher shape as stable before beta.

Current Status

• OpenCL is the active runtime path today.
• NVIDIA OpenCL and AMD OpenCL are the current validated hardware baselines.
• Intel OpenCL still needs real-hardware validation before broad cross-vendor claims.
• CUDA is a staged, explicit opt-in preview path and is not production execution yet.
• IR optimizer mutation is optional, fail-closed, and intended for review/testing before production use.

JavaToGpu is not a "run any Java app on the GPU" system. GPU methods must stay inside the supported kernel subset.

What You Can Do Today

• Write @GPU Java kernels over arrays, scalars, vectors, structs, pointers, images, and samplers.
• Use GPU.* builtins for OpenCL-style indexing, math, barriers, images, atomics, and low-level helpers.
• Run kernels through the public JavaToGpu runtime facade.
• Add fixture-based @GPUTest metadata for manual method probes and future placement evidence.
• Enable optional IR validation for stricter diagnostics and CI reports.
• Inspect backend/device explanations without learning backend SPI internals.

Install

Add JavaToGpu as both a dependency and an annotation processor:

repositories {
    mavenCentral()
}

dependencies {
    implementation 'io.github.deussixik:javatogpu:0.1.0-alpha.5'
    annotationProcessor 'io.github.deussixik:javatogpu:0.1.0-alpha.5'
}

JitPack is also configured for builds from Git tags or commits. Use a tag or commit that contains jitpack.yml:

repositories {
    maven { url = uri('https://jitpack.io') }
    mavenCentral()
}

dependencies {
    implementation 'com.github.Team-Argentum.JavaToGpu:javatogpu:<tag-or-commit>'
    annotationProcessor 'com.github.Team-Argentum.JavaToGpu:javatogpu:<tag-or-commit>'
}

To let JavaToGpu replace direct calls to @GPU methods with generated runtime launchers, add the bytecode rewrite task to the same build.gradle:

tasks.register('rewriteGpuMethods', JavaExec) {
    dependsOn tasks.named('compileJava')
    dependsOn tasks.named('processResources')
    classpath = files(layout.buildDirectory.dir('classes/java/main')) + configurations.annotationProcessor + configurations.compileClasspath
    mainClass = 'net.sixik.ga_utils.javatogpu.runtime.GpuMethodBodyRewriter'
    args layout.buildDirectory.dir('classes/java/main').get().asFile.absolutePath
}

tasks.named('classes') {
    dependsOn tasks.named('rewriteGpuMethods')
}

The annotation processor generates GPU metadata and launcher resources. rewriteGpuMethods runs after compileJava and updates compiled class files so normal calls such as DemoKernel.transform(input, output) go through JavaToGpu.

Optional stricter IR validation:

dependencies {
    annotationProcessor 'io.github.deussixik:javatogpu-ir-validation:0.1.0-alpha.5'
}

tasks.withType(JavaCompile).configureEach {
    options.compilerArgs += '-Ajavatogpu.irValidation=diagnostic'
    options.compilerArgs += '-Ajavatogpu.irValidationDiagnostics=summary'
    options.compilerArgs += '-Ajavatogpu.irValidationReport=reports/javatogpu-ir-validation.properties'
}

Start with diagnostic mode. Move to stricter modes only when you want CI to fail on validation diagnostics.

First Kernel

import net.sixik.ga_utils.javatogpu.api.GPU;
import net.sixik.ga_utils.javatogpu.api.annotations.GPUGlobal;

public final class DemoKernel {
    @net.sixik.ga_utils.javatogpu.api.annotations.GPU
    public static void transform(
            @GPUGlobal float[] input,
            @GPUGlobal float[] output
    ) {
        int id = GPU.get_global_id(0);
        output[id] = GPU.sin(input[id]) + 2.0f;
    }
}

Run it through the OpenCL runtime:

import net.sixik.ga_utils.javatogpu.api.GpuScope;
import net.sixik.ga_utils.javatogpu.api.GpuPreparedLauncher;
import net.sixik.ga_utils.javatogpu.api.JavaToGpu;

try (GpuScope ignored = JavaToGpu.useOpenClSharedCache()) {
    DemoKernel.transform(input, output);
} finally {
    JavaToGpu.shutdownOpenClSharedCache();
}

Use JavaToGpu.useOpenCl() for one-off calls. Use JavaToGpu.useOpenClSharedCache() for repeated calls so the OpenCL session and compile cache stay warm. For tight loops, prepare the generated method once and call the prepared handle:

try (GpuScope ignored = JavaToGpu.useOpenClSharedCache()) {
    GpuPreparedLauncher launcher = JavaToGpu.prepare(DemoKernel.class, "transform", input, output);

    for (int i = 0; i < 1000; i++) {
        launcher.invoke(input, output);
    }
} finally {
    JavaToGpu.shutdownOpenClSharedCache();
}

The lower-level runtime.GpuRuntime entrypoint remains available for advanced runtime configuration and compatibility.

Important Alpha Limits

• @GPU entry methods normally return void; write results to output buffers.
• Generated launcher convenience helpers can cover narrow return-first cases, but output parameters are the stable alpha pattern.
• General object allocation, virtual dispatch, exceptions, recursion, monitors, and heap object graphs are not supported inside kernels.
• Arrays inside @GPUStruct fields are not supported in the current alpha.
• OpenCL is the active backend today. CUDA, Vulkan, and Metal are future directions.

See Known Limitations before using JavaToGpu in a larger project.

Documentation

Start here:

• User Quickstart - shortest path to one OpenCL-backed output array.
• Getting Started - first kernel with more context.
• Cookbook - copyable user patterns.
• Troubleshooting - first-run failures and fixes.
• Performance Basics - cold compile, warm cache, launch overhead, and when GPU execution is worth it.
• Known Limitations - current alpha boundaries.

Data and runtime:

• OpenCL Data Model - arrays, structs, vectors, pointers, packed blobs, and images.
• Method Tests - fixture-based @GPUTest checks, including @GPUStruct examples.
• Runtime Guide - runtime scopes, launch sizes, logging, artifacts, and advanced options.
• API Overview - public packages and most-used types.

Advanced and maintainer docs:

• Language Contract - exact supported Java subset.
• IR Validation - optional stricter compiler checks.
• IR Optimizer - optional optimizer profiles, journals, and dumps.
• Backend Adapter Authoring - backend provider/SPI path.
• Public API And Extension Contract - extension services and compatibility boundaries.
• Validation and Operations - local validation routines and OpenCL evidence artifacts.
• Diagnostics Reference - detailed diagnostic vocabulary.
• Publishing Guide - Maven Central publishing notes.

Useful Commands

Run the normal processor tests:

.\gradlew.bat :processor:test --console=plain

Run real OpenCL validation on a GPU machine:

.\gradlew.bat :processor:openClOperationalRoutine --rerun-tasks --console=plain

Run the curated user-facing OpenCL walkthrough:

.\gradlew.bat :examples-app:runOpenClPracticalReleaseExample --console=plain

Show backend/device selection explanations without running a kernel:

.\gradlew.bat :examples-app:runBackendSelectionExample --console=plain

Show the public runtime facade and launch helpers without running a kernel:

.\gradlew.bat :examples-app:runRuntimeFacadeExample --console=plain

Run the optional IR optimizer journal example:

.\gradlew.bat :examples-app:runOptimizationJournalExample --console=plain

OpenCL reports are written under:

processor/build/reports/opencl/

Start with validation-report.md when checking a run.

Project Layout

• processor - annotation processor, compiler, OpenCL emitter, runtime, launchers, tests, and validation buckets.
• ir-validation - optional stricter IR validation module.
• ir-optimizer - optional backend-neutral IR optimizer skeleton and future transform module.
• ir-vendor-optimizer - optional vendor-specific IR optimizer provider skeleton.
• examples-app - example kernels and usage patterns.
• test-app - consumer-style sample application.
• docs - public documentation.

Publishing

Published artifacts:

io.github.deussixik:javatogpu
io.github.deussixik:javatogpu-ir-validation
io.github.deussixik:javatogpu-ir-optimizer
io.github.deussixik:javatogpu-ir-vendor-optimizer

Publishing is configured for the main processor artifact, optional IR validation artifact, optional backend-neutral IR optimizer artifact, and optional vendor optimizer provider artifact. Keep Maven Central credentials and signing keys outside the repository. See Publishing Guide.

License

See LICENSE.