668
669 if (eap != NULL) {
670 erp = v8plus_method_call(op, "_emit", eap);
671 nvlist_free(eap);
672 nvlist_free(erp);
673 }
674
675 This example will generate an event named "my_event" and propagate it to
676 listeners registered with the `MyObjectWrapper` instance. If additional
677 arguments are associated with the event, they may be added to `eap` and will
678 also be passed along to listeners as arguments to their callbacks.
679
680 ### void v8plus_obj_hold(const void *op)
681
682 Places a hold on the V8 representation of the specified C object. This is
683 rarely necessary; `v8plus_defer()` performs this action for you, but other
684 asynchronous mechanisms may require it. If you are returning from a method
685 call but have stashed a reference to the object somewhere and are not
686 calling `v8plus_defer()`, you must call this first. Holds and releases must
687 be balanced. Use of the object within a thread after releasing is a bug.
688
689 ### void v8plus_obj_rele(const void *op)
690
691 Releases a hold placed by `v8plus_obj_hold()`. This function may be called
692 safely from any thread; releases from threads other than the main event loop
693 are non-blocking and will occur some time in the future.
694
695 ### void v8plus_jsfunc_hold(v8plus_jsfunc_t f)
696
697 Places a hold on the V8 representation of the specified JavaScript function.
698 This is required when returning from a C function that has stashed a
699 reference to the function, typically to use it asynchronously as a callback.
700 All holds must be balanced with a release. Because a single hold is placed
701 on such objects when passed to you in an argument list (and released for you
702 when you return), it is legal to reference and even to invoke such a
703 function without first placing an additional hold on it.
704
705 ### void v8plus_jsfunc_rele(v8plus_jsfunc_t f)
706
707 Releases a hold placed by `v8plus_jsfunc_hold()`. This function may be called
708 safely from any thread; releases from threads other than the main event loop
709 thread are non-blocking and will occur some time in the future.
710
711 ### void v8plus_defer(void *op, void *ctx, worker, completion)
712
713 Enqueues work to be performed in the Node.js shared thread pool. The object
714 `op` and context `ctx` are passed as arguments to `worker` executing in a
715 thread from that pool. The same two arguments, along with the worker's
716 return value, are passed to `completion` executing in the main event loop
717 thread. See example above.
718
719 ### nvlist_t *v8plus_call(v8plus_jsfunc_t f, const nvlist_t *ap)
720
721 Calls the JavaScript function referred to by `f` with encoded arguments
722 `ap`. The return value is the encoded return value of the function. The
723 argument and return value encoding match the encodings that are used by C
724 functions that provide methods.
725
726 As JavaScript functions must be called from the event loop thread,
727 `v8plus_call()` contains logic to determine whether we are in the
728 correct context or not. If we are running on some other thread we will
729 queue the request and sleep, waiting for the event loop thread to make the
730 call. In the simple case, where we are already in the correct thread, we
731 make the call directly.
732
733 Note that when passing JavaScript functions around as callbacks, you must use
734 first use `v8plus_jsfunc_hold()` from within the main event loop thread. Once
735 finished with the function, you may pass it to `v8plus_jsfunc_rele()` from any
736 thread to clean up.
737
|
668
669 if (eap != NULL) {
670 erp = v8plus_method_call(op, "_emit", eap);
671 nvlist_free(eap);
672 nvlist_free(erp);
673 }
674
675 This example will generate an event named "my_event" and propagate it to
676 listeners registered with the `MyObjectWrapper` instance. If additional
677 arguments are associated with the event, they may be added to `eap` and will
678 also be passed along to listeners as arguments to their callbacks.
679
680 ### void v8plus_obj_hold(const void *op)
681
682 Places a hold on the V8 representation of the specified C object. This is
683 rarely necessary; `v8plus_defer()` performs this action for you, but other
684 asynchronous mechanisms may require it. If you are returning from a method
685 call but have stashed a reference to the object somewhere and are not
686 calling `v8plus_defer()`, you must call this first. Holds and releases must
687 be balanced. Use of the object within a thread after releasing is a bug.
688 This hold includes an implicit event loop hold, as if `v8plus_eventloop_hold()`
689 was called.
690
691 ### void v8plus_obj_rele(const void *op)
692
693 Releases a hold placed by `v8plus_obj_hold()`. This function may be called
694 safely from any thread; releases from threads other than the main event loop
695 are non-blocking and will occur some time in the future. Releases the
696 implicit event loop hold obtained by `v8plus_obj_hold()`.
697
698 ### void v8plus_jsfunc_hold(v8plus_jsfunc_t f)
699
700 Places a hold on the V8 representation of the specified JavaScript function.
701 This is required when returning from a C function that has stashed a
702 reference to the function, typically to use it asynchronously as a callback.
703 All holds must be balanced with a release. Because a single hold is placed
704 on such objects when passed to you in an argument list (and released for you
705 when you return), it is legal to reference and even to invoke such a
706 function without first placing an additional hold on it. This hold includes
707 an implicit event loop hold, as if `v8plus_eventloop_hold()` was called.
708
709 ### void v8plus_jsfunc_rele(v8plus_jsfunc_t f)
710
711 Releases a hold placed by `v8plus_jsfunc_hold()`. This function may be called
712 safely from any thread; releases from threads other than the main event loop
713 thread are non-blocking and will occur some time in the future. Releases
714 the implicit event loop hold obtained by `v8plus_jsfunc_hold()`.
715
716 ### void v8plus_defer(void *op, void *ctx, worker, completion)
717
718 Enqueues work to be performed in the Node.js shared thread pool. The object
719 `op` and context `ctx` are passed as arguments to `worker` executing in a
720 thread from that pool. The same two arguments, along with the worker's
721 return value, are passed to `completion` executing in the main event loop
722 thread. See example above.
723
724 ### void v8plus_eventloop_hold(void)
725
726 Places a hold on the V8 event loop. V8 will terminate when it detects that
727 there is no more work to do. This liveliness check includes things like open
728 sockets or file descriptors, but only if they are tracked by the event loop
729 itself. If you are using multiple threads, some of which may blocking waiting
730 for input (e.g. a message subscription thread) then you will need to prevent V8
731 from terminating prematurely. This function must be called from within the
732 main event loop thread. Each hold must be balanced with a release. Note that
733 holds on objects or functions obtained via `v8plus_obj_hold()` or
734 `v8plus_jsfunc_hold()` will implicitly hold the event loop for you.
735
736 ### void v8plus_eventloop_rele(void)
737
738 Release a hold on the V8 event loop. If there are no more pending events or
739 input sources, then V8 will generally terminate the process shortly afterward.
740 This function may be called safely from any thread; releases from threads other
741 than the main event loop thread are non-blocking and will occur some time in
742 the future.
743
744 ### nvlist_t *v8plus_call(v8plus_jsfunc_t f, const nvlist_t *ap)
745
746 Calls the JavaScript function referred to by `f` with encoded arguments
747 `ap`. The return value is the encoded return value of the function. The
748 argument and return value encoding match the encodings that are used by C
749 functions that provide methods.
750
751 As JavaScript functions must be called from the event loop thread,
752 `v8plus_call()` contains logic to determine whether we are in the
753 correct context or not. If we are running on some other thread we will
754 queue the request and sleep, waiting for the event loop thread to make the
755 call. In the simple case, where we are already in the correct thread, we
756 make the call directly.
757
758 Note that when passing JavaScript functions around as callbacks, you must use
759 first use `v8plus_jsfunc_hold()` from within the main event loop thread. Once
760 finished with the function, you may pass it to `v8plus_jsfunc_rele()` from any
761 thread to clean up.
762
|