# 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

```rust
#[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