Add annotation Critical

README.md

@@ -55,9 +55,12 @@ interface CGLFW {
     /**
      * Fixed size array.
      * Note: this method doesn't exist in GLFW
+     * <p>
+     * You can mark methods with Critical
      *
      * @param arr The array
      */
+    @Critical(allowHeapAccess = true)
     void fixedSizeArray(@FixedSize(2) int[] arr);
 
     /**
@@ -97,6 +100,7 @@ class Main {
         double time = GLFW.getTime();
         GLFW.fixedSizeArray(new int[]{4, 2});
         MemorySegment windowHandle = /*...*/createWindow();
+        // MemoryStack is a placeholder type
         try (MemoryStack stack = /*...*/stackPush()) {
             MemorySegment bufX1 = stack.callocInt(1);
             MemorySegment bufY1 = stack.callocInt(1);

demo/src/main/java/overrun/marshal/test/CDowncallTest.java

@@ -112,6 +112,12 @@ interface CDowncallTest {
     @Overload
     void testMixArrSeg(MemorySegment segment, @Ref int[] arr);
 
+    @Critical(allowHeapAccess = true)
+    void testCriticalTrue();
+
+    @Critical(allowHeapAccess = false)
+    void testCriticalFalse();
+
     /**
      * This is a test that tests all features.
      *

src/main/java/overrun/marshal/Critical.java

@@ -0,0 +1,41 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2023 Overrun Organization
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ */
+
+package overrun.marshal;
+
+import java.lang.annotation.*;
+
+/**
+ * Marks a method that invokes a <em>critical</em> function.
+ * <h2>Example</h2>
+ * <pre>{@code
+ * @Critical(allowHeapAccess = false)
+ * void criticalFunction();
+ * }</pre>
+ *
+ * @author squid233
+ * @see java.lang.foreign.Linker.Option#critical(boolean) Linker.Option.critical
+ * @since 0.1.0
+ */
+@Documented
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.SOURCE)
+public @interface Critical {
+    /**
+     * {@return whether the linked function should allow access to the Java heap}
+     */
+    boolean allowHeapAccess();
+}

src/main/java/overrun/marshal/DowncallProcessor.java

@@ -102,6 +102,7 @@ private void writeFile(
         file.addImports(
             BoolHelper.class,
             Checks.class,
+            Critical.class,
             Default.class,
             FixedSize.class,
             Ref.class,
@@ -154,19 +155,26 @@ private void writeFile(
                     final boolean shouldStoreResult = notVoid &&
                                                       parameters.stream().anyMatch(p -> p.getAnnotation(Ref.class) != null);
                     final Access access = e.getAnnotation(Access.class);
+                    final Critical critical = e.getAnnotation(Critical.class);
                     final Custom custom = e.getAnnotation(Custom.class);
                     final Default defaultAnnotation = e.getAnnotation(Default.class);
                     final boolean isDefaulted = defaultAnnotation != null;
 
                     methodSpec.setDocument(getDocument(e));
                     methodSpec.setStatic(true);
+
+                    if (critical != null) {
+                        methodSpec.addAnnotation(new AnnotationSpec(Critical.class)
+                            .addArgument("allowHeapAccess", getConstExp(critical.allowHeapAccess())));
+                    }
                     if (isDefaulted) {
                         methodSpec.addAnnotation(new AnnotationSpec(Default.class).also(annotationSpec -> {
                             if (!defaultAnnotation.value().isBlank()) {
                                 annotationSpec.addArgument("value", getConstExp(defaultAnnotation.value()));
                             }
                         }));
                     }
+
                     if (access != null) {
                         methodSpec.setAccessModifier(access.value());
                     }
@@ -502,6 +510,7 @@ private void addMethodHandles(TypeElement type, List<ExecutableElement> methods,
             return e2;
         }, LinkedHashMap::new)).forEach((k, v) -> {
             final TypeMirror returnType = v.getReturnType();
+            final Critical critical = v.getAnnotation(Critical.class);
             final boolean defaulted = v.getAnnotation(Default.class) != null;
             classSpec.addField(new VariableStatement(MethodHandle.class, k,
                 new InvokeSpec(new InvokeSpec(
@@ -516,7 +525,12 @@ private void addMethodHandles(TypeElement type, List<ExecutableElement> methods,
                                 invokeSpec.addArgument(toValueLayout(returnType));
                             }
                             v.getParameters().forEach(e -> invokeSpec.addArgument(toValueLayout(e.asType())));
-                        })))), defaulted ? "orElse" : "orElseThrow").also(invokeSpec -> {
+                        })).also(invokeSpec -> {
+                            if (critical != null) {
+                                invokeSpec.addArgument(new InvokeSpec(Spec.accessSpec(Linker.class, Linker.Option.class), "critical")
+                                    .addArgument(getConstExp(critical.allowHeapAccess())));
+                            }
+                        }))), defaulted ? "orElse" : "orElseThrow").also(invokeSpec -> {
                     if (defaulted) {
                         invokeSpec.addArgument("null");
                     }

src/main/java/overrun/marshal/gen/Spec.java

@@ -56,6 +56,17 @@ static Spec accessSpec(Class<?> object, String member) {
         return literal(object.getSimpleName() + '.' + member);
     }
 
+    /**
+     * Create access spec
+     *
+     * @param object object
+     * @param member member
+     * @return spec
+     */
+    static Spec accessSpec(Class<?> object, Class<?> member) {
+        return literal(object.getSimpleName() + '.' + member.getSimpleName());
+    }
+
     /**
      * Create access spec
      *