archive-gh-me/jerryscript
1
0
Fork 0
mirror of https://github.com/jerryscript-project/jerryscript.git synced 2025-12-15 16:29:21 +00:00
Code Issues Projects Releases Wiki Activity

Improve documentation on native pointer API methods (#3191)

Browse Source 
Added extra notes on the native pointer API usages to clarify
when the free callback function is invoked. Also added a note
for the free callback typedef to inform users to not call API methods
in the callback.

JerryScript-DCO-1.0-Signed-off-by: Peter Gal pgal.u-szeged@partner.samsung.com
This commit is contained in:
Péter Gál 2019-10-04 16:57:16 +02:00 committed by Dániel Bátyai
parent e54666b448
commit 3e23a3b62f
1 changed files with 17 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
docs/02.API-REFERENCE.md
View File

@ -441,6 +441,9 @@ typedef jerry_value_t (*jerry_external_handler_t) (const jerry_value_t function_
Native free callback of an object. It is used in `jerry_object_native_info_t` and for external Array buffers.
*Note*:
- This callback method **must not** call any JerryScript API methods.
**Prototype**
```c
@ -5542,7 +5545,8 @@ jerry_set_prototype (const jerry_value_t obj_val,
**Summary**
Get native pointer by the given type information.
The pointer and the type information are previously associated with the object by jerry_set_object_native_pointer.
The pointer and the type information are previously associated with the object by
[jerry_set_object_native_pointer](#jerry_set_object_native_pointer).
*Note*: `out_native_pointer_p` can be NULL, and it means the
caller doesn't want to get the native_pointer.
@ -5749,15 +5753,15 @@ main (void)
**Summary**
Set native pointer and an optional type information for the specified object.
You can get them by calling jerry_get_object_native_pointer later.
You can get them by calling [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) later.
*Note*: If native pointer was already set for the object, its value is updated.
*Note*: If a non-NULL free callback is specified in the native type information,
it will be called by the garbage collector when the object is freed.
This callback **must not** invoke API functions.
The type info always overwrites the previous value, so passing
a NULL value deletes the current type info.
*Notes*:
- If a native pointer was already set for the object with the same type information, its value is updated.
- If a non-NULL free callback is specified in the native type information,
it will be called by the garbage collector when the object is freed.
- If the object is only referenced via the "global" object (or one of it's "child"),
the free callback will be invoked during the execution of `jerry_cleanup`.
- The free callback **must not** invoke API functions.
**Prototype**
@ -5792,10 +5796,12 @@ best-practice example.
**Summary**
Delete the native pointer of the specified object associated with the given native type info.
You can get them by calling jerry_get_object_native_pointer later.
*Note*:
*Notes*:
- If the specified object has no matching native pointer for the given native type info the operation has no effect.
- The method does not invoke the free callback specified in the type info.
If the native pointer should be freed then one must get the native pointer first and invoke the free callback manually
before calling this method.
- This operation cannot throw an exception.
**Prototype**