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
- 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.