Advance the facade to the ecosystem-pin-2026-06-22a MEOS surface

codegen/src/main/java/FunctionsGenerator.java

@@ -24,6 +24,16 @@ public class FunctionsGenerator {
     // These are mapped to int in Java (JNR-FFI represents C enums as int).
     private final Set<String> enumNames = new HashSet<>();
 
+    // Struct names → SysV-AMD64 size in bytes, from the JSON "structs" section.
+    // Used to detect functions that return a struct BY VALUE.  On the SysV /
+    // AArch64 ABIs a by-value struct larger than 16 bytes is returned via memory
+    // (the "sret" convention): the caller allocates the struct and passes a hidden
+    // pointer as an implicit FIRST argument; the callee fills it and returns it in
+    // the return register.  jnr-ffi cannot bind a by-value struct return mapped to
+    // a bare Pointer (it mis-reads the return register), so for these we model the
+    // sret pointer explicitly — see generateAllInterfaces / generateStaticMethod.
+    private final Map<String, Integer> structSizes = new HashMap<>();
+
     // DateADT      → typedef int32_t  → Java int
     // Timestamp    → typedef int64_t  → Java long  (no timezone)
     // TimestampTz  → typedef int64_t  → Java long  (with timezone)
@@ -79,7 +89,25 @@ public class FunctionsGenerator {
     //   1. The interface method returns boolean
     //   2. There is a parameter whose name is in OUTPUT_RESULT_PARAMS
     //   3. That parameter's Java type is Pointer
-    private static final Set<String> OUTPUT_RESULT_PARAMS = Set.of("result");
+    //   4. That parameter's C type is a pointer (so a by-value input named
+    //      "value" — e.g. the Datum argument to contains_set_value — is never
+    //      mistaken for an out-param; only pointer out-params qualify)
+    //
+    // "value" covers the *_value_at_timestamptz accessor family, e.g.
+    //   bool tbool_value_at_timestamptz(const Temporal *, TimestampTz, bool, bool *value)
+    // uniformly for tbool/tint/tfloat/tbigint/ttext/tcbuffer/tjsonb/tnpoint, so the
+    // OO layer calls the managed 3-arg wrapper and never marshals the out-param by hand.
+    private static final Set<String> OUTPUT_RESULT_PARAMS = Set.of("result", "value");
+
+    // True when p is the output-result parameter of a boolean-returning function
+    // (the boolean signals success and the value is written into *p).  Gated on a
+    // pointer C type so a by-value input named "value" (a Datum) is not treated as
+    // an out-param.  See OUTPUT_RESULT_PARAMS.
+    private static boolean isResultOutParam(ParamDef p) {
+        return OUTPUT_RESULT_PARAMS.contains(p.name)
+                && p.javaType.equals("Pointer")
+                && p.cType != null && p.cType.contains("*");
+    }
 
     // -------------------------------------------------------------------------
     // Entry point
@@ -112,6 +140,10 @@ private void run(String inputPath, String outputPath) throws IOException {
         collectEnumNames(root);
         System.out.println("Enums collected: " + enumNames);
 
+        // 1b. Collect struct layouts so by-value struct returns can be bound
+        //     via the sret calling convention (see structSizes).
+        collectStructs(root);
+
         // 2. Parse all functions
         JsonNode functionsNode = root.get("functions");
         if (functionsNode == null || !functionsNode.isArray()) {
@@ -157,6 +189,69 @@ private void collectEnumNames(JsonNode root) {
         }
     }
 
+    /**
+     * Collects struct layouts from the JSON "structs" section and records each
+     * struct's SysV-AMD64 size.  Structs larger than 16 bytes are returned via
+     * memory (sret) when used as a by-value return type; that is the only fact
+     * the generator needs (see structSizes / parseFunctionDef).
+     */
+    private void collectStructs(JsonNode root) {
+        JsonNode structs = root.get("structs");
+        if (structs == null || !structs.isArray()) {
+            return;
+        }
+        List<String> registerReturned = new ArrayList<>();
+        for (JsonNode s : structs) {
+            JsonNode nameNode = s.get("name");
+            JsonNode fields   = s.get("fields");
+            if (nameNode == null || fields == null || !fields.isArray()) {
+                continue;
+            }
+            int off = 0, maxAlign = 1;
+            for (JsonNode f : fields) {
+                JsonNode ct = f.get("cType");
+                int sz = (ct == null) ? 8 : cFieldSize(ct.asText());
+                off = ((off + sz - 1) / sz) * sz; // align field to its own size
+                off += sz;
+                maxAlign = Math.max(maxAlign, sz);
+            }
+            int size = ((off + maxAlign - 1) / maxAlign) * maxAlign;
+            String nm = nameNode.asText();
+            structSizes.put(nm, size);
+            if (size <= 16) {
+                registerReturned.add(nm + "(" + size + "B)");
+            }
+        }
+        System.out.println("Structs collected: " + structSizes.size());
+        // No silent caps: a by-value return of a <=16B struct is register-returned
+        // (not sret) and is NOT handled by the sret path below.  Log it so the gap
+        // is visible rather than silently mis-bound.
+        if (!registerReturned.isEmpty()) {
+            System.out.println("NOTE: register-returned structs (<=16B, NOT sret-bound): "
+                    + registerReturned);
+        }
+    }
+
+    /** SysV-AMD64 size of a single C field type (pointers and 8-byte scalars = 8). */
+    private int cFieldSize(String cType) {
+        String t = cType.replace("const ", "").trim();
+        if (t.endsWith("*")) {
+            return 8;
+        }
+        return switch (t) {
+            case "double", "float8", "long", "int64", "int64_t", "uint64",
+                 "uint64_t", "size_t", "uintptr_t", "Datum",
+                 "Timestamp", "TimestampTz"           -> 8;
+            case "int", "int32", "int32_t", "uint32",
+                 "uint32_t", "float", "DateADT"       -> 4;
+            case "short", "int16", "int16_t",
+                 "uint16", "uint16_t"                 -> 2;
+            case "bool", "char", "int8", "int8_t",
+                 "uint8", "uint8_t"                   -> 1;
+            default                                   -> 8; // nested struct/pointer: conservative
+        };
+    }
+
     private FunctionDef parseFunctionDef(JsonNode fn) {
         String name = fn.get("name").asText();
 
@@ -198,7 +293,16 @@ private FunctionDef parseFunctionDef(JsonNode fn) {
             }
         }
 
-        return new FunctionDef(name, retJava, retCType, params);
+        // By-value struct return: if the return C type names a struct larger than
+        // 16 bytes, it is returned via memory (sret) and must be bound with an
+        // explicit hidden first pointer argument (see generateStaticMethod).
+        int sretStructSize = 0;
+        Integer sz = structSizes.get(retCType.replace("struct ", "").trim());
+        if (sz != null && sz > 16) {
+            sretStructSize = sz;
+        }
+
+        return new FunctionDef(name, retJava, retCType, params, sretStructSize);
     }
 
     // -------------------------------------------------------------------------
@@ -476,10 +580,17 @@ private String generateAllInterfaces(List<FunctionDef> functions, int partSize)
             sb.append("\tpublic interface MeosLibraryPart").append(letters[p]).append(" {\n\n");
             for (int i = start; i < end; i++) {
                 FunctionDef fn = functions.get(i);
+                String ifaceParams = buildInterfaceParamList(fn.params);
+                // sret return: the struct pointer is a hidden FIRST argument.
+                if (fn.sretStructSize > 0) {
+                    ifaceParams = ifaceParams.isEmpty()
+                            ? "Pointer _sret"
+                            : "Pointer _sret, " + ifaceParams;
+                }
                 sb.append("\t\t")
                         .append(fn.returnType).append(" ")
                         .append(fn.name).append("(")
-                        .append(buildInterfaceParamList(fn.params))
+                        .append(ifaceParams)
                         .append(");\n\n");
             }
             sb.append("\t}\n\n");
@@ -550,18 +661,21 @@ private String generateStaticMethod(FunctionDef fn, int partIndex) {
         //   bool*   → public static boolean fn(...) return result.getByte(0) != 0
         //   Span*   → public static Pointer fn(...) return result.getPointer(0)
         boolean isBoolResultPattern = fn.returnType.equals("boolean")
-                && fn.params.stream().anyMatch(p ->
-                OUTPUT_RESULT_PARAMS.contains(p.name)
-                        && p.javaType().equals("Pointer"));
+                && fn.params.stream().anyMatch(FunctionsGenerator::isResultOutParam);
+
+        // sret pattern: the function returns a >16B struct by value.  The wrapper
+        // allocates the struct buffer internally, passes it as the hidden first
+        // argument, and returns the filled buffer.  Callers read the struct fields
+        // off the returned Pointer (.getPointer(0), .getInt(offset), …).
+        boolean isSretStruct = fn.sretStructSize > 0;
 
         // Resolve the ResultStrategy from the C type of the result param.
         // Determines allocation size, read expression, and wrapper return type.
         // Previously hardcoded to Pointer/Long.BYTES/getPointer(0), which caused
         // a SIGSEGV at runtime for scalar result types (double*, int*, bool*…).
         ResultStrategy resultStrategy = isBoolResultPattern
                 ? fn.params.stream()
-                .filter(p -> OUTPUT_RESULT_PARAMS.contains(p.name)
-                        && p.javaType().equals("Pointer"))
+                .filter(FunctionsGenerator::isResultOutParam)
                 .findFirst()
                 .map(p -> resolveResultStrategy(p.cType))
                 .orElse(new ResultStrategy("Long.BYTES", true))
@@ -579,8 +693,7 @@ private String generateStaticMethod(FunctionDef fn, int partIndex) {
                 internalSizeParams.add(p.name);
                 continue;
             }
-            if (isBoolResultPattern && OUTPUT_RESULT_PARAMS.contains(p.name)
-                    && p.javaType().equals("Pointer")) {
+            if (isBoolResultPattern && isResultOutParam(p)) {
                 hasInternalResult = true;
                 continue; // hide from signature; allocated below
             }
@@ -610,7 +723,7 @@ private String generateStaticMethod(FunctionDef fn, int partIndex) {
 
         // --- Internal allocations ---
         // Determine if we need a Runtime (needed for any Memory.allocateDirect call).
-        boolean needsRuntime = !internalSizeParams.isEmpty() || hasInternalResult;
+        boolean needsRuntime = !internalSizeParams.isEmpty() || hasInternalResult || isSretStruct;
 
         if (isBoolResultPattern) {
             // Emit the "boolean out" sentinel variable first,
@@ -630,6 +743,12 @@ private String generateStaticMethod(FunctionDef fn, int partIndex) {
                     .append(resultStrategy.allocExpr()).append(");\n");
         }
 
+        // Allocate the hidden sret struct buffer.
+        if (isSretStruct) {
+            sb.append("\t\tPointer _sret = Memory.allocateDirect(runtime, ")
+                    .append(fn.sretStructSize).append(");\n");
+        }
+
         // Allocate hidden size_out pointer(s).
         for (String paramName : internalSizeParams) {
             sb.append("\t\tPointer ").append(paramName)
@@ -653,11 +772,14 @@ private String generateStaticMethod(FunctionDef fn, int partIndex) {
         // --- Build argument list for the interface call ---
         // Hidden params (size_out, result) are still forwarded by their local name.
         StringJoiner args = new StringJoiner(", ");
+        if (isSretStruct) {
+            args.add("_sret"); // hidden sret buffer is the first native argument
+        }
         for (ParamDef p : fn.params) {
-            if (OUTPUT_SIZE_PARAMS.contains(p.name)
-                    || (isBoolResultPattern && OUTPUT_RESULT_PARAMS.contains(p.name)
-                    && p.javaType().equals("Pointer"))) {
-                args.add(p.name); // pass locally-allocated pointer
+            if (OUTPUT_SIZE_PARAMS.contains(p.name)) {
+                args.add(p.name); // locally-allocated size_out buffer (named after the param)
+            } else if (isBoolResultPattern && isResultOutParam(p)) {
+                args.add("result"); // locally-allocated result buffer (allocated above as `result`)
             } else {
                 boolean converted = isTemporalCType(p.cType());
                 args.add(converted ? p.name + "_new" : p.name);
@@ -687,6 +809,12 @@ private String generateStaticMethod(FunctionDef fn, int partIndex) {
                 sb.append("\t\tMeosErrorHandler.checkError();\n");
                 sb.append("\t\treturn out ? result : null;\n");
             }
+        } else if (isSretStruct) {
+            // The native function fills _sret and also returns it in the return
+            // register; we keep our own buffer (known size) and return that.
+            sb.append("\t\t").append(call).append("\n");
+            sb.append("\t\tMeosErrorHandler.checkError();\n");
+            sb.append("\t\treturn _sret;\n");
         } else if (fn.returnType.equals("void")) {
             sb.append("\t\t").append(call).append("\n");
             sb.append("\t\tMeosErrorHandler.checkError();\n");
@@ -743,7 +871,10 @@ private String buildWrapperParamList(List<WrapperParam> params) {
 
     // retCType field so generateStaticMethod can decide the
     // wrapper return type independently of the interface return type.
-    private record FunctionDef(String name, String returnType, String retCType, List<ParamDef> params) {}
+    // sretStructSize > 0 marks a by-value struct return bound via the sret
+    // convention (hidden first pointer arg of that many bytes); 0 otherwise.
+    private record FunctionDef(String name, String returnType, String retCType,
+                               List<ParamDef> params, int sretStructSize) {}
 
     // Added cType field so each param's original C type is
     // available when generating conversion code in the static wrapper.

jmeos-core/pom.xml

@@ -95,9 +95,10 @@
                 <artifactId>maven-surefire-plugin</artifactId>
                 <version>3.4.0</version>
                 <configuration>
-                    <!--                    <forkCount>4</forkCount>-->
-                    <!--                    <reuseForks>true</reuseForks>-->
-                    <!--                    <argLine>-Xmx4096m -XX:MaxMetaspaceSize=512m</argLine>-->
+                    <!-- MEOS keeps process-global state: meos_initialize cannot be
+                         re-run after a meos_finalize in the same JVM. Give each test
+                         class its own fork so the native MEOS lifecycle is clean. -->
+                    <reuseForks>false</reuseForks>
                     <skipTests>false</skipTests>
                 </configuration>
             </plugin>