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

Comparing libev/ev.pod (file contents):
Revision 1.253 by root, Tue Jul 14 18:33:48 2009 UTC vs.
Revision 1.254 by root, Tue Jul 14 19:02:43 2009 UTC

… …
890afterwards. 890afterwards.
891 891
892Ideally, C<release> will just call your mutex_unlock function, and 892Ideally, C<release> will just call your mutex_unlock function, and
893C<acquire> will just call the mutex_lock function again. 893C<acquire> will just call the mutex_lock function again.
894 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
895=item ev_set_userdata (loop, void *data) 908=item ev_set_userdata (loop, void *data)
896 909
897=item ev_userdata (loop) 910=item ev_userdata (loop)
898 911
899Set and retrieve a single C<void *> associated with a loop. When 912Set and retrieve a single C<void *> associated with a loop. When
… …
3928 3941
3929=back 3942=back
3930 3943
3931=head4 THREAD LOCKING EXAMPLE 3944=head4 THREAD LOCKING EXAMPLE
3932 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
3933=head3 COROUTINES 4078=head3 COROUTINES
3934 4079
3935Libev is very accommodating to coroutines ("cooperative threads"): 4080Libev is very accommodating to coroutines ("cooperative threads"):
3936libev fully supports nesting calls to its functions from different 4081libev fully supports nesting calls to its functions from different
3937coroutines (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