Add an API to traverse objects by their associated native data

JerryScript-DCO-1.0-Signed-off-by: Gabriel Schulhof [email protected]

Author: Gabriel Schulhof

docs/02.API-REFERENCE.md

@@ -290,6 +290,20 @@ typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_na
                                                  void *user_data_p);
 ```
 
+## jerry_native_info_foreach_t
+
+**Summary**
+
+Function type applied for each matching object in the engine
+
+**Prototype**
+
+```c
+typedef bool (*jerry_native_info_foreach_t) (const jerry_value_t object,
+                                             void *object_data_p,
+                                             void *user_data_p);
+```
+
 ## jerry_vm_exec_stop_callback_t
 
 **Summary**
@@ -4564,6 +4578,112 @@ bool foreach_function (const jerry_value_t prop_name,
 - [jerry_object_property_foreach_t](#jerry_object_property_foreach_t)
 
 
+## jerry_traverse_objects_by_native_info
+
+**Summary**
+
+Iterate over objects matching a certain native data type.
+
+*Note*: Values obtained in `foreach_p` must be retained using [jerry_acquire_value](#jerry_acquire_value).
+
+**Prototype**
+
+```c
+bool jerry_traverse_objects_by_native_info (const jerry_object_native_info_t *native_info_p,
+                                            jerry_native_info_foreach_t foreach_p,
+                                            void *user_data_p);
+```
+
+- `native_info_p` - native pointer's type infomation.
+- return value
+  - `true`, if the search function terminated the traversal by returning `false`
+  - `false`, if the end of the list of objects was reached
+
+**Example**
+
+```c
+typedef struct
+{
+  int foo;
+  bool bar;
+} native_obj_t;
+
+typedef struct
+{
+  jerry_value_t found_object;
+  void *match_data_p;
+} find_object_data_t;
+
+static void native_freecb (void *native_p)
+{
+  ... // free the native pointer
+}
+
+// NOTE: The address (!) of type_info acts as a way to uniquely "identify" the
+// C type `native_obj_t *`.
+static const jerry_object_native_info_t native_obj_type_info =
+{
+  .free_cb = native_freecb
+};
+
+// Function creating JS object that is "backed" by a native_obj_t *:
+{
+  ...
+
+  // construct object and native_set value:
+  jerry_value_t object = ...;
+  native_obj_t *native_obj_p = malloc (sizeof (*native_obj_p));
+  jerry_set_object_native_pointer (object, native_obj_p, &native_obj_type_info);
+
+  ...
+}
+
+// Native method that retrieves the JavaScript object by way of its native data:
+static bool find_object (const jerry_value_t candidate, void *data_p, void *user_data_p)
+{
+  find_object_data_t *find_data_p = (find_object_data_t *) user_data_p;
+
+  if (find_data_p->match_data_p == data_p)
+  {
+    // If the object was found, acquire it and store it in the user data.
+    find_data_p->found_object = jerry_acquire_value (candidate);
+
+    // Stop traversing over the objects.
+    return false;
+  }
+
+  // Indicate that the object was not found, so traversal must continue.
+  return true;
+}
+...
+{
+  find_object_data_t find_data =
+  {
+    .match_data = native_obj
+  };
+
+  if (jerry_traverse_objects_by_native_info (&native_obj_type_info, find_object, &find_data))
+  {
+    // The object was found and is now stored in find_data.found_object. After using it, it must be released.
+    ...
+    jerry_release_value (find_data.found_object);
+  }
+  else
+  {
+    // The object was not found.
+  }
+  ...
+}
+```
+
+**See also**
+
+- [jerry_create_object](#jerry_create_object)
+- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
+- [jerry_get_object_native_pointer](#jerry_get_object_native_pointer)
+- [jerry_object_native_info_t](#jerry_object_native_info_t)
+
+
 # Input validator functions
 
 ## jerry_is_valid_utf8_string

jerry-core/api/jerry.c

@@ -2463,6 +2463,45 @@ jerry_set_object_native_handle (const jerry_value_t obj_val, /**< object to set
   }
 } /* jerry_set_object_native_handle */
 
+/**
+ * Traverse objects having a given native type info.
+ *
+ * @return true - traversal was interrupted by the callback.
+ *         false - otherwise - traversal visited all objects.
+ */
+bool
+jerry_traverse_objects_by_native_info (const jerry_object_native_info_t *native_info_p,
+                                       jerry_native_info_foreach_t foreach_p,
+                                       void *user_data_p)
+{
+  jerry_assert_api_available ();
+
+  ecma_object_t *iter_p;
+  ecma_native_pointer_t *native_pointer_p;
+
+  JERRY_ASSERT (native_info_p != NULL);
+  JERRY_ASSERT (foreach_p != NULL);
+
+  for (iter_p = JERRY_CONTEXT (ecma_gc_objects_p);
+       iter_p != NULL;
+       iter_p = ECMA_GET_POINTER (ecma_object_t, iter_p->gc_next_cp))
+  {
+    if (!ecma_is_lexical_environment (iter_p))
+    {
+      native_pointer_p = ecma_get_native_pointer_value (iter_p, LIT_INTERNAL_MAGIC_STRING_NATIVE_POINTER);
+      if (native_pointer_p != NULL
+          && ((const jerry_object_native_info_t *) native_pointer_p->u.info_p) == native_info_p
+          && !foreach_p (ecma_make_object_value (iter_p),
+                         native_pointer_p->data_p,
+                         user_data_p))
+      {
+        return true;
+      }
+    }
+  }
+  return false;
+} /* jerry_traverse_objects_by_native_info */
+
 /**
  * Get native pointer and its type information, associated with specified object.
  *

jerry-core/include/jerryscript-core.h

@@ -211,6 +211,13 @@ typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_na
                                                  const jerry_value_t property_value,
                                                  void *user_data_p);
 
+/**
+ * Function type applied for each matching object in the engine.
+ */
+typedef bool (*jerry_native_info_foreach_t) (const jerry_value_t object,
+                                             void *object_data_p,
+                                             void *user_data_p);
+
 /**
  * User context item manager
  */
@@ -439,6 +446,9 @@ void jerry_set_object_native_handle (const jerry_value_t obj_val, uintptr_t hand
 bool jerry_get_object_native_pointer (const jerry_value_t obj_val,
                                       void **out_native_pointer_p,
                                       const jerry_object_native_info_t **out_pointer_info_p);
+bool jerry_traverse_objects_by_native_info (const jerry_object_native_info_t *native_info_p,
+                                            jerry_native_info_foreach_t foreach_p,
+                                            void *user_data_p);
 void jerry_set_object_native_pointer (const jerry_value_t obj_val,
                                       void *native_pointer_p,
                                       const jerry_object_native_info_t *native_info_p);

tests/unit-core/test-weak-reference.c

@@ -0,0 +1,85 @@
+/* Copyright JS Foundation and other contributors, http://js.foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "jerryscript.h"
+#include "test-common.h"
+
+static int test_data = 1;
+
+static void free_test_data (void *data)
+{
+  TEST_ASSERT ((int *) data == &test_data);
+} /* free_test_data */
+
+static const jerry_object_native_info_t test_info =
+{
+  .free_cb = free_test_data
+};
+
+static const char *strict_equal_source = "var x = function(a, b) {return a === b;}; x";
+
+static bool
+find_test_object (const jerry_value_t candidate,
+                  void *object_data,
+                  void *context)
+{
+  if (object_data == &test_data)
+  {
+    *((jerry_value_t *) context) = jerry_acquire_value (candidate);
+    return false;
+  }
+  return true;
+} /* find_test_object */
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  /* Render strict-equal as a function. */
+  jerry_value_t parse_result = jerry_parse ((jerry_char_t *) strict_equal_source, strlen (strict_equal_source), true);
+  TEST_ASSERT (!jerry_value_has_error_flag (parse_result));
+  jerry_value_t strict_equal = jerry_run (parse_result);
+  TEST_ASSERT (!jerry_value_has_error_flag (strict_equal));
+  jerry_release_value (parse_result);
+
+  /* Create an object and associate some native data with it. */
+  jerry_value_t object = jerry_create_object ();
+  jerry_set_object_native_pointer (object, &test_data, &test_info);
+
+  /* Retrieve the object by its native pointer. */
+
+  jerry_value_t found_object;
+  TEST_ASSERT (jerry_traverse_objects_by_native_info (&test_info, find_test_object, &found_object));
+  jerry_value_t args[2] = {object, found_object};
+
+  /* Assert that the correct object was retrieved. */
+  jerry_value_t undefined = jerry_create_undefined ();
+  jerry_value_t strict_equal_result = jerry_call_function (strict_equal, undefined, args, 2);
+  jerry_release_value (undefined);
+  TEST_ASSERT (jerry_value_is_boolean (strict_equal_result) && jerry_get_boolean_value (strict_equal_result));
+  jerry_release_value (strict_equal_result);
+  jerry_release_value (found_object);
+  jerry_release_value (object);
+  jerry_release_value (strict_equal);
+
+  /* Collect garbage. */
+  jerry_gc ();
+
+  /* Attempt to retrieve the object by its native pointer again. */
+  TEST_ASSERT (!jerry_traverse_objects_by_native_info (&test_info, find_test_object, &found_object));
+
+  jerry_cleanup ();
+} /* main */