Skip to content

[GR-60209] Implement new foreign configuration file syntax. #11023

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 12, 2025

Conversation

graalvmbot
Copy link
Collaborator

Implements a new, more user-friendly FFM API configuration file syntax.
Before this change, the configuration file syntax was based on the reverse-engineered toString representation of the function descriptors and memory layouts which turned out to be very tricky to use.

We therefore decided to introduce a syntax that aligns with the MemoryLayout factory methods.
The configuration file is still a JSON file. We now use a more JSON-style way to define a function descriptor:

{
  "downcalls": [
    { "returnType": "Layout", "parameterTypes": ["Layout", "Layout"] },
  ]
}

The syntax for a single returnType or parameterType is:

 Layout ::= Alignment | StructLayout | UnionLayout | SequenceLayout | ValueLayout | PaddingLayout
 Alignment ::= 'align' '(' Int ',' Layout ')'
 StructLayout ::= 'struct' '(' Layout* ')'
 UnionLayout ::=  'union' '(' Layout* ')'
 SequenceLayout ::= 'sequence' '(' Int ',' Layout ')'
 ValueLayout ::=  canonical layout (e.g. 'int', 'long', ...)
 PaddingLayout ::= 'padding' '(' Int ')'
 Int ::= a positive decimal integer

Example:

{ 
    "returnType":  "double", 
    "parameterTypes": ["sequence(10, long)", "struct(long, padding(8), long)", "union(int, double)"] 
}

Furthermore, for direct upcalls it is now possible to skip declaration of returnType and parameterTypes if the Java signature can be represented as FunctionDescriptor without ambiguity. This is the case if the Java signature does not contain any MemorySegment parameter or return type. For example:

Java:

public class MyClass {
    public static int foo(long x) {
        // ...
    }
    
    public static int foo(double x) {
        // ...
    }
}

Configuration File:

{
  "directUpcalls": [
    { "class", "MyClass", "method": "foo" },
  ]
}

This will register both overloads of MyClass.foo for direct upcalls.

An appropriate update of the docs (i.e. ForeignInterface.md) will follow in a separate PR.

@oracle-contributor-agreement oracle-contributor-agreement bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Apr 10, 2025
@graalvmbot graalvmbot force-pushed the fa/GR-60209/foreign_conf_file_syntax branch 2 times, most recently from 2c1fd55 to 5e85f05 Compare April 11, 2025 17:33
@graalvmbot graalvmbot force-pushed the fa/GR-60209/foreign_conf_file_syntax branch from 5e85f05 to 9d7699d Compare April 11, 2025 20:03
@graalvmbot graalvmbot closed this Apr 12, 2025
@graalvmbot graalvmbot deleted the fa/GR-60209/foreign_conf_file_syntax branch April 12, 2025 02:34
@graalvmbot graalvmbot merged commit 272457e into master Apr 12, 2025
12 of 13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
OCA Verified All contributors have signed the Oracle Contributor Agreement.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants