Print this page
enable v8plus_call to be used in any thread
*** 557,570 ****
/*
* In thread pool context -- do not call any of the
* following functions:
* v8plus_obj_hold()
! * v8plus_obj_rele()
* v8plus_jsfunc_hold()
! * v8plus_jsfunc_rele()
! * v8plus_call()
* v8plus_method_call_direct()
* v8plus_defer()
*
* If you touch anything inside op, you may need locking to
* protect against functions called in the main thread.
--- 557,570 ----
/*
* In thread pool context -- do not call any of the
* following functions:
* v8plus_obj_hold()
! * v8plus_obj_rele_direct()
* v8plus_jsfunc_hold()
! * v8plus_jsfunc_rele_direct()
! * v8plus_call_direct()
* v8plus_method_call_direct()
* v8plus_defer()
*
* If you touch anything inside op, you may need locking to
* protect against functions called in the main thread.
*** 686,696 ****
calling `v8plus_defer()`, you must call this first. Holds and releases must
be balanced. Use of the object within a thread after releasing is a bug.
### void v8plus_obj_rele(const void *op)
! Releases a hold placed by `v8plus_obj_hold()`.
### void v8plus_jsfunc_hold(v8plus_jsfunc_t f)
Places a hold on the V8 representation of the specified JavaScript function.
This is required when returning from a C function that has stashed a
--- 686,698 ----
calling `v8plus_defer()`, you must call this first. Holds and releases must
be balanced. Use of the object within a thread after releasing is a bug.
### void v8plus_obj_rele(const void *op)
! Releases a hold placed by `v8plus_obj_hold()`. This function may be called
! safely from any thread; releases from threads other than the main event loop
! are non-blocking and will occur some time in the future.
### void v8plus_jsfunc_hold(v8plus_jsfunc_t f)
Places a hold on the V8 representation of the specified JavaScript function.
This is required when returning from a C function that has stashed a
*** 700,710 ****
when you return), it is legal to reference and even to invoke such a
function without first placing an additional hold on it.
### void v8plus_jsfunc_rele(v8plus_jsfunc_t f)
! Releases a hold placed by `v8plus_jsfunc_hold()`.
### void v8plus_defer(void *op, void *ctx, worker, completion)
Enqueues work to be performed in the Node.js shared thread pool. The object
`op` and context `ctx` are passed as arguments to `worker` executing in a
--- 702,714 ----
when you return), it is legal to reference and even to invoke such a
function without first placing an additional hold on it.
### void v8plus_jsfunc_rele(v8plus_jsfunc_t f)
! Releases a hold placed by `v8plus_jsfunc_hold()`. This function may be called
! safely from any thread; releases from threads other than the main event loop
! thread are non-blocking and will occur some time in the future.
### void v8plus_defer(void *op, void *ctx, worker, completion)
Enqueues work to be performed in the Node.js shared thread pool. The object
`op` and context `ctx` are passed as arguments to `worker` executing in a
*** 717,740 ****
Calls the JavaScript function referred to by `f` with encoded arguments
`ap`. The return value is the encoded return value of the function. The
argument and return value encoding match the encodings that are used by C
functions that provide methods.
### nvlist_t *v8plus_method_call(void *op, const char *name, const nvlist_t *ap)
Calls the method named by `name` in the native object `op` with encoded
argument list `ap`. The method must exist and must be a JavaScript
function. Such functions may be attached by JavaScript code as in the event
emitter example above. The effects of using this function to call a native
method are undefined.
! As JavaScript functions must be called from the event loop thread,
! `v8plus_method_call()` contains logic to determine whether we are in the
! correct context or not. If we are running on some other thread we will
! queue the request and sleep, waiting for the event loop thread to make the
! call. In the simple case, where we are already in the correct thread, we
! make the call directly.
## FAQ
- Why?
--- 721,753 ----
Calls the JavaScript function referred to by `f` with encoded arguments
`ap`. The return value is the encoded return value of the function. The
argument and return value encoding match the encodings that are used by C
functions that provide methods.
+ As JavaScript functions must be called from the event loop thread,
+ `v8plus_call()` contains logic to determine whether we are in the
+ correct context or not. If we are running on some other thread we will
+ queue the request and sleep, waiting for the event loop thread to make the
+ call. In the simple case, where we are already in the correct thread, we
+ make the call directly.
+
+ Note that when passing JavaScript functions around as callbacks, you must use
+ first use `v8plus_jsfunc_hold()` from within the main event loop thread. Once
+ finished with the function, you may pass it to `v8plus_jsfunc_rele()` from any
+ thread to clean up.
+
### nvlist_t *v8plus_method_call(void *op, const char *name, const nvlist_t *ap)
Calls the method named by `name` in the native object `op` with encoded
argument list `ap`. The method must exist and must be a JavaScript
function. Such functions may be attached by JavaScript code as in the event
emitter example above. The effects of using this function to call a native
method are undefined.
! When called from threads other than the main event loop thread,
! `v8plus_method_call()` uses the same queue-and-block logic as described above
! in `v8plus_call()`.
## FAQ
- Why?