Rework external string free operation (#4690)

JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
2021-08-17 08:31:30 +02:00
parent 74e5ccd434
commit e7ffb70ae0
9 changed files with 187 additions and 44 deletions
@@ -769,6 +769,34 @@ typedef void (*jerry_object_native_free_callback_t) (void *native_p, struct jerr

 - [jerry_object_native_info_t](#jerry_object_native_info_t)

+## jerry_external_string_free_callback_t
+
+**Summary**
+
+Free callback for external strings. See
+[jerry_string_set_external_string_free_callback](#jerry_string_set_external_string_free_callback)
+for more information.
+
+**Prototype**
+
+```c
+typedef void (*jerry_external_string_free_callback_t) (jerry_char_t *string_p,
+                                                       jerry_size_t string_size,
+                                                       void *user_p);
+```
+
+- `string_p` - extrenal string pointer
+- `string_size` - size of external string
+- `user_p` - pointer passed when the external string is created
+
+*New in version [[NEXT_RELEASE]]*.
+
+**See also**
+
+- [jerry_string_set_external_string_free_callback](#jerry_string_set_external_string_free_callback)
+- [jerry_create_external_string](#jerry_create_external_string)
+- [jerry_create_external_string_sz](#jerry_create_external_string_sz)
+
 ## jerry_error_object_created_callback_t

 **Summary**
@@ -4195,6 +4223,70 @@ jerry_substring_to_utf8_char_buffer (const jerry_value_t value,
 - [jerry_is_valid_utf8_string](#jerry_is_valid_utf8_string)


+# jerry_string_set_external_string_free_callback
+
+**Summary**
+
+Sets the global callback which is called when the string data of an external
+string is no longer used. It is recommended to set this function before the
+first external string is created.
+
+*Note*:
+  - When the callback is NULL, no function is called when an external string is freed.
+  - In some cases (e.g. when the string is also a magic string registered by
+    [jerry_register_magic_strings](#jerry_register_magic_strings)), the callback
+    is called when the string is created, not when it is released.
+
+**Prototype**
+
+```c
+void jerry_string_set_external_string_free_callback (jerry_external_string_free_callback_t callback_p);
+```
+
+- `callback_p` - callback which is called when an external string is freed.
+
+*New in version [[NEXT_RELEASE]]*.
+
+**Example**
+
+[doctest]: # ()
+
+```c
+#include "jerryscript.h"
+#include <stdio.h>
+
+static void
+external_string_free_callback (jerry_char_t *string_p, /**< string pointer */
+                               jerry_size_t string_size, /**< size of the string */
+                               void *user_p) /**< user pointer */
+{
+  printf ("External string is freed!\n");
+}
+
+int
+main (void)
+{
+  jerry_init (JERRY_INIT_EMPTY);
+
+  jerry_string_set_external_string_free_callback (external_string_free_callback);
+
+  const char *string_p = "This is a long external string, should not be duplicated!";
+  jerry_value_t external_string = jerry_create_external_string ((jerry_char_t *) string_p, NULL);
+  /* The external_string_free_callback is called. */
+  jerry_release_value (external_string);
+
+  jerry_cleanup ();
+  return 0;
+}
+```
+
+**See also**
+
+- [jerry_external_string_free_callback_t](#jerry_external_string_free_callback_t)
+- [jerry_create_external_string](#jerry_create_external_string)
+- [jerry_create_external_string_sz](#jerry_create_external_string_sz)
+
+
 # Functions for array object values

 ## jerry_get_array_length
@@ -7293,24 +7385,25 @@ Create an external string from a valid CESU8 string. The string buffer passed to
 should not be modified until the free callback is called. This function can be used to avoid
 the duplication of large strings.

-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
-is no longer needed.
+*Note*:
+ - The free callback can be set by [jerry_string_set_external_string_free_callback](#jerry_string_set_external_string_free_callback)
+ - Returned value must be freed with [jerry_release_value](#jerry_release_value)
+   when it is no longer needed.

 **Prototype**

 ```c
 jerry_value_t
-jerry_create_external_string (const jerry_char_t *str_p,
-                              jerry_value_free_callback_t free_cb)
+jerry_create_external_string (const jerry_char_t *str_p, void *user_p);
 ```

 - `str_p` - non-null pointer to string
- `free_cb` - optional callback which is called right before the string is freed
+- `user_p` - user pointer passed to the callback when the string is freed
 - return value - value of the created string

 *New in version 2.4*.

-*Changed in version [[NEXT_RELEASE]]*: type of `free_cb` has been changed.
+*Changed in version [[NEXT_RELEASE]]*: `free_cb` is replaced by `user_p`.

 **Example**

@@ -7330,6 +7423,7 @@ jerry_create_external_string (const jerry_char_t *str_p,

 - [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string)
 - [jerry_create_external_string_sz](#jerry_create_external_string_sz)
+- [jerry_string_set_external_string_free_callback](#jerry_string_set_external_string_free_callback)


 ## jerry_create_external_string_sz
@@ -7340,8 +7434,10 @@ Create an external string from a valid CESU8 string. The string buffer passed to
 should not be modified until the free callback is called. This function can be used to avoid
 the duplication of large strings.

-*Note*: Returned value must be freed with [jerry_release_value](#jerry_release_value) when it
-is no longer needed.
+*Note*:
+ - The free callback can be set by [jerry_string_set_external_string_free_callback](#jerry_string_set_external_string_free_callback)
+ - Returned value must be freed with [jerry_release_value](#jerry_release_value)
+   when it is no longer needed.

 **Prototype**

@@ -7349,17 +7445,17 @@ is no longer needed.
 jerry_value_t
 jerry_create_external_string_sz (const jerry_char_t *str_p,
                                 jerry_size_t str_size,
-                                 jerry_value_free_callback_t free_cb)
+                                 void *user_p);
 ```

 - `str_p` - non-null pointer to string
 - `str_size` - size of the string
- `free_cb` - optional callback which is called right before the string is freed
+- `user_p` - user pointer passed to the callback when the string is freed
 - return value - value of the created string

 *New in version 2.4*.

-*Changed in version [[NEXT_RELEASE]]*: type of `free_cb` has been changed.
+*Changed in version [[NEXT_RELEASE]]*: `free_cb` is replaced by `user_p`.

 **Example**

@@ -7381,6 +7477,7 @@ jerry_create_external_string_sz (const jerry_char_t *str_p,

 - [jerry_is_valid_cesu8_string](#jerry_is_valid_cesu8_string)
 - [jerry_create_external_string](#jerry_create_external_string)
+- [jerry_string_set_external_string_free_callback](#jerry_string_set_external_string_free_callback)


 ## jerry_create_symbol