Skip to content

Improve documentation on native pointer API methods #3191

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 4, 2019
Merged

Improve documentation on native pointer API methods #3191

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 17 additions & 11 deletions docs/02.API-REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

*Note*: If native pointer was already set for the object, its value is updated.
You can get them by calling [jerry_get_object_native_pointer](#jerry_get_object_native_pointer) later.

*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**

Expand Down Expand Up @@ -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**
Expand Down