Add reference support for native pointers. (#4615)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
2021-04-19 14:47:17 +02:00
parent cc1a263657
commit ec3ed65b56
23 changed files with 681 additions and 150 deletions
@@ -902,33 +902,56 @@ typedef bool (*jerry_backtrace_callback_t) (jerry_backtrace_frame_t *frame_p, vo

 **Summary**

-The type information of the native pointer.
-It includes the free callback that will be called when associated JavaScript object is garbage collected. It can be left NULL in case it is not needed.
+Type information for native pointers. Since each native pointer has a type information,
+multiple native pointers can be assigned to an object, and these can be updated or
+deleted independently.

-Typically, one would create a `static const jerry_object_native_info_t` for
-each distinct C type for which a pointer is used with
-`jerry_set_object_native_pointer ()` and `jerry_get_object_native_pointer ()`.
-This way, each `const jerry_object_native_info_t *` pointer address value itself
-uniquely identifies the C type of the native pointer.
+The type information has a free callback, which is called when the object is freed
+by the garbage collector. If the callback is NULL, the application is not notified
+about the destruction of the object.

-See [jerry_get_object_native_pointer](#jerry_get_object_native_pointer)
-for a best-practice code example.
+The buffer pointed by the native pointer can have a fixed number of jerry values,
+which refer to other values as long as the object is alive. The starting byte
+offset and the number of these values are specified by `offset_of_references` and
+`number_of_references` fields respectively. Before a buffer is attached to an
+object by [jerry_set_object_native_pointer](#jerry_set_object_native_pointer),
+the values must be initialized to undefined by
+[jerry_native_pointer_init_references](#jerry_native_pointer_init_references).
+When a buffer is no longer attached to any object, the
+[jerry_native_pointer_release_references](#jerry_native_pointer_release_references)
+must be called to release the values. A single buffer can be attached to any
+number of living objects. When a buffer is currently attached to at least
+one object, the references can be updated by
+[jerry_native_pointer_set_reference](#jerry_native_pointer_set_reference).
+However, if the buffer is no longer attached to an object, the finalize function
+must be called even if the buffer is reattached to another object later. In this
+case, calling the init function after the finalization is optional, because the
+finalize function also initializes all values to undefined.

 **Prototype**

 ```c
 typedef struct
 {
-  jerry_object_native_free_callback_t free_cb;
+  jerry_object_native_free_callback_t free_cb; /**< the free callback of the native pointer */
+  uint16_t number_of_references; /**< the number of value references which are marked by the garbage collector */
+  uint16_t offset_of_references; /**< byte offset indicating the start offset of value
+                                  *   references in the user allocated buffer */
 } jerry_object_native_info_t;
 ```

 *New in version 2.0*.

+*Changed in version [[NEXT_RELEASE]]*: Added `number_of_references`, and `offset_of_references` fields.
+
 **See also**

 - [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
 - [jerry_get_object_native_pointer](#jerry_get_object_native_pointer)
+- [jerry_delete_object_native_pointer](#jerry_delete_object_native_pointer)
+- [jerry_native_pointer_init_references](#jerry_native_pointer_init_references)
+- [jerry_native_pointer_release_references](#jerry_native_pointer_release_references)
+- [jerry_native_pointer_set_reference](#jerry_native_pointer_set_reference)

 ## jerry_object_property_foreach_t

@@ -9021,6 +9044,171 @@ best-practice example.
 - [jerry_object_native_info_t](#jerry_object_native_info_t)


+## jerry_native_pointer_init_references
+
+**Summary**
+
+Initialize the references stored in a buffer pointed by a native pointer.
+The references are initialized to undefined. This function must be called
+before the buffer is attached to an object by
+[jerry_set_object_native_pointer](#jerry_set_object_native_pointer).
+
+*Note*:
+  - The description of [jerry_object_native_info_t](#jerry_object_native_info_t)
+    provides detailed information about these references.
+
+**Prototype**
+
+```c
+void
+jerry_native_pointer_init_references (void *native_pointer_p,
+                                      const jerry_object_native_info_t *native_info_p);
+```
+
+- `native_pointer_p` - a valid non-NULL pointer to a native buffer.
+- `native_info_p` - native pointer's type information.
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include <stdlib.h>
+#include "jerryscript.h"
+
+typedef struct
+{
+  uint32_t user_data;
+  jerry_value_t a;
+  jerry_value_t b;
+  uint32_t user_other_data;
+} user_buffer_t;
+
+static void
+native_references_free_callback (void *native_p, /**< native pointer */
+                                 jerry_object_native_info_t *info_p) /**< native info */
+{
+  /* References must be finalized when a buffer is no longer attached. */
+  jerry_native_pointer_release_references (native_p, info_p);
+  free (native_p);
+} /* native_references_free_callback */
+
+static const jerry_object_native_info_t native_info =
+{
+  .free_cb = native_references_free_callback,
+  .number_of_references = 2,
+  .offset_of_references = offsetof(user_buffer_t, a),
+};
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_value_t object_value = jerry_create_object ();
+
+  user_buffer_t *buffer_p = (user_buffer_t *) malloc (sizeof (user_buffer_t));
+
+  /* References must be initialized before a buffer is attached. */
+  jerry_native_pointer_init_references ((void *) buffer_p, &native_info);
+
+  jerry_set_object_native_pointer (object_value, (void *) buffer_p, &native_info);
+
+  /* References can be modified after the buffer is attached.
+   * This example sets a self reference. */
+  jerry_native_pointer_set_reference (&buffer_p->a, object_value);
+
+  jerry_release_value (object_value);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
+- [jerry_native_pointer_release_references](#jerry_native_pointer_release_references)
+- [jerry_native_pointer_set_reference](#jerry_native_pointer_set_reference)
+
+## jerry_native_pointer_release_references
+
+**Summary**
+
+Release the value references stored in a buffer pointed by a native pointer.
+This function must be called after a buffer is no longer attached to any
+object, even if the buffer is attached to another object again. This
+function also initializes the values to undefined, so calling
+[jerry_native_pointer_init_references](#jerry_native_pointer_init_references)
+is optional before the buffer is attached again.
+
+*Note*:
+  - The description of [jerry_object_native_info_t](#jerry_object_native_info_t)
+    provides detailed information about these references.
+
+**Prototype**
+
+```c
+void
+jerry_native_pointer_release_references (void *native_pointer_p,
+                                         const jerry_object_native_info_t *native_info_p);
+```
+
+- `native_pointer_p` - a valid non-NULL pointer to a native buffer.
+- `native_info_p` - native pointer's type information.
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+See the example of [jerry_native_pointer_init_references](#jerry_native_pointer_init_references).
+
+**See also**
+
+- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
+- [jerry_native_pointer_init_references](#jerry_native_pointer_init_references)
+- [jerry_native_pointer_set_reference](#jerry_native_pointer_set_reference)
+
+
+## jerry_native_pointer_set_reference
+
+**Summary**
+
+Updates a value reference inside the area specified by the `number_of_references` and
+`offset_of_references` fields in its corresponding
+[jerry_object_native_info_t](#jerry_object_native_info_t) data. The area must be
+part of a buffer which is currently assigned to an object.
+
+*Note*:
+  - The description of [jerry_object_native_info_t](#jerry_object_native_info_t)
+    provides detailed information about these references.
+
+**Prototype**
+
+```c
+void
+jerry_native_pointer_set_reference (jerry_value_t *reference_p,
+                                    jerry_value_t value)
+```
+
+- `reference_p` - a valid non-NULL pointer to a reference in a native buffer.
+- `value` - new value of the reference.
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+See the example of [jerry_native_pointer_init_references](#jerry_native_pointer_init_references).
+
+**See also**
+
+- [jerry_set_object_native_pointer](#jerry_set_object_native_pointer)
+- [jerry_native_pointer_init_references](#jerry_native_pointer_init_references)
+- [jerry_native_pointer_release_references](#jerry_native_pointer_release_references)
+
+
 ## jerry_object_get_property_names

 **Summary**