Print this page
enable v8plus_call to be used in any thread

@@ -557,14 +557,14 @@
 
                 /*
                  * In thread pool context -- do not call any of the
                  * following functions:
                  * v8plus_obj_hold()
-                 * v8plus_obj_rele()
+                 * v8plus_obj_rele_direct()
                  * v8plus_jsfunc_hold()
-                 * v8plus_jsfunc_rele()
-                 * v8plus_call()
+                 * 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,11 +686,13 @@
 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()`.
+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,11 +702,13 @@
 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()`.
+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,24 +721,33 @@
 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.
 
-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.
+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?