RFR: Add jextract guide [v2]

[Jorn Vernee]

On Wed, 10 Apr 2024 10:08:25 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> doc/GUIDE.md line 451:
>> 
>>> 449: returned by the `java.lang.foreign.Linker::upcallStub` method. The `arena` argument denotes
>>> 450: the lifetime of the upcall stub, meaning that the upcall stub will be freed when the arena
>>> 451: is closed (after which the callback instance should no longer be called).
>> 
>> "should not be called" seems to imply that if we call it something bad happens, but we can call it (e.g. it's up to our "goodwill"). "can no longer be called" seems more appropriate?
>
> Of course, if the native code stashes the function pointer in a variable somewhere, it would be possible for it to call the func pointer again. But what I meant is that, in principle, FFM should give you an exception when trying to call `call_me_back` again after the arena has been closed, or calling `callback_t::invoke` on a closed segment.

Yes, I had `can no longer be called` before, but switched to `should not be called` since it's technically more correct. I think `can not longer be called` makes more sense for the reader, in hindsight. Thanks

-------------

PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559499178