XXX keith II

@@ -561,11 +561,11 @@
                  * v8plus_obj_hold()
                  * v8plus_obj_rele()
                  * v8plus_jsfunc_hold()
                  * v8plus_jsfunc_rele()
                  * v8plus_call()
-                 * v8plus_method_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.
                  */

@@ -649,16 +649,15 @@
                 };
         }
         util.inherits(MyObjectWrapper, events.EventEmitter);
 
 Then, in C code, you must arrange for libuv to call a C function in the
-context of the main event loop.  How to do this depends on what type of
-asynchronous event you are waiting for; for example, the `uv_poll` mechanism
-will call you back in the appropriate context when a file descriptor becomes
-readable or writable.  Because libuv is a C library, you can easily use
-these interfaces directly in your v8+ addon.  Your libuv callback might then
-contain code looking something like this:
+context of the main event loop.  The function `v8plus_method_call()` is safe
+to call from any thread: depending on the context in which it is invoked, it
+will either make the call directly or queue the call in the main event loop
+and block on a reply.  Simply arrange to call back into your JavaScript
+object when you wish to post an event:
 
         nvlist_t *eap;
         nvlist_t *erp;
         my_object_t *op = ...;
         ...

@@ -726,10 +725,17 @@
 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?
 
 Because C++ is garbage.  Writing good software is challenging enough without