Add an API to traverse objects by their associated native data (#2236)

JerryScript-DCO-1.0-Signed-off-by: Gabriel Schulhof gabriel.schulhof@intel.com

1 files changed, 208 insertions, 0 deletions

diff --git a/docs/02.API-REFERENCE.md b/docs/02.API-REFERENCE.md
index 30840ae4..442bc6a9 100644
--- a/docs/02.API-REFERENCE.md
+++ b/docs/02.API-REFERENCE.md
@@ -291,6 +291,33 @@ typedef bool (*jerry_object_property_foreach_t) (const jerry_value_t property_na
                                                  void *user_data_p);
 ```
 
+## jerry_objects_foreach_t
+
+**Summary**
+
+Function type applied for each object in the engine
+
+**Prototype**
+
+```c
+typedef bool (*jerry_objects_foreach_t) (const jerry_value_t object,
+                                         void *user_data_p);
+```
+
+## jerry_objects_foreach_by_native_info_t
+
+**Summary**
+
+Function type applied for each matching object in the engine
+
+**Prototype**
+
+```c
+typedef bool (*jerry_objects_foreach_by_native_info_t) (const jerry_value_t object,
+                                                        void *object_data_p,
+                                                        void *user_data_p);
+```
+
 ## jerry_vm_exec_stop_callback_t
 
 **Summary**
@@ -4564,6 +4591,187 @@ bool foreach_function (const jerry_value_t prop_name,
 
 - [jerry_object_property_foreach_t](#jerry_object_property_foreach_t)
 
+## jerry_objects_foreach
+
+**Summary**
+
+Iterate over objects.
+
+*Note*: Values obtained in `foreach_p` must be retained using [jerry_acquire_value](#jerry_acquire_value).
+
+**Prototype**
+
+```c
+bool jerry_objects_foreach (jerry_objects_foreach_t foreach_p,
+                            void *user_data_p);
+```
+
+- `foreach_p` - function that will be invoked for each object.
+- `user_data_p` - User data to pass to the function.
+- 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
+{
+  jerry_value_t property_name;
+  jerry_value_t result;
+} find_my_object_info_t;
+
+/*
+ * Find the first object with the given property.
+ */
+static bool
+find_my_object(const jerry_value_t candidate,
+               void *user_data_p)
+{
+  find_my_object_info_t *info_p = (find_my_object_info_t *) user_data_p;
+  jerry_value_t has_property = jerry_object_has_property (candidate, info_p->property_name);
+  bool keep_searching = (jerry_value_has_error_flag (has_property) || !jerry_get_boolean_value ());
+  if (!keep_searching)
+  {
+    /* We found it, so we acquire the value and record it. */
+    info_p->result = jerry_acquire_value (candidate);
+  }
+  jerry_release_value (has_property);
+  return keep_searching;
+} /* find_my_object */
+
+{
+  find_my_object_info_t search_info =
+  {
+    .property_name = jerry_create_string ("desired_property")
+  };
+
+  if (jerry_object_foreach (find_my_object, &search_info))
+  {
+    /* The search was successful. Do something useful with search_info.result. */
+    ...
+
+    /* Release the found object after we're done using it. */
+    jerry_release_value (search_info.result);
+  }
+  else
+  {
+    /* The search has failed. */
+  }
+
+  jerry_release_value (search_info.desired_property);
+}
+```
+**See also**
+
+- [jerry_objects_foreach_t](#jerry_objects_foreach_t)
+
+## jerry_objects_foreach_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_objects_foreach_by_native_info (const jerry_object_native_info_t *native_info_p,
+                                           jerry_objects_foreach_by_native_info_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
+} /* native_freecb */
+
+// 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 */
+...
+{
+  find_object_data_t find_data =
+  {
+    .match_data = native_obj
+  };
+
+  if (jerry_objects_foreach_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)
+- [jerry_objects_foreach](#jerry_objects_foreach)
+
 
 # Input validator functions