Project Panama: Interconnecting JVM and native code

We are improving and enriching the connections between the Javavirtual machine and well-defined but “foreign”(non-Java) APIs, including many interfaces commonly used by Cprogrammers.

To this end, Project Panama will include most or all of thesecomponents:

• native function calling from JVM
• native data access from JVM or inside JVM heap
• new data layouts in JVM heap
• native metadata definition for JVM
• header file API extraction tools (jextract)
• native library management APIs
• native-oriented interpreter and runtime“hooks”
• class and method resolution “hooks”
• native-oriented JIT optimizations
• tooling or wrapper interposition for safety
• exploratory work with difficult-to-integrate nativelibraries

Community

This Project is sponsored by theHotspot Group.

• Mailing lists & News
  • panama-dev— the usual developer list
  • panama-spec-experts — moderated, restricted tospecification discussions only
  • Stay tuned on latest Panama development atInside.java
• Design documents
  • Panama foreign memory acccess
  • Panama foreign function support
  • Panama jextract usage examples
  • early problem space overview:the isthmus in the VM
• JEPs
  • Foreign-Memory Access API JEPs:JEP-370,JEP-383
  • Foreign Linker API JEPs:JEP-389
  • Vector API JEP:JEP-338
• Talks
  • ByteBuffersare dead, long live ByteBuffers!
  • DeconstructingPanama
  • VectorAPI
  • Panama: aforeign policy for Java

Repository organization

Project Panama is designed to incubate a series of componentsfor eventual inclusion in the JDK, via curated merge. Following theexperience of Project Amber, and Project Valhalla, we have twosanbox-like repositories:

• Panamaforeign support, which contains the following active branches:
  • foreign-memaccess+abi, this branch adds support forforeign memory access, as well as forforeign function calls;
  • foreign-jextract, this branch provides a tool (jextract)which mechanically generate Java bindings from native libraryheaders
• Panamavector support, which contains the following active branches:
  • vectorIntrinsics, this branch adds vectorization supportin Java through JVM intriniscs.

The master branch in these repositopries is kept in sync withjdk/jdk, and where each experimental feature is developed in itsown feature branch.

When first cloning the panama repository, it is necessary toupdate it to the desired experimental branch; this can be achievedusing thegit checkout ${branch} command.

For an up-to-date list of the available branches, you might alsowant to run thegit branch command. For moreinformation regarding each branch, please refer to theREADME.${branch} file in that branch (if that file does not exist,usual OpenJDK build instruction apply).

The legacy Panama repository is also availablehere, although wedo not expect to carry out further work there; as such thisrepository should not be used (and in the future we might make thismore explicit by marking the legacy repository asread-only).

Repository workflow

The repository will be managed as follows (note, this process islocal and subject to change):

• No changes will be pushed to the default branch of the Panamarepository. This branch should in fact always be in sync with theupstream repository (jdk/jdk) to facilitate automatic integrationof upstream changes, as well as to allow developers to generatediffs against upstream in an easy and predictable fashion (seebelow).
• Create and update JIRA issues to informally describe chunks ofwork, usingrepo-panama as the value of theFixVersion field. Additionally,labels are used to identifythe branch to which the issue refers to, as shownhere;
• Publish, review and integrate changesets via pull requests,according to theSkaraworkflow. A typical example of a Panama pull request can befoundhere
• Automated infrastructure will take care of performing regulartest runs when new changes are pushed to any of the Panamabranches; additionally, the infrastructure might automaticallypropagate changesets from the default branch to other experimentalbranches (not all branches might opt in on this feature given thesubtlety of some of the changes involved).
• Infrequently, create a “curated” change settargeted at the upstream JDK repository; properly review, test,integrate. For an example of how this integration process mightwork, seehere. Developers can easily generate a diff against upstreamusing thegit diff master command from anyexperimental branch.