Rework external string free operation (#4690)
JerryScript-DCO-1.0-Signed-off-by: Zoltan Herczeg zherczeg.u-szeged@partner.samsung.com
This commit is contained in:
Zoltan Herczeg
+108
-11
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user