jvmti-bindings

Write JVM agents in Rust with explicit safety boundaries and production-grade ergonomics.

Complete JNI and JVMTI bindings plus higher-level abstractions designed for building profilers, tracers, debuggers, and runtime instrumentation — without writing C or C++.

This crate focuses on:

• Making ownership, lifetimes, and error handling explicit
• Reducing common JVMTI footguns
• Keeping unsafe behavior localized and auditable

It is intended for serious native JVM tooling, not just experimentation.

Why This Exists

JVMTI is powerful — and notoriously easy to misuse.

Typical problems when writing agents:

• Unchecked error codes that silently corrupt state
• Invalid reference lifetimes causing segfaults
• Allocator mismatches leaking memory
• Thread-local JNIEnv misuse across callbacks
• Undocumented callback constraints causing deadlocks

Most existing Rust options either:

• Expose raw bindings with little guidance
• Rely on build-time bindgen
• Are incomplete or unmaintained (7+ years)
• Optimize for JNI, not JVMTI agents

This crate was designed around how agents are actually written, not around mirroring C headers.

Comparison with Alternatives

When to use what:

• jvmti-bindings: Building JVMTI agents (profilers, tracers, debuggers)
• jni: Calling Java from Rust applications (not agents)
• jvmti-rs: Legacy projects already using it
• jni-simple: Minimal JNI with no frills

Why Rust for JVMTI?

C++ is the traditional choice, but Rust offers compelling advantages:

• Memory safety without GC — JVMTI agents run inside the JVM process; a segfault kills the application
• Fearless concurrency — JVMTI callbacks fire from multiple threads simultaneously
• Zero-cost abstractions — RAII guards and Result types add safety without runtime overhead
• No runtime dependencies — Deploy a single .so/.dylib/.dll with no external libraries
• Modern tooling — Cargo, docs.rs, and crates.io beat Makefiles and manual distribution

Java agents (java.lang.instrument) are simpler but can't access low-level features like heap iteration, breakpoints, or raw bytecode hooks.

Design Goals

Quick Start

1. Create your crate

cargo new --lib my_agent
cd my_agent

2. Configure Cargo.toml

[lib]
crate-type = ["cdylib"]

[dependencies]
jvmti-bindings = "0.1"

3. Implement your agent

use jvmti_bindings::{Agent, export_agent};
use jvmti_bindings::sys::jni;

#[derive(Default)]
struct MyAgent;

impl Agent for MyAgent {
    fn on_load(&self, vm: *mut jni::JavaVM, options: &str) -> jni::jint {
        println!("[MyAgent] Loaded with options: {}", options);
        jni::JNI_OK
    }

    fn vm_init(&self, _jni: *mut jni::JNIEnv, _thread: jni::jthread) {
        println!("[MyAgent] VM initialized");
    }

    fn vm_death(&self, _jni: *mut jni::JNIEnv) {
        println!("[MyAgent] VM shutting down");
    }
}

export_agent!(MyAgent);

4. Build and run

cargo build --release

# Linux
java -agentpath:./target/release/libmy_agent.so=myoptions MyApp

# macOS
java -agentpath:./target/release/libmy_agent.dylib=myoptions MyApp

# Windows
java -agentpath:./target/release/my_agent.dll=myoptions MyApp

What export_agent! Does

The macro generates the native entry points the JVM expects.

It does:

• Generate Agent_OnLoad / Agent_OnUnload FFI entry points
• Initialize JNI and JVMTI environments
• Register callbacks before enabling events
• Convert JVMTI error codes into Result<T, JvmtiError>
• Store your agent instance globally (must be Sync + Send)

It does not:

• Hide undefined JVMTI behavior
• Make callbacks re-entrant or async-safe
• Attach arbitrary native threads automatically
• Prevent JVM crashes from invalid JVMTI usage

The goal is clarity, not magic.

Safety Model

This crate enforces the following invariants:

What Remains Unsafe

Some things cannot be made safe by design:

• Bytecode transformation correctness — invalid bytecode crashes the JVM
• Callback timing assumptions — JVMTI events fire at specific phases
• Blocking in callbacks — long operations in GC callbacks deadlock
• Cross-thread reference sharing — JNI local refs are thread-local

Rust helps — but JVMTI is still a sharp tool.

Is This For You?

Yes, if you are:

• Building profilers, tracers, debuggers, or instrumentation
• Want Rust's type system around JVMTI's sharp edges
• Need a single crate that works across JDK 8–27
• Comfortable reading JVMTI docs for advanced use cases

Probably not, if you:

• Only need basic JNI calls (consider the jni crate)
• Are uncomfortable debugging native JVM crashes
• Need dynamic attach API (not yet wrapped)
• Want zero unsafe anywhere

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Your Agent Code                       │
│         impl Agent for MyAgent { ... }                   │
├─────────────────────────────────────────────────────────┤
│                   Agent Trait + Macros                   │
│      Agent, export_agent!, get_default_callbacks()       │
├─────────────────────────────────────────────────────────┤
│              High-Level Wrappers (env module)            │
│   Jvmti      - JVMTI operations (153 methods)            │
│   JniEnv     - JNI operations (60+ methods)              │
│   LocalRef   - RAII guard, prevented from escaping       │
│   GlobalRef  - RAII guard, releases on drop              │
├─────────────────────────────────────────────────────────┤
│              Raw FFI Bindings (sys module)               │
│   sys::jni   - Complete JNI vtable (236 functions)       │
│   sys::jvmti - Complete JVMTI vtable (156 functions)     │
└─────────────────────────────────────────────────────────┘

Enabling Events

Events require three steps — capabilities, callbacks, then enable:

use jvmti_bindings::env::Jvmti;
use jvmti_bindings::sys::jvmti;
use jvmti_bindings::get_default_callbacks;

fn on_load(&self, vm: *mut jni::JavaVM, _options: &str) -> jni::jint {
    let jvmti_env = Jvmti::new(vm).expect("Failed to get JVMTI");

    // 1. Request capabilities (must happen in on_load)
    let mut caps = jvmti::jvmtiCapabilities::default();
    caps.set_can_generate_all_class_hook_events(true);
    jvmti_env.add_capabilities(&caps).expect("capabilities");

    // 2. Wire callbacks to your Agent impl
    let callbacks = get_default_callbacks();
    jvmti_env.set_event_callbacks(callbacks).expect("callbacks");

    // 3. Enable specific events
    jvmti_env.set_event_notification_mode(
        true,
        jvmti::JVMTI_EVENT_CLASS_FILE_LOAD_HOOK,
        std::ptr::null_mut(),
    ).expect("enable");

    jni::JNI_OK
}

Capabilities Reference

JDK Compatibility

Bindings generated from JDK 27 headers, backwards compatible to JDK 8.

Project Status

Examples

# Minimal agent — lifecycle events only
cargo build --release --example minimal

# Method counter — counts all method entries/exits
cargo build --release --example method_counter

# Class logger — logs every class load
cargo build --release --example class_logger

License

MIT OR Apache-2.0