Documentation project: JNI Workshop

[johnwalker]

I'm working on materials for a workshop that teaches JNI programming to Rust programmers, which uses jni-rs. Would you be interested in a project like that as a contribution to jni-rs?

[dmitry-timofeev]

Hi, @johnwalker , I think it's an awesome initiative. Including it in the project will extend the audience to all (prospective) users; and will make it more likely to stay up-to-date in case the APIs evolve.

When I studied the JNI, I found the tutorial on IBM Developer Works to be quite well-written. Although it is rather dated and does not cover additions post 1.2, it might work as a source of ideas on what to cover.

[johnwalker]

Awesome! Yeah, the one you referenced is nice. JNI is hard, so I'd love to get this stuff reviewed and representative of the best practices.

I have the start of some sections written, and can probably start raising PRs soon. Is there a place you think makes sense to add them? It's all mdbook material.

Edit: Current outline looks like:

• Environment setup
• Introduction to dividing
  • Java's load library
  • JNI signatures, division
• Debugging
  • A debugger in a debugger [intellij + clion]
• Divide by Zero, panic / result handling
• Building a JNI counter
  • Storing on the native heap
• Cleaning up resource leaks, using Cleaner / Try-with-resources
• Working with Java Objects from Rust

[dmitry-timofeev]

Awesome!

I'd certainly keep the tutorial code in the main repo in a separate module, so that in case of any changes to the API the tutorial code is also updated. Regarding the tutorial pages — what's the best practice for that? Would it make sense to create a separate repository for doc pages or keep them here?

---

On native resource management (Cleaning up resource leaks, using Cleaner / Try-with-resources), we've done some research when started our project, and discovered that GC-based approaches (i.e., finalize, PhantomReference and Cleaner) are quite tricky to get completely right. I've summarized the main nuances in this post, with a link to a more detailed presentation. It may be useful if you plan to cover GC-based approaches and show a complete and cross-platform solution.

[johnwalker]

I see a nice example here, which uses a single repo: https://github.com/camshaft/bolero

Let's do something similar to that! I like your idea of keeping the examples building together with the docs.

I've been very lucky to rely on https://github.com/corretto/amazon-corretto-crypto-provider/blob/develop/src/com/amazon/corretto/crypto/provider/Janitor.java for cleaning up native objects. It sounds like you've come up with a similar approach, and we should definitely spend the time to get that section right.

[dmitry-timofeev]

Let's do something similar to that!

Agree!

It sounds like you've come up with a similar approach

We did a prototype of a very similar approach, building on Guava's FinalizableReferenceQueue, but decided that the performance and complexity were not adequate. Therefore, we went with a deterministic approach that does not require client code to explicitly clean up any native objects. It relies on the luxury of being a framework and controlling the execution flow. In our case, the client code receives a context, which includes a Cleaner, where all native objects register their clean actions. When the client code completes, the framework requests the Cleaner from the context to perform all registered clean actions in the reverse order of their registration.

This approach provides both simple client code (no try-with-resources) and deterministic cleaning with good performance, however, it won't work as good for non-framework code — someone has to invoke Cleaner#close.

[worstpractice]

@johnwalker @dmitry-timofeev Any updates on this? What an amazing initiative. The discussion alone has proven most insightful thus far.

[togetherwithasteria]

I recently discovered https://github.com/giovanniberti/robusta too!! It's a pretty great alternative if you feel jni_fn needs to be more Rusty!!!