toad/toad-java
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: add glue/readme

Browse Source
This commit is contained in:
Orion Kindel 2023-04-05 09:08:11 -07:00
parent e5622087dc
commit 4c981c9c9a
Signed by untrusted user who does not match committer: orion
GPG Key ID: 6D4165AE4C928719
1 changed files with 29 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
toad-java-glue-rs/README.md Normal file
View File

@ -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.