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.256 by root, Tue Jul 14 20:31:21 2009 UTC

… …
862 862
863This call will simply invoke all pending watchers while resetting their 863This call will simply invoke all pending watchers while resetting their
864pending state. Normally, C<ev_loop> does this automatically when required, 864pending state. Normally, C<ev_loop> does this automatically when required,
865but when overriding the invoke callback this call comes handy. 865but when overriding the invoke callback this call comes handy.
866 866
867=item int ev_pending_count (loop)
868
869Returns the number of pending watchers - zero indicates that no watchers
870are pending.
871
867=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P)) 872=item ev_set_invoke_pending_cb (loop, void (*invoke_pending_cb)(EV_P))
868 873
869This overrides the invoke pending functionality of the loop: Instead of 874This overrides the invoke pending functionality of the loop: Instead of
870invoking all pending watchers when there are any, C<ev_loop> will call 875invoking all pending watchers when there are any, C<ev_loop> will call
871this callback instead. This is useful, for example, when you want to 876this callback instead. This is useful, for example, when you want to
… …
889suspended waiting for new events, and C<acquire> is called just 894suspended waiting for new events, and C<acquire> is called just
890afterwards. 895afterwards.
891 896
892Ideally, C<release> will just call your mutex_unlock function, and 897Ideally, C<release> will just call your mutex_unlock function, and
893C<acquire> will just call the mutex_lock function again. 898C<acquire> will just call the mutex_lock function again.
899
900While event loop modifications are allowed between invocations of
901C<release> and C<acquire> (that's their only purpose after all), no
902modifications done will affect the event loop, i.e. adding watchers will
903have no effect on the set of file descriptors being watched, or the time
904waited. USe an C<ev_async> watcher to wake up C<ev_loop> when you want it
905to take note of any changes you made.
906
907In theory, threads executing C<ev_loop> will be async-cancel safe between
908invocations of C<release> and C<acquire>.
909
910See also the locking example in the C<THREADS> section later in this
911document.
894 912
895=item ev_set_userdata (loop, void *data) 913=item ev_set_userdata (loop, void *data)
896 914
897=item ev_userdata (loop) 915=item ev_userdata (loop)
898 916
… …
3928 3946
3929=back 3947=back
3930 3948
3931=head4 THREAD LOCKING EXAMPLE 3949=head4 THREAD LOCKING EXAMPLE
3932 3950
3951Here is a fictitious example of how to run an event loop in a different
3952thread than where callbacks are being invoked and watchers are
3953created/added/removed.
3954
3955For a real-world example, see the C<EV::Loop::Async> perl module,
3956which uses exactly this technique (which is suited for many high-level
3957languages).
3958
3959The example uses a pthread mutex to protect the loop data, a condition
3960variable to wait for callback invocations, an async watcher to notify the
3961event loop thread and an unspecified mechanism to wake up the main thread.
3962
3963First, you need to associate some data with the event loop:
3964
3965 typedef struct {
3966 mutex_t lock; /* global loop lock */
3967 ev_async async_w;
3968 thread_t tid;
3969 cond_t invoke_cv;
3970 } userdata;
3971
3972 void prepare_loop (EV_P)
3973 {
3974 // for simplicity, we use a static userdata struct.
3975 static userdata u;
3976
3977 ev_async_init (&u->async_w, async_cb);
3978 ev_async_start (EV_A_ &u->async_w);
3979
3980 pthread_mutex_init (&u->lock, 0);
3981 pthread_cond_init (&u->invoke_cv, 0);
3982
3983 // now associate this with the loop
3984 ev_set_userdata (EV_A_ u);
3985 ev_set_invoke_pending_cb (EV_A_ l_invoke);
3986 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
3987
3988 // then create the thread running ev_loop
3989 pthread_create (&u->tid, 0, l_run, EV_A);
3990 }
3991
3992The callback for the C<ev_async> watcher does nothing: the watcher is used
3993solely to wake up the event loop so it takes notice of any new watchers
3994that might have been added:
3995
3996 static void
3997 async_cb (EV_P_ ev_async *w, int revents)
3998 {
3999 // just used for the side effects
4000 }
4001
4002The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
4003protecting the loop data, respectively.
4004
4005 static void
4006 l_release (EV_P)
4007 {
4008 userdata *u = ev_userdata (EV_A);
4009 pthread_mutex_unlock (&u->lock);
4010 }
4011
4012 static void
4013 l_acquire (EV_P)
4014 {
4015 userdata *u = ev_userdata (EV_A);
4016 pthread_mutex_lock (&u->lock);
4017 }
4018
4019The event loop thread first acquires the mutex, and then jumps straight
4020into C<ev_loop>:
4021
4022 void *
4023 l_run (void *thr_arg)
4024 {
4025 struct ev_loop *loop = (struct ev_loop *)thr_arg;
4026
4027 l_acquire (EV_A);
4028 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
4029 ev_loop (EV_A_ 0);
4030 l_release (EV_A);
4031
4032 return 0;
4033 }
4034
4035Instead of invoking all pending watchers, the C<l_invoke> callback will
4036signal the main thread via some unspecified mechanism (signals? pipe
4037writes? C<Async::Interrupt>?) and then waits until all pending watchers
4038have been called (in a while loop because a) spurious wakeups are possible
4039and b) skipping inter-thread-communication when there are no pending
4040watchers is very beneficial):
4041
4042 static void
4043 l_invoke (EV_P)
4044 {
4045 userdata *u = ev_userdata (EV_A);
4046
4047 while (ev_pending_count (EV_A))
4048 {
4049 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
4050 pthread_cond_wait (&u->invoke_cv, &u->lock);
4051 }
4052 }
4053
4054Now, whenever the main thread gets told to invoke pending watchers, it
4055will grab the lock, call C<ev_invoke_pending> and then signal the loop
4056thread to continue:
4057
4058 static void
4059 real_invoke_pending (EV_P)
4060 {
4061 userdata *u = ev_userdata (EV_A);
4062
4063 pthread_mutex_lock (&u->lock);
4064 ev_invoke_pending (EV_A);
4065 pthread_cond_signal (&u->invoke_cv);
4066 pthread_mutex_unlock (&u->lock);
4067 }
4068
4069Whenever you want to start/stop a watcher or do other modifications to an
4070event loop, you will now have to lock:
4071
4072 ev_timer timeout_watcher;
4073 userdata *u = ev_userdata (EV_A);
4074
4075 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
4076
4077 pthread_mutex_lock (&u->lock);
4078 ev_timer_start (EV_A_ &timeout_watcher);
4079 ev_async_send (EV_A_ &u->async_w);
4080 pthread_mutex_unlock (&u->lock);
4081
4082Note that sending the C<ev_async> watcher is required because otherwise
4083an event loop currently blocking in the kernel will have no knowledge
4084about the newly added timer. By waking up the loop it will pick up any new
4085watchers in the next event loop iteration.
4086
3933=head3 COROUTINES 4087=head3 COROUTINES
3934 4088
3935Libev is very accommodating to coroutines ("cooperative threads"): 4089Libev is very accommodating to coroutines ("cooperative threads"):
3936libev fully supports nesting calls to its functions from different 4090libev fully supports nesting calls to its functions from different
3937coroutines (e.g. you can call C<ev_loop> on the same loop from two 4091coroutines (e.g. you can call C<ev_loop> on the same loop from two
3938different coroutines, and switch freely between both coroutines running the 4092different coroutines, and switch freely between both coroutines running
3939loop, as long as you don't confuse yourself). The only exception is that 4093the loop, as long as you don't confuse yourself). The only exception is
3940you must not do this from C<ev_periodic> reschedule callbacks. 4094that you must not do this from C<ev_periodic> reschedule callbacks.
3941 4095
3942Care has been taken to ensure that libev does not keep local state inside 4096Care has been taken to ensure that libev does not keep local state inside
3943C<ev_loop>, and other calls do not usually allow for coroutine switches as 4097C<ev_loop>, and other calls do not usually allow for coroutine switches as
3944they do not call any callbacks. 4098they do not call any callbacks.
3945 4099

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines