Skip to content

Commit 8812e8a

Browse files
kimetakimeta
committed
New API, within new metadata package.
1 parent acfc254 commit 8812e8a

24 files changed

+955
-562
lines changed

‎sdk/mx.sdk/suite.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -970,6 +970,7 @@ class UniversalDetector {
970970
"exports" : [
971971
"com.oracle.svm.core.annotate",
972972
"org.graalvm.nativeimage.hosted",
973+
"org.graalvm.nativeimage.dynamicaccess",
973974
"org.graalvm.nativeimage.c.function",
974975
"org.graalvm.nativeimage.c.struct",
975976
"org.graalvm.nativeimage.c.type",

‎sdk/src/org.graalvm.nativeimage/snapshot.sigtest‎

Lines changed: 39 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1011,10 +1011,10 @@ meth public abstract java.nio.file.Path getImagePath()
10111011
CLSS public abstract interface static org.graalvm.nativeimage.hosted.Feature$AfterRegistrationAccess
10121012
outer org.graalvm.nativeimage.hosted.Feature
10131013
intf org.graalvm.nativeimage.hosted.Feature$FeatureAccess
1014-
meth public abstract org.graalvm.nativeimage.hosted.RuntimeJNIAccess getRuntimeJNIAccess()
1015-
meth public abstract org.graalvm.nativeimage.hosted.RuntimeReflection getRuntimeReflection()
1016-
meth public abstract org.graalvm.nativeimage.hosted.RuntimeResourceAccess getRuntimeResourceAccess()
1017-
meth public abstract org.graalvm.nativeimage.hosted.RuntimeForeignAccess getRuntimeForeignAccess()
1014+
meth public abstract org.graalvm.nativeimage.dynamicaccess.JNIAccess getJNIAccess()
1015+
meth public abstract org.graalvm.nativeimage.dynamicaccess.ReflectiveAccess getReflectiveAccess()
1016+
meth public abstract org.graalvm.nativeimage.dynamicaccess.ResourceAccess getResourceAccess()
1017+
meth public abstract org.graalvm.nativeimage.dynamicaccess.ForeignAccess getForeignAccess()
10181018

10191019
CLSS public abstract interface static org.graalvm.nativeimage.hosted.Feature$BeforeAnalysisAccess
10201020
outer org.graalvm.nativeimage.hosted.Feature
@@ -1104,34 +1104,23 @@ meth public !varargs static void initializeAtRunTime(java.lang.Class<?>[])
11041104
meth public !varargs static void initializeAtRunTime(java.lang.String[])
11051105
supr java.lang.Object
11061106

1107-
CLSS public abstract interface org.graalvm.nativeimage.hosted.RuntimeForeignAccess
1107+
CLSS public final org.graalvm.nativeimage.hosted.RuntimeForeignAccess
11081108
meth public !varargs static void registerForDirectUpcall(java.lang.invoke.MethodHandle,java.lang.Object,java.lang.Object[])
11091109
meth public !varargs static void registerForDowncall(java.lang.Object,java.lang.Object[])
11101110
meth public !varargs static void registerForUpcall(java.lang.Object,java.lang.Object[])
1111-
meth public !varargs abstract void registerForDirectUpcall(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.invoke.MethodHandle,java.lang.Object,java.lang.Object[])
1112-
meth public !varargs abstract void registerForDowncall(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Object,java.lang.Object[])
1113-
meth public !varargs abstract void registerForUpcall(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Object,java.lang.Object[])
1114-
1115-
CLSS public abstract interface org.graalvm.nativeimage.hosted.RuntimeJNIAccess
1116-
meth public !varargs abstract void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Class<?>[])
1117-
meth public !varargs abstract void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.reflect.Executable[])
1118-
meth public !varargs abstract void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.reflect.Field[])
1111+
supr java.lang.Object
1112+
1113+
CLSS public final org.graalvm.nativeimage.hosted.RuntimeJNIAccess
11191114
meth public !varargs static void register(java.lang.Class<?>[])
11201115
meth public !varargs static void register(java.lang.reflect.Executable[])
11211116
meth public !varargs static void register(java.lang.reflect.Field[])
1117+
supr java.lang.Object
11221118

11231119
CLSS public final org.graalvm.nativeimage.hosted.RuntimeProxyCreation
11241120
meth public !varargs static void register(java.lang.Class<?>[])
11251121
supr java.lang.Object
11261122

1127-
CLSS public abstract interface org.graalvm.nativeimage.hosted.RuntimeReflection
1128-
meth public !varargs abstract void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Class<?>[])
1129-
meth public abstract void registerClassLookup(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.String)
1130-
meth public !varargs abstract void registerUnsafeAllocation(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Class<?>[])
1131-
meth public !varargs abstract void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.reflect.Executable[])
1132-
meth public !varargs abstract void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.reflect.Field[])
1133-
meth public !varargs abstract void registerForSerialization(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Class<?>[])
1134-
meth public !varargs abstract java.lang.Class<?> registerProxy(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Class<?>[])
1123+
CLSS public final org.graalvm.nativeimage.hosted.RuntimeReflection
11351124
meth public !varargs static void register(boolean,boolean,java.lang.reflect.Field[])
11361125
anno 0 java.lang.Deprecated(boolean forRemoval=false, java.lang.String since="21.1")
11371126
meth public !varargs static void register(boolean,java.lang.reflect.Field[])
@@ -1157,16 +1146,40 @@ meth public static void registerAllRecordComponents(java.lang.Class<?>)
11571146
meth public static void registerAllSigners(java.lang.Class<?>)
11581147
meth public static void registerClassLookup(java.lang.String)
11591148
meth public static void registerFieldLookup(java.lang.Class<?>,java.lang.String)
1149+
supr java.lang.Object
11601150

1161-
CLSS public abstract interface org.graalvm.nativeimage.hosted.RuntimeResourceAccess
1162-
meth public abstract void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Module,java.lang.String)
1163-
meth public void register(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.String)
1164-
meth public abstract void registerResourceBundle(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.Module,java.lang.String)
1165-
meth public void registerResourceBundle(org.graalvm.nativeimage.hosted.AccessCondition,java.lang.String)
1151+
CLSS public final org.graalvm.nativeimage.hosted.RuntimeResourceAccess
11661152
meth public static void addResource(java.lang.Module,java.lang.String)
11671153
meth public static void addResource(java.lang.Module,java.lang.String,byte[])
11681154
meth public static void addResourceBundle(java.lang.Module,java.lang.String)
11691155
meth public static void addResourceBundle(java.lang.Module,java.lang.String,java.util.Locale[])
1156+
supr java.lang.Object
1157+
1158+
CLSS public abstract interface org.graalvm.nativeimage.dynamicaccess.ReflectiveAccess
1159+
meth public !varargs abstract void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Class<?>[])
1160+
meth public abstract void registerClassLookup(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.String)
1161+
meth public !varargs abstract void registerUnsafeAllocation(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Class<?>[])
1162+
meth public !varargs abstract void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.reflect.Executable[])
1163+
meth public !varargs abstract void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.reflect.Field[])
1164+
meth public !varargs abstract void registerForSerialization(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Class<?>[])
1165+
meth public !varargs abstract java.lang.Class<?> registerProxy(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Class<?>[])
1166+
1167+
CLSS public abstract interface org.graalvm.nativeimage.dynamicaccess.ResourceAccess
1168+
meth public abstract void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Module,java.lang.String)
1169+
meth public void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.String)
1170+
meth public abstract void registerResourceBundle(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Module,java.lang.String)
1171+
meth public void registerResourceBundle(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.String)
1172+
1173+
CLSS public abstract interface org.graalvm.nativeimage.dynamicaccess.JNIAccess
1174+
meth public !varargs abstract void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Class<?>[])
1175+
meth public !varargs abstract void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.reflect.Executable[])
1176+
meth public !varargs abstract void register(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.reflect.Field[])
1177+
1178+
CLSS public abstract interface org.graalvm.nativeimage.dynamicaccess.ForeignAccess
1179+
meth public !varargs abstract void registerForDirectUpcall(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.invoke.MethodHandle,java.lang.Object,java.lang.Object[])
1180+
meth public !varargs abstract void registerForDowncall(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Object,java.lang.Object[])
1181+
meth public !varargs abstract void registerForUpcall(org.graalvm.nativeimage.dynamicaccess.AccessCondition,java.lang.Object,java.lang.Object[])
1182+
11701183

11711184
CLSS public final org.graalvm.nativeimage.hosted.RuntimeSerialization
11721185
meth public !varargs static void register(java.lang.Class<?>[])

‎sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/dynamicaccess/AccessCondition.java‎

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,6 @@
4141
package org.graalvm.nativeimage.dynamicaccess;
4242

4343
import org.graalvm.nativeimage.impl.TypeReachabilityCondition;
44-
import org.graalvm.nativeimage.dynamicaccess.ForeignAccess;
45-
import org.graalvm.nativeimage.dynamicaccess.JNIAccess;
46-
import org.graalvm.nativeimage.dynamicaccess.ReflectiveAccess;
47-
import org.graalvm.nativeimage.dynamicaccess.ResourceAccess;
4844

4945
/**
5046
* A condition that must be satisfied to register elements for dynamic access (e.g., reflection,

‎sdk/src/org.graalvm.nativeimage/src/org/graalvm/nativeimage/dynamicaccess/ForeignAccess.java‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
/*
2+
* Copyright (c) 2025, Oracle and/or its affiliates. All rights reserved.
3+
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4+
*
5+
* The Universal Permissive License (UPL), Version 1.0
6+
*
7+
* Subject to the condition set forth below, permission is hereby granted to any
8+
* person obtaining a copy of this software, associated documentation and/or
9+
* data (collectively the "Software"), free of charge and under any and all
10+
* copyright rights in the Software, and any and all patent rights owned or
11+
* freely licensable by each licensor hereunder covering either (i) the
12+
* unmodified Software as contributed to or provided by such licensor, or (ii)
13+
* the Larger Works (as defined below), to deal in both
14+
*
15+
* (a) the Software, and
16+
*
17+
* (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
18+
* one is included with the Software each a "Larger Work" to which the Software
19+
* is contributed by such licensors),
20+
*
21+
* without restriction, including without limitation the rights to copy, create
22+
* derivative works of, display, perform, and distribute the Software and make,
23+
* use, sell, offer for sale, import, export, have made, and have sold the
24+
* Software and the Larger Work(s), and to sublicense the foregoing rights on
25+
* either these or other terms.
26+
*
27+
* This license is subject to the following condition:
28+
*
29+
* The above copyright notice and either this complete permission notice or at a
30+
* minimum a reference to the UPL must be included in all copies or substantial
31+
* portions of the Software.
32+
*
33+
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
34+
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
35+
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
36+
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
37+
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
38+
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
39+
* SOFTWARE.
40+
*/
41+
package org.graalvm.nativeimage.dynamicaccess;
42+
43+
import org.graalvm.nativeimage.hosted.Feature;
44+
45+
import java.lang.invoke.MethodHandle;
46+
import java.lang.invoke.MethodType;
47+
48+
/**
49+
* This interface is used to register classes, methods, and fields for foreign access at runtime. An
50+
* instance of this interface is acquired via
51+
* {@link Feature.AfterRegistrationAccess#getForeignAccess()}.
52+
* <p>
53+
* All methods in {@link ForeignAccess} require a {@link AccessCondition} as their first parameter.
54+
* Registration for foreign access will happen only if the specified condition is satisfied.
55+
*
56+
* <h3>How to use</h3>
57+
*
58+
* {@link ForeignAccess} should only be used during {@link Feature#afterRegistration}. Any attempt
59+
* to register metadata in any other phase will result in an error.
60+
* <p>
61+
* <strong>Example:</strong>
62+
*
63+
* <pre>{@code @Override
64+
* public void afterRegistration(AfterRegistrationAccess access) {
65+
* ForeignAccess foreignAccess = access.getForeignAccess();
66+
* AccessCondition condition = AccessCondition.typeReached(Condition.class);
67+
* foreignAccess.registerForDowncall(condition, java.lang.foreign.ValueLayout.JAVA_INT);
68+
* }
69+
* }</pre>
70+
*
71+
* @since 25.0
72+
*/
73+
public interface ForeignAccess {
74+
75+
/**
76+
* Registers the provided function descriptor and options pair at image build time for downcalls
77+
* into foreign code, if the {@code condition} is satisfied. Required to get a downcall method
78+
* handle using {@link java.lang.foreign.Linker#downcallHandle} for the same descriptor and
79+
* options at runtime.
80+
* <p>
81+
* Even though this method is weakly typed for compatibility reasons, runtime checks will be
82+
* performed to ensure that the arguments have the expected type. It will be deprecated in favor
83+
* of strongly typed variant as soon as possible.
84+
*
85+
* @param condition represents the condition that needs to be satisfied in order to register
86+
* target resources.
87+
* @param desc A {@link java.lang.foreign.FunctionDescriptor} to register for downcalls.
88+
* @param options An array of {@link java.lang.foreign.Linker.Option} used for the downcalls.
89+
*
90+
* @since 25.0
91+
*/
92+
void registerForDowncall(AccessCondition condition, Object desc, Object... options);
93+
94+
/**
95+
* Registers the provided function descriptor and options pair at image build time for upcalls
96+
* from foreign code, if the {@code condition} is satisfied. Required to get an upcall stub
97+
* function pointer using {@link java.lang.foreign.Linker#upcallStub} for the same descriptor
98+
* and options at runtime.
99+
* <p>
100+
* Even though this method is weakly typed for compatibility reasons, runtime checks will be
101+
* performed to ensure that the arguments have the expected type. It will be deprecated in favor
102+
* of strongly typed variant as soon as possible.
103+
*
104+
* @param condition represents the condition that needs to be satisfied in order to register
105+
* target resources.
106+
* @param desc A {@link java.lang.foreign.FunctionDescriptor} to register for upcalls.
107+
* @param options An array of {@link java.lang.foreign.Linker.Option} used for the upcalls.
108+
*
109+
* @since 25.0
110+
*/
111+
void registerForUpcall(AccessCondition condition, Object desc, Object... options);
112+
113+
/**
114+
* Registers a specific static method (denoted by a method handle) as a fast upcall target, if
115+
* the {@code condition} is satisfied. This will create a specialized upcall stub that will
116+
* invoke only the specified method, which is much faster than using
117+
* {@link #registerForUpcall(AccessCondition, Object, Object...)}).
118+
* <p>
119+
* The provided method handle must be a direct method handle. Those are most commonly created
120+
* using {@link java.lang.invoke.MethodHandles.Lookup#findStatic(Class, String, MethodType)}.
121+
* However, a strict requirement is that it must be possible to create a non-empty descriptor
122+
* for the method handle using {@link MethodHandle#describeConstable()}. The denoted static
123+
* method will also be registered for reflective access since run-time code will also create a
124+
* method handle to denoted static method.
125+
* </p>
126+
* <p>
127+
* Even though this method is weakly typed for compatibility reasons, runtime checks will be
128+
* performed to ensure that the arguments have the expected type. It will be deprecated in favor
129+
* of strongly typed variant as soon as possible.
130+
* </p>
131+
*
132+
* @param condition represents the condition that needs to be satisfied in order to register
133+
* target resources.
134+
* @param target A direct method handle denoting a static method.
135+
* @param desc A {@link java.lang.foreign.FunctionDescriptor} to register for upcalls.
136+
* @param options An array of {@link java.lang.foreign.Linker.Option} used for the upcalls.
137+
*
138+
* @since 25.0
139+
*/
140+
void registerForDirectUpcall(AccessCondition condition, MethodHandle target, Object desc, Object... options);
141+
}

0 commit comments

Comments
 (0)