Time for pudding... and another Panama update

Tue Dec 20 14:00:53 UTC 2022

Hi all,
with JEP 434 [25] integrated into Java 20, it is time for another Panama 
update.

The Foreign Function & Memory API has been a Preview API since Java 19. 
Since then, the already biggie number of applications using Panama has 
been growing steadily [1-14]. As always, we are thankful for all the 
feedback provided through this and other channels. In all projects, but 
especially in a hydra-like project like this, feedback is essential, so 
please do keep this up!

After the first preview in Java 19, while most of the FFM API was in a 
very stable state, it was also clear that there were two areas of 
uncertainties. The first had to do with the split between MemoryAddress 
and MemorySegment. While this split made logical sense when it was 
introduced, it also made a lot of application code more verbose, and for 
no good reason. The new FFM API iteration in Java 20 rectifies this 
issue, by doubling down on memory segments [15]: in Java 20 memory 
segments act both as buffers, *and* as addresses (e.g. when their size 
is zero). As recently demonstrated [16] this leads to significant 
simplifications in client code using jextract.

The other area of uncertainty in the FFM API revolved around the 
MemorySession abstraction, which was trying to do too many things at 
once. The new iteration of the FFM API splits MemorySession into two 
abstractions [17]: an Arena, which is used to allocate and 
deterministically release memory in a try-with-resource statement, and a 
SegmentScope, which is used to indicate the temporal bounds associated 
with a memory segment. This split leads to a more principled API, and 
one that is much easier to build upon (as a result of this split, the 
Arena interface has been made non-sealed and can be extended to define 
custom allocators). Some long standing issues, such as lack of 
encapsulation w.r.t. MemorySession::close have also been addressed. 
Overall, we believe this is a good improvement, but it's fair to say 
that more time (and feedback) is required to understand if lifetime 
management in the FFM API has reached its lowest energy state (which 
might, in turn, affect our chances to finalize the FFM API in 21). This 
is perhaps not surprising: one of the main challenges of the FFM API is 
that to bring timely *and* safe deallocation in a programming language 
that is built around the idea of *implicit* deallocation, managed by a 
garbage collector. As such, we should make sure we get this absolutely 
right.

As pointed out in [18], we realized that some classes that are currently 
part of the FFM API (yes, we're looking at you VaList!) are too 
hopelessly platform specific, and, while handy, they probably do not 
deserve to be part of a Java SE API. The current thinking, confirmed by 
the feedback received in this mailing list (thanks!) is that we will 
likely drop VaList and VaList.Builder from Java 21. As for the rest of 
the Linker API, it's all looking very good and stable. Java 20 adds the 
concept of "linker option", which we used to model variadic calls, and 
also to capture the state of "errno" and other runtime-dependent 
variables in a fairly general way [19]. We have plans to add more linker 
options in the future, perhaps to remove the cost of state transitions 
in trivial calls, or to allow Java code to pass _heap_ segments directly 
to native calls (pinning), or to add custom signal handlers for native 
functions (as some native functions like to report errors that way). We 
believe that these improvement can be delivered incrementally, even 
*after* the FFM API is finalized.

Last but not least, we have made solid progress on the jextract front. A 
year ago the jextract tool was still part of the Panama repo [20]. Since 
then, we have moved jextract in its own repository [21] and started 
offering jextract binaries [22], so as to help developers getting 
started. Overall, the jextract tool has benefited from this split, and 
the number of external contributions has increased steadily (as the 
process for building standalone jextract is much simpler, thanks to the 
new Gradle build). Over the last few months we have been working on a 
number of usability improvements, such as the ability to generate 
javadoc with C-like signatures for all the generates structs and 
functions [23]. But, of course, in a tool like jextract there is always 
some tinkering left to do: possible areas of improvement include adding 
first class support for capturing errno (using the linker option 
machinery described above), improving the mapping for C structs, and 
investigate ways to reduce the static footprint of the jextract 
generated code (perhaps in combination with some explorations happening 
as part of Project Leyden [24]).

This sums up where we are, and should provide some guidance of where 
things are headed in the various areas touched by this project.

Cheers
Maurizio

[1] - https://github.com/manuelbl/JavaDoesUSB
[2] - https://github.com/BlueGoliath/Envious-FX
[3] - https://github.com/boulder-on/JPassport
[4] - https://github.com/carldea/panama4newbies
[5] - https://github.com/rmaucher/openssl-panama-foreign
[6] - https://github.com/openjdk/jextract
[7] - https://github.com/netty/netty-incubator-buffer-api
[8] - https://github.com/apache/lucene
[9] - https://github.com/cryptomator/jfuse
[10] - https://github.com/jzy3d/panama-gl
[11] - https://github.com/hhu-bsinfo/infinileap
[12] - https://gitlab.com/mhammons/slinc
[13] - https://github.com/IGJoshua/coffi
[14] - https://github.com/brcolow/java-vulkan
[15] - https://mail.openjdk.org/pipermail/panama-dev/2022-July/017181.html
[16] - 
https://github.com/brcolow/java-vulkan/commit/171f167782eea538b19b60d5fa73e9f75a112f6d
[17] - 
https://mail.openjdk.org/pipermail/panama-dev/2022-November/017991.html
[18] - 
https://mail.openjdk.org/pipermail/panama-dev/2022-November/018096.html
[19] - https://git.openjdk.org/panama-foreign/pull/742
[20] - https://github.com/openjdk/panama-foreign
[21] - https://github.com/openjdk/jextract
[22] - https://jdk.java.net/jextract/
[23] - https://git.openjdk.org/jextract/pull/85
[24] - 
https://mail.openjdk.org/pipermail/leyden-dev/2022-November/000092.html
[25] - https://openjdk.org/jeps/434