From 4c981c9c9a958e06fbfb7796fde9da6a5d184b69 Mon Sep 17 00:00:00 2001 From: Orion Kindel Date: Wed, 5 Apr 2023 09:08:11 -0700 Subject: [PATCH] docs: add glue/readme --- toad-java-glue-rs/README.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 toad-java-glue-rs/README.md diff --git a/toad-java-glue-rs/README.md b/toad-java-glue-rs/README.md new file mode 100644 index 0000000..40858e0 --- /dev/null +++ b/toad-java-glue-rs/README.md @@ -0,0 +1,29 @@ +## toad-java-glue +Implementations of native java methods and state for +running `toad` with the JVM + +### 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 +#### justification +aside from the [runtime](#pub-static-mut-runtime), all usage of +unsafe in safe functions is 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](https://doc.rust-lang.org/nightly/std/ptr/index.html#strict-provenance) +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.