Project Panama: Interconnecting JVM and native code

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

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

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 native libraries

Community

This Project is sponsored by the Hotspot Group.

Mailing lists & News
- panama-dev — the usual developer list
- panama-spec-experts — moderated, restricted to specification discussions only
- Stay tuned on latest Panama development at Inside.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

Repository organization

Project Panama is designed to incubate a series of components for eventual inclusion in the JDK, via curated merge. Following the experience of Project Amber, and Project Valhalla, we have two sanbox-like repositories:

Panama foreign support, which contains the following active branches:
- foreign-memaccess+abi, this branch adds support for foreign memory access, as well as for foreign function calls;
- foreign-jextract, this branch provides a tool (jextract) which mechanically generate Java bindings from native library headers
Panama vector support, which contains the following active branches:
- vectorIntrinsics, this branch adds vectorization support in Java through JVM intriniscs.

The master branch in these repositopries is kept in sync with jdk/jdk, and where each experimental feature is developed in its own feature branch.

When first cloning the panama repository, it is necessary to update it to the desired experimental branch; this can be achieved using the git checkout ${branch} command.

For an up-to-date list of the available branches, you might also want to run the git branch command. For more information regarding each branch, please refer to the README.${branch} file in that branch (if that file does not exist, usual OpenJDK build instruction apply).

The legacy Panama repository is also available here, although we do not expect to carry out further work there; as such this repository should not be used (and in the future we might make this more explicit by marking the legacy repository as read-only).

Repository workflow

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

No changes will be pushed to the default branch of the Panama repository. This branch should in fact always be in sync with the upstream repository (jdk/jdk) to facilitate automatic integration of upstream changes, as well as to allow developers to generate diffs against upstream in an easy and predictable fashion (see below).
Create and update JIRA issues to informally describe chunks of work, using repo-panama as the value of the Fix Version field. Additionally, labels are used to identify the branch to which the issue refers to, as shown here;
Publish, review and integrate changesets via pull requests, according to the Skara workflow. A typical example of a Panama pull request can be found here
Automated infrastructure will take care of performing regular test runs when new changes are pushed to any of the Panama branches; additionally, the infrastructure might automatically propagate changesets from the default branch to other experimental branches (not all branches might opt in on this feature given the subtlety of some of the changes involved).
Infrequently, create a “curated” change set targeted at the upstream JDK repository; properly review, test, integrate. For an example of how this integration process might work, see here. Developers can easily generate a diff against upstream using the git diff master command from any experimental branch.