jvm-rs/docs/roast-vm-sys.md

roast-vm-sys Crate

Location: crates/roast-vm-sys/

A cdylib crate that exports native method implementations callable from Java via JNI.

Overview

roast-vm-sys is a JNI wrapper crate that exposes the roast-vm-core runtime to Java. It's compiled as a C dynamic library (cdylib) named roast_vm.

Exported Native Methods

The crate exports 40+ JNI native functions via #[no_mangle] extern "system" declarations.

By Module

Module	Functions
thread.rs	Thread.currentThread(), Thread.start0(), Thread.setPriority0()
object.rs	Object.hashCode(), Object.clone(), Object.notify(), Object.notifyAll(), Object.wait()
class.rs	Class.forName0(), Class.getPrimitiveClass(), Class.getDeclaredConstructors0()
reflection.rs	Reflection.getCallerClass()
reflect/array.rs	Array.newArray()
string.rs	String.intern()
system.rs	System.arraycopy(), System.nanoTime()
runtime.rs	Runtime.maxMemory(), Runtime.availableProcessors()
misc_unsafe.rs	Unsafe field offsets, volatile read/write, memory allocation
file_output_stream.rs	FileOutputStream.writeBytes()
system_props.rs	vmProperties() - VM identity (version 0.1.0, vendor "infernap12")
CDS.rs	Class Data Sharing stubs
signal.rs	Signal.handle0() stub
scoped_memory_access.rs	ScopedMemoryAccess registration

Bridge Pattern

Each native function follows this pattern:

1. Extract VmThread from JNIEnv.reserved0 using get_thread() helper
2. Resolve References - Convert JNI handles (jobject) to internal references:
   • resolve_object() - gets ObjectReference
   • resolve_array() - gets ArrayReference
   • resolve_reference() - gets generic ReferenceKind
3. Perform Operation via core VM APIs
4. Return Result in JNI-compatible format

Example Native Implementation

#[unsafe(no_mangle)]
pub extern "system" fn Java_org_example_MockIO_print(
    env: JNIEnv,
    _jclass: JClass,
    input: JString,
) {
    unsafe {
        let input: String = env.get_string_unchecked(&input)
            .expect("Couldn't get java string!")
            .into();
        std::io::stdout().write_all(input.as_bytes()).ok();
    }
}

File Structure

17 modules organized by Java class:

• lib.rs - Core helpers, test functions (MockIO.print(), Main.getTime())
• runtime.rs, thread.rs, class.rs - Core VM operations
• object.rs, string.rs, reflection.rs, reflect/ - Object/class introspection
• system.rs, file_output_stream.rs - System I/O
• misc_unsafe.rs - Unsafe memory operations (largest implementation, ~626 lines)
• CDS.rs, signal.rs, system_props.rs, scoped_memory_access.rs - Stubs/properties

GC Interaction

Native methods access the garbage collector via:

• thread.gc.read() / thread.gc.write() for object access
• Object creation, cloning, and array operations go through GC
• Field access via thread.gc or direct field references

Error Handling

Mixed approach:

• Some methods panic on errors
• Some return null/default values
• TODO comments indicate incomplete exception throwing