88 lines
3.1 KiB
Markdown
88 lines
3.1 KiB
Markdown
# 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
|