toad-java/glue

toad-java-glue

Implementations of native java methods and state for running toad with the JVM

nightly

this project builds on the nightly channel so that it can use the pointer strict provenance API (explained in # pub static mut RUNTIME)

integers

all integers stored in java objects to be passed to rust code should use the dev.toad.ffi.uX compat classes to ensure that the primitive casts in rust succeed.

unsafe

externs

no extern fns called by java should be decorated unsafe and should instead be safe functions with unsafe expression bodies to clearly denote the patterns of unsafety within.

justification

with 1 exception described below in # pub static mut RUNTIME, all uses of unsafe in safe functions are accompanied by a // SAFETY comment justifying its use and explaining the risks (or not) of memory defects and UB.

pub static mut RUNTIME

unsafe is used in an unjustified manner to cast long addresses into pointers to the RUNTIME static or data within.

The RUNTIME static is created in a way such that the location in memory does not move. This means that addresses issued by rust code may be stored safely in java objects to be eventually passed back to rust code to perform operations on the rust structs.

Addresses are issued by rust code using the strict provenance API to avoid direct integer <> pointer casts, as well as to theoretically provide runtime guarantees that the addresses gotten from java do not attempt to access memory regions outside of the runtime data structure.