On Tue, 9 Apr 2024 17:20:22 GMT, Jorn Vernee <jvernee@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 392:
390: ### Function Pointers 391: 392: If jextract finds a function pointer type in the header files it parses, it will generate
More directly: `Jextract will generate a separate class for each function pointer type found in the header files it parses.` doc/GUIDE.md line 420:
418: We again have a meta-data accessor for the function descriptor (`descriptor()`). There's 419: an `allocate` method that can be used to allocate a new instance of this function pointer, 420: who's implementation is implemented by the `fi` functional interface instance. And finally,
Suggestion: whose implementation is defined by the `fi` functional interface instance. And finally, doc/GUIDE.md line 448:
446: 447: Here we use the lambda `(a, b) -> a * b` as the implementation of the `callback_t` instance 448: we create using the call to `allocate`. This method returns an upcall stub like the ones
Suggestion: we create using `allocate`. This method returns an upcall stub like the ones doc/GUIDE.md line 449:
447: Here we use the lambda `(a, b) -> a * b` as the implementation of the `callback_t` instance 448: we create using the call to `allocate`. This method returns an upcall stub like the ones 449: returned by the `java.lang.foreign.Linker::upcallStub` method. The `arena` argument denotes
Should there be a link here - like we did for symbol lookup? 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? doc/GUIDE.md line 486:
484: `callback_t` instance. 485: 486: Jextract generates function pointer classes like the `callback_t` class for function
I know what you mean here - but I wonder if readers will get it w/o some kind of example. doc/GUIDE.md line 493:
491: 492: Jextract handles variadic functions differently from regular functions. Variadic functions 493: in C more or less like a template, where the calling convention changes based on the number
Suggestion: in C behave more or less like a template, where the calling convention changes based on the number ------------- PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559178430 PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559179645 PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559181255 PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559181887 PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559183287 PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559187645 PR Review Comment: https://git.openjdk.org/jextract/pull/231#discussion_r1559188565