RFR: Add jextract guide

[Maurizio Cimadamore]

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

>> Add a comprehensive jextract guide under a new `doc/` folder.
>> 
>> This is meant as a comprehensive guide about the features of jextract and the code that it generates (including both examples from header files, the code that jextract generates, and corresponding Java user code). This is a first cut, and I'm anticipating quite a bit of comments.
>> 
>> Some sections of the readme have been moved to the guide (with minor edits here and there), and replaced by a link in the readme.
>
> 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.

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

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