feat: add WrenValue handle API for persistent object references outside VM

Introduce WrenValue type and wrenGetArgumentValue/wrenReleaseValue functions to allow C code to hold GC-safe references to Wren objects across foreign calls. Implement doubly-linked list management in VM struct, mark value handles during garbage collection, and add assertion in wrenFreeVM to detect unreleased values. Update test infrastructure with new get_value test case and rename existing test binding functions to camelCase convention.

test/api/get_value/get_value.c

@@ -0,0 +1,24 @@
+#include <string.h>
+
+#include "get_value.h"
+
+static WrenValue* value;
+
+static void setValue(WrenVM* vm)
+{
+  value = wrenGetArgumentValue(vm, 1);
+}
+
+static void getValue(WrenVM* vm)
+{
+  wrenReturnValue(vm, value);
+  wrenReleaseValue(vm, value);
+}
+
+WrenForeignMethodFn getValueBindForeign(const char* signature)
+{
+  if (strcmp(signature, "static Api.value=(_)") == 0) return setValue;
+  if (strcmp(signature, "static Api.value") == 0) return getValue;
+
+  return NULL;
+}

test/api/get_value/get_value.h

@@ -0,0 +1,3 @@
+#include "wren.h"
+
+WrenForeignMethodFn getValueBindForeign(const char* signature);

test/api/get_value/get_value.wren

@@ -0,0 +1,14 @@
+class Api {
+  foreign static value=(value)
+  foreign static value
+}
+
+Api.value = ["list", "of", "strings"]
+
+// Do some stuff to trigger a GC (at least when GC stress testing enabled).
+var s = "string"
+for (i in 1...10) {
+  s = s + " more"
+}
+
+IO.print(Api.value) // expect: [list, of, strings]

test/api/main.c

@@ -5,12 +5,13 @@
 #include "vm.h"
 #include "wren.h"
 
+#include "get_value/get_value.h"
 #include "return_bool/return_bool.h"
 #include "return_double/return_double.h"
 #include "return_null/return_null.h"
 
-#define REGISTER_TEST(name) \
-  if (strcmp(testName, #name) == 0) return name##BindForeign(fullName)
+#define REGISTER_TEST(name, camelCase) \
+  if (strcmp(testName, #name) == 0) return camelCase##BindForeign(fullName)
 
 // The name of the currently executing API test.
 const char* testName;
@@ -30,9 +31,10 @@ static WrenForeignMethodFn bindForeign(
   strcat(fullName, ".");
   strcat(fullName, signature);
 
-  REGISTER_TEST(return_bool);
-  REGISTER_TEST(return_double);
-  REGISTER_TEST(return_null);
+  REGISTER_TEST(get_value, getValue);
+  REGISTER_TEST(return_bool, returnBool);
+  REGISTER_TEST(return_double, returnDouble);
+  REGISTER_TEST(return_null, returnNull);
 
   fprintf(stderr,
       "Unknown foreign method '%s' for test '%s'\n", fullName, testName);

test/api/return_bool/return_bool.c

@@ -12,7 +12,7 @@ static void returnFalse(WrenVM* vm)
   wrenReturnBool(vm, false);
 }
 
-WrenForeignMethodFn return_boolBindForeign(const char* signature)
+WrenForeignMethodFn returnBoolBindForeign(const char* signature)
 {
   if (strcmp(signature, "static Api.returnTrue") == 0) return returnTrue;
   if (strcmp(signature, "static Api.returnFalse") == 0) return returnFalse;

test/api/return_bool/return_bool.h

@@ -1,3 +1,3 @@
 #include "wren.h"
 
-WrenForeignMethodFn return_boolBindForeign(const char* signature);
+WrenForeignMethodFn returnBoolBindForeign(const char* signature);

test/api/return_double/return_double.c

@@ -12,7 +12,7 @@ static void returnFloat(WrenVM* vm)
   wrenReturnDouble(vm, 123.456);
 }
 
-WrenForeignMethodFn return_doubleBindForeign(const char* signature)
+WrenForeignMethodFn returnDoubleBindForeign(const char* signature)
 {
   if (strcmp(signature, "static Api.returnInt") == 0) return returnInt;
   if (strcmp(signature, "static Api.returnFloat") == 0) return returnFloat;

test/api/return_double/return_double.h

@@ -1,3 +1,3 @@
 #include "wren.h"
 
-WrenForeignMethodFn return_doubleBindForeign(const char* signature);
+WrenForeignMethodFn returnDoubleBindForeign(const char* signature);

test/api/return_null/return_null.c

@@ -7,7 +7,7 @@ static void implicitNull(WrenVM* vm)
   // Do nothing.
 }
 
-WrenForeignMethodFn return_nullBindForeign(const char* signature)
+WrenForeignMethodFn returnNullBindForeign(const char* signature)
 {
   if (strcmp(signature, "static Api.implicitNull") == 0) return implicitNull;
 

test/api/return_null/return_null.h

@@ -1,3 +1,3 @@
 #include "wren.h"
 
-WrenForeignMethodFn return_nullBindForeign(const char* signature);
+WrenForeignMethodFn returnNullBindForeign(const char* signature);