ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.248 by root, Wed Jul 8 04:14:34 2009 UTC vs.
Revision 1.254 by root, Tue Jul 14 19:02:43 2009 UTC

856more often than 100 times per second: 856more often than 100 times per second:
857 857
858 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1); 858 ev_set_timeout_collect_interval (EV_DEFAULT_UC_ 0.1);
859 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01); 859 ev_set_io_collect_interval (EV_DEFAULT_UC_ 0.01);
860 860
861=item ev_invoke_pending (loop)
862
863This call will simply invoke all pending watchers while resetting their
864pending state. Normally, C<ev_loop> does this automatically when required,
865but when overriding the invoke callback this call comes handy.
866
867=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
868
869This overrides the invoke pending functionality of the loop: Instead of
870invoking all pending watchers when there are any, C<ev_loop> will call
871this callback instead. This is useful, for example, when you want to
872invoke the actual watchers inside another context (another thread etc.).
873
874If you want to reset the callback, use C<ev_invoke_pending> as new
875callback.
876
877=item ev_set_loop_release_cb (loop, void (*release)(EV_P), void (*acquire)(EV_P))
878
879Sometimes you want to share the same loop between multiple threads. This
880can be done relatively simply by putting mutex_lock/unlock calls around
881each call to a libev function.
882
883However, C<ev_loop> can run an indefinite time, so it is not feasible to
884wait for it to return. One way around this is to wake up the loop via
885C<ev_unloop> and C<av_async_send>, another way is to set these I<release>
886and I<acquire> callbacks on the loop.
887
888When set, then C<release> will be called just before the thread is
889suspended waiting for new events, and C<acquire> is called just
890afterwards.
891
892Ideally, C<release> will just call your mutex_unlock function, and
893C<acquire> will just call the mutex_lock function again.
894
895While event loop modifications are allowed between invocations of
896C<release> and C<acquire> (that's their only purpose after all), no
897modifications done will affect the event loop, i.e. adding watchers will
898have no effect on the set of file descriptors being watched, or the time
899waited. USe an C<ev_async> watcher to wake up C<ev_loop> when you want it
900to take note of any changes you made.
901
902In theory, threads executing C<ev_loop> will be async-cancel safe between
903invocations of C<release> and C<acquire>.
904
905See also the locking example in the C<THREADS> section later in this
906document.
907
908=item ev_set_userdata (loop, void *data)
909
910=item ev_userdata (loop)
911
912Set and retrieve a single C<void *> associated with a loop. When
913C<ev_set_userdata> has never been called, then C<ev_userdata> returns
914C<0.>
915
916These two functions can be used to associate arbitrary data with a loop,
917and are intended solely for the C<invoke_pending_cb>, C<release> and
918C<acquire> callbacks described above, but of course can be (ab-)used for
919any other purpose as well.
920
861=item ev_loop_verify (loop) 921=item ev_loop_verify (loop)
862 922
863This function only does something when C<EV_VERIFY> support has been 923This function only does something when C<EV_VERIFY> support has been
864compiled in, which is the default for non-minimal builds. It tries to go 924compiled in, which is the default for non-minimal builds. It tries to go
865through all internal structures and checks them for validity. If anything 925through all internal structures and checks them for validity. If anything
2033 2093
2034Only the default event loop is capable of handling signals, and therefore 2094Only the default event loop is capable of handling signals, and therefore
2035you can only register child watchers in the default event loop. 2095you can only register child watchers in the default event loop.
2036 2096
2037Due to some design glitches inside libev, child watchers will always be 2097Due to some design glitches inside libev, child watchers will always be
2038handled at maximum priority (their priority is set to EV_MAXPRI by libev) 2098handled at maximum priority (their priority is set to C<EV_MAXPRI> by
2099libev)
2039 2100
2040=head3 Process Interaction 2101=head3 Process Interaction
2041 2102
2042Libev grabs C<SIGCHLD> as soon as the default event loop is 2103Libev grabs C<SIGCHLD> as soon as the default event loop is
2043initialised. This is necessary to guarantee proper behaviour even if 2104initialised. This is necessary to guarantee proper behaviour even if
3670defined to be C<0>, then they are not. 3731defined to be C<0>, then they are not.
3671 3732
3672=item EV_MINIMAL 3733=item EV_MINIMAL
3673 3734
3674If you need to shave off some kilobytes of code at the expense of some 3735If you need to shave off some kilobytes of code at the expense of some
3675speed, define this symbol to C<1>. Currently this is used to override some 3736speed (but with the full API), define this symbol to C<1>. Currently this
3676inlining decisions, saves roughly 30% code size on amd64. It also selects a 3737is used to override some inlining decisions, saves roughly 30% code size
3677much smaller 2-heap for timer management over the default 4-heap. 3738on amd64. It also selects a much smaller 2-heap for timer management over
3739the default 4-heap.
3740
3741You can save even more by disabling watcher types you do not need
3742and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert>
3743(C<-DNDEBUG>) will usually reduce code size a lot.
3744
3745Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to
3746provide a bare-bones event library. See C<ev.h> for details on what parts
3747of the API are still available, and do not complain if this subset changes
3748over time.
3678 3749
3679=item EV_PID_HASHSIZE 3750=item EV_PID_HASHSIZE
3680 3751
3681C<ev_child> watchers use a small hash table to distribute workload by 3752C<ev_child> watchers use a small hash table to distribute workload by
3682pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 3753pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
3868default loop and triggering an C<ev_async> watcher from the default loop 3939default loop and triggering an C<ev_async> watcher from the default loop
3869watcher callback into the event loop interested in the signal. 3940watcher callback into the event loop interested in the signal.
3870 3941
3871=back 3942=back
3872 3943
3944=head4 THREAD LOCKING EXAMPLE
3945
3946Here is a fictitious example of how to run an event loop in a different
3947thread than where callbacks are being invoked and watchers are
3948created/added/removed.
3949
3950For a real-world example, see the C<EV::Loop::Async> perl module,
3951which uses exactly this technique (which is suited for many high-level
3952languages).
3953
3954The example uses a pthread mutex to protect the loop data, a condition
3955variable to wait for callback invocations, an async watcher to notify the
3956event loop thread and an unspecified mechanism to wake up the main thread.
3957
3958First, you need to associate some data with the event loop:
3959
3960 typedef struct {
3961 mutex_t lock; /* global loop lock */
3962 ev_async async_w;
3963 thread_t tid;
3964 cond_t invoke_cv;
3965 } userdata;
3966
3967 void prepare_loop (EV_P)
3968 {
3969 // for simplicity, we use a static userdata struct.
3970 static userdata u;
3971
3972 ev_async_init (&u->async_w, async_cb);
3973 ev_async_start (EV_A_ &u->async_w);
3974
3975 pthread_mutex_init (&u->lock, 0);
3976 pthread_cond_init (&u->invoke_cv, 0);
3977
3978 // now associate this with the loop
3979 ev_set_userdata (EV_A_ u);
3980 ev_set_invoke_pending_cb (EV_A_ l_invoke);
3981 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
3982
3983 // then create the thread running ev_loop
3984 pthread_create (&u->tid, 0, l_run, EV_A);
3985 }
3986
3987The callback for the C<ev_async> watcher does nothing: the watcher is used
3988solely to wake up the event loop so it takes notice of any new watchers
3989that might have been added:
3990
3991 static void
3992 async_cb (EV_P_ ev_async *w, int revents)
3993 {
3994 // just used for the side effects
3995 }
3996
3997The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
3998protecting the loop data, respectively.
3999
4000 static void
4001 l_release (EV_P)
4002 {
4003 udat *u = ev_userdata (EV_A);
4004 pthread_mutex_unlock (&u->lock);
4005 }
4006
4007 static void
4008 l_acquire (EV_P)
4009 {
4010 udat *u = ev_userdata (EV_A);
4011 pthread_mutex_lock (&u->lock);
4012 }
4013
4014The event loop thread first acquires the mutex, and then jumps straight
4015into C<ev_loop>:
4016
4017 void *
4018 l_run (void *thr_arg)
4019 {
4020 struct ev_loop *loop = (struct ev_loop *)thr_arg;
4021
4022 l_acquire (EV_A);
4023 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
4024 ev_loop (EV_A_ 0);
4025 l_release (EV_A);
4026
4027 return 0;
4028 }
4029
4030Instead of invoking all pending watchers, the C<l_invoke> callback will
4031signal the main thread via some unspecified mechanism (signals? pipe
4032writes? C<Async::Interrupt>?) and then waits until all pending watchers
4033have been called:
4034
4035 static void
4036 l_invoke (EV_P)
4037 {
4038 udat *u = ev_userdata (EV_A);
4039
4040 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
4041
4042 pthread_cond_wait (&u->invoke_cv, &u->lock);
4043 }
4044
4045Now, whenever the main thread gets told to invoke pending watchers, it
4046will grab the lock, call C<ev_invoke_pending> and then signal the loop
4047thread to continue:
4048
4049 static void
4050 real_invoke_pending (EV_P)
4051 {
4052 udat *u = ev_userdata (EV_A);
4053
4054 pthread_mutex_lock (&u->lock);
4055 ev_invoke_pending (EV_A);
4056 pthread_cond_signal (&u->invoke_cv);
4057 pthread_mutex_unlock (&u->lock);
4058 }
4059
4060Whenever you want to start/stop a watcher or do other modifications to an
4061event loop, you will now have to lock:
4062
4063 ev_timer timeout_watcher;
4064 udat *u = ev_userdata (EV_A);
4065
4066 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
4067
4068 pthread_mutex_lock (&u->lock);
4069 ev_timer_start (EV_A_ &timeout_watcher);
4070 ev_async_send (EV_A_ &u->async_w);
4071 pthread_mutex_unlock (&u->lock);
4072
4073Note that sending the C<ev_async> watcher is required because otherwise
4074an event loop currently blocking in the kernel will have no knowledge
4075about the newly added timer. By waking up the loop it will pick up any new
4076watchers in the next event loop iteration.
4077
3873=head3 COROUTINES 4078=head3 COROUTINES
3874 4079
3875Libev is very accommodating to coroutines ("cooperative threads"): 4080Libev is very accommodating to coroutines ("cooperative threads"):
3876libev fully supports nesting calls to its functions from different 4081libev fully supports nesting calls to its functions from different
3877coroutines (e.g. you can call C<ev_loop> on the same loop from two 4082coroutines (e.g. you can call C<ev_loop> on the same loop from two

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines