[ViewVC] Diff of: cvs/libev/ev.pod

Comparing libev/ev.pod (file contents):
Revision 1.352 by root, Mon Jan 10 14:30:15 2011 UTC vs.
Revision 1.356 by root, Tue Jan 11 01:42:47 2011 UTC

 employing an additional generation counter and comparing that against the
 events to filter out spurious ones, recreating the set when required. Last
 not least, it also refuses to work with some file descriptors which work
 perfectly fine with C<select> (files, many character devices...).
-Epoll is truly the train wreck analog among event poll mechanisms.
+Epoll is truly the train wreck analog among event poll mechanisms,
+a frankenpoll, cobbled together in a hurry, no thought to design or
+interaction with others.
 While stopping, setting and starting an I/O watcher in the same iteration
 will result in some caching, there is still a system call per such
 incident (because the same I<file descriptor> could point to a different
 I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
 hacks).
 On the negative side, the interface is I<bizarre> - so bizarre that
 even sun itself gets it wrong in their code examples: The event polling
 function sometimes returning events to the caller even though an error
-occured, but with no indication whether it has done so or not (yes, it's
+occurred, but with no indication whether it has done so or not (yes, it's
 even documented that way) - deadly for edge-triggered interfaces where
-you absolutely have to know whether an event occured or not because you
+you absolutely have to know whether an event occurred or not because you
 have to re-arm the watcher.
 Fortunately libev seems to be able to work around these idiocies.
 This backend maps C<EV_READ> and C<EV_WRITE> in the same way as
 In general you can register as many read and/or write event watchers per
 fd as you want (as long as you don't confuse yourself). Setting all file
 descriptors to non-blocking mode is also usually a good idea (but not
 required if you know what you are doing).
-If you cannot use non-blocking mode, then force the use of a
-known-to-be-good backend (at the time of this writing, this includes only
-C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
-descriptors for which non-blocking operation makes no sense (such as
-files) - libev doesn't guarantee any specific behaviour in that case.
 Another thing you have to watch out for is that it is quite easy to
-receive "spurious" readiness notifications, that is your callback might
+receive "spurious" readiness notifications, that is, your callback might
 be called with C<EV_READ> but a subsequent C<read>(2) will actually block
-because there is no data. Not only are some backends known to create a
+because there is no data. It is very easy to get into this situation even
-lot of those (for example Solaris ports), it is very easy to get into
+with a relatively standard program structure. Thus it is best to always
-this situation even with a relatively standard program structure. Thus
+use non-blocking I/O: An extra C<read>(2) returning C<EAGAIN> is far
-it is best to always use non-blocking I/O: An extra C<read>(2) returning
-C<EAGAIN> is far preferable to a program hanging until some data arrives.
+preferable to a program hanging until some data arrives.
 If you cannot run the fd in non-blocking mode (for example you should
 not play around with an Xlib connection), then you have to separately
 re-test whether a file descriptor is really ready with a known-to-be good
-interface such as poll (fortunately in our Xlib example, Xlib already
+interface such as poll (fortunately in the case of Xlib, it already does
-does this on its own, so its quite safe to use). Some people additionally
+this on its own, so its quite safe to use). Some people additionally
 use C<SIGALRM> and an interval timer, just to be sure you won't block
 indefinitely.
 But really, best use non-blocking mode.
 There is no workaround possible except not registering events
 for potentially C<dup ()>'ed file descriptors, or to resort to
 C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
+=head3 The special problem of files
+Many people try to use C<select> (or libev) on file descriptors
+representing files, and expect it to become ready when their program
+doesn't block on disk accesses (which can take a long time on their own).
+However, this cannot ever work in the "expected" way - you get a readiness
+notification as soon as the kernel knows whether and how much data is
+there, and in the case of open files, that's always the case, so you
+always get a readiness notification instantly, and your read (or possibly
+write) will still block on the disk I/O.
+Another way to view it is that in the case of sockets, pipes, character
+devices and so on, there is another party (the sender) that delivers data
+on it's own, but in the case of files, there is no such thing: the disk
+will not send data on it's own, simply because it doesn't know what you
+wish to read - you would first have to request some data.
+Since files are typically not-so-well supported by advanced notification
+mechanism, libev tries hard to emulate POSIX behaviour with respect
+to files, even though you should not use it. The reason for this is
+convenience: sometimes you want to watch STDIN or STDOUT, which is
+usually a tty, often a pipe, but also sometimes files or special devices
+(for example, C<epoll> on Linux works with F</dev/random> but not with
+F</dev/urandom>), and even though the file might better be served with
+asynchronous I/O instead of with non-blocking I/O, it is still useful when
+it "just works" instead of freezing.
+So avoid file descriptors pointing to files when you know it (e.g. use
+libeio), but use them when it is convenient, e.g. for STDIN/STDOUT, or
+when you rarely read from a file instead of from a socket, and want to
+reuse the same code path.
 =head3 The special problem of fork
 Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit
 useless behaviour. Libev fully supports fork, but needs to be told about
-it in the child.
+it in the child if you want to continue to use it in the child.
-To support fork in your programs, you either have to call
+To support fork in your child processes, you have to call C<ev_loop_fork
-C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child,
+()> after a fork in the child, enable C<EVFLAG_FORKCHECK>, or resort to
-enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
+C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
-C<EVBACKEND_POLL>.
 =head3 The special problem of SIGPIPE
 While not really specific to libev, it is easy to forget about C<SIGPIPE>:
 when writing to a pipe whose other end has been closed, your program gets
 This section explains some common idioms that are not immediately
 obvious. Note that examples are sprinkled over the whole manual, and this
 section only contains stuff that wouldn't fit anywhere else.
-=over 4
+=head2 MODEL/NESTED EVENT LOOP INVOCATIONS AND EXIT CONDITIONS
-=item Model/nested event loop invocations and exit conditions.
 Often (especially in GUI toolkits) there are places where you have
 I<modal> interaction, which is most easily implemented by recursively
 invoking C<ev_run>.
    exit_main_loop = 1;
    // exit both
    exit_main_loop = exit_nested_loop = 1;
-=back
+=head2 THREAD LOCKING EXAMPLE
+Here is a fictitious example of how to run an event loop in a different
+thread than where callbacks are being invoked and watchers are
+created/added/removed.
+For a real-world example, see the C<EV::Loop::Async> perl module,
+which uses exactly this technique (which is suited for many high-level
+languages).
+The example uses a pthread mutex to protect the loop data, a condition
+variable to wait for callback invocations, an async watcher to notify the
+event loop thread and an unspecified mechanism to wake up the main thread.
+First, you need to associate some data with the event loop:
+   typedef struct {
+     mutex_t lock; /* global loop lock */
+     ev_async async_w;
+     thread_t tid;
+     cond_t invoke_cv;
+   } userdata;
+   void prepare_loop (EV_P)
+   {
+      // for simplicity, we use a static userdata struct.
+      static userdata u;
+      ev_async_init (&u->async_w, async_cb);
+      ev_async_start (EV_A_ &u->async_w);
+      pthread_mutex_init (&u->lock, 0);
+      pthread_cond_init (&u->invoke_cv, 0);
+      // now associate this with the loop
+      ev_set_userdata (EV_A_ u);
+      ev_set_invoke_pending_cb (EV_A_ l_invoke);
+      ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
+      // then create the thread running ev_loop
+      pthread_create (&u->tid, 0, l_run, EV_A);
+   }
+The callback for the C<ev_async> watcher does nothing: the watcher is used
+solely to wake up the event loop so it takes notice of any new watchers
+that might have been added:
+   static void
+   async_cb (EV_P_ ev_async *w, int revents)
+   {
+      // just used for the side effects
+   }
+The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
+protecting the loop data, respectively.
+   static void
+   l_release (EV_P)
+   {
+     userdata *u = ev_userdata (EV_A);
+     pthread_mutex_unlock (&u->lock);
+   }
+   static void
+   l_acquire (EV_P)
+   {
+     userdata *u = ev_userdata (EV_A);
+     pthread_mutex_lock (&u->lock);
+   }
+The event loop thread first acquires the mutex, and then jumps straight
+into C<ev_run>:
+   void *
+   l_run (void *thr_arg)
+   {
+     struct ev_loop *loop = (struct ev_loop *)thr_arg;
+     l_acquire (EV_A);
+     pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
+     ev_run (EV_A_ 0);
+     l_release (EV_A);
+     return 0;
+   }
+Instead of invoking all pending watchers, the C<l_invoke> callback will
+signal the main thread via some unspecified mechanism (signals? pipe
+writes? C<Async::Interrupt>?) and then waits until all pending watchers
+have been called (in a while loop because a) spurious wakeups are possible
+and b) skipping inter-thread-communication when there are no pending
+watchers is very beneficial):
+   static void
+   l_invoke (EV_P)
+   {
+     userdata *u = ev_userdata (EV_A);
+     while (ev_pending_count (EV_A))
+       {
+         wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
+         pthread_cond_wait (&u->invoke_cv, &u->lock);
+       }
+   }
+Now, whenever the main thread gets told to invoke pending watchers, it
+will grab the lock, call C<ev_invoke_pending> and then signal the loop
+thread to continue:
+   static void
+   real_invoke_pending (EV_P)
+   {
+     userdata *u = ev_userdata (EV_A);
+     pthread_mutex_lock (&u->lock);
+     ev_invoke_pending (EV_A);
+     pthread_cond_signal (&u->invoke_cv);
+     pthread_mutex_unlock (&u->lock);
+   }
+Whenever you want to start/stop a watcher or do other modifications to an
+event loop, you will now have to lock:
+   ev_timer timeout_watcher;
+   userdata *u = ev_userdata (EV_A);
+   ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
+   pthread_mutex_lock (&u->lock);
+   ev_timer_start (EV_A_ &timeout_watcher);
+   ev_async_send (EV_A_ &u->async_w);
+   pthread_mutex_unlock (&u->lock);
+Note that sending the C<ev_async> watcher is required because otherwise
+an event loop currently blocking in the kernel will have no knowledge
+about the newly added timer. By waking up the loop it will pick up any new
+watchers in the next event loop iteration.
 =head1 LIBEVENT EMULATION
 Libev offers a compatibility emulation layer for libevent. It cannot
 And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
    #include "ev_cpp.h"
    #include "ev.c"
-=head1 INTERACTION WITH OTHER PROGRAMS OR LIBRARIES
+=head1 INTERACTION WITH OTHER PROGRAMS, LIBRARIES OR THE ENVIRONMENT
 =head2 THREADS AND COROUTINES
 =head3 THREADS
 default loop and triggering an C<ev_async> watcher from the default loop
 watcher callback into the event loop interested in the signal.
 =back
-=head4 THREAD LOCKING EXAMPLE
+See also L<THREAD LOCKING EXAMPLE>.
-Here is a fictitious example of how to run an event loop in a different
-thread than where callbacks are being invoked and watchers are
-created/added/removed.
-For a real-world example, see the C<EV::Loop::Async> perl module,
-which uses exactly this technique (which is suited for many high-level
-languages).
-The example uses a pthread mutex to protect the loop data, a condition
-variable to wait for callback invocations, an async watcher to notify the
-event loop thread and an unspecified mechanism to wake up the main thread.
-First, you need to associate some data with the event loop:
-   typedef struct {
-     mutex_t lock; /* global loop lock */
-     ev_async async_w;
-     thread_t tid;
-     cond_t invoke_cv;
-   } userdata;
-   void prepare_loop (EV_P)
-   {
-      // for simplicity, we use a static userdata struct.
-      static userdata u;
-      ev_async_init (&u->async_w, async_cb);
-      ev_async_start (EV_A_ &u->async_w);
-      pthread_mutex_init (&u->lock, 0);
-      pthread_cond_init (&u->invoke_cv, 0);
-      // now associate this with the loop
-      ev_set_userdata (EV_A_ u);
-      ev_set_invoke_pending_cb (EV_A_ l_invoke);
-      ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
-      // then create the thread running ev_loop
-      pthread_create (&u->tid, 0, l_run, EV_A);
-   }
-The callback for the C<ev_async> watcher does nothing: the watcher is used
-solely to wake up the event loop so it takes notice of any new watchers
-that might have been added:
-   static void
-   async_cb (EV_P_ ev_async *w, int revents)
-   {
-      // just used for the side effects
-   }
-The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
-protecting the loop data, respectively.
-   static void
-   l_release (EV_P)
-   {
-     userdata *u = ev_userdata (EV_A);
-     pthread_mutex_unlock (&u->lock);
-   }
-   static void
-   l_acquire (EV_P)
-   {
-     userdata *u = ev_userdata (EV_A);
-     pthread_mutex_lock (&u->lock);
-   }
-The event loop thread first acquires the mutex, and then jumps straight
-into C<ev_run>:
-   void *
-   l_run (void *thr_arg)
-   {
-     struct ev_loop *loop = (struct ev_loop *)thr_arg;
-     l_acquire (EV_A);
-     pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
-     ev_run (EV_A_ 0);
-     l_release (EV_A);
-     return 0;
-   }
-Instead of invoking all pending watchers, the C<l_invoke> callback will
-signal the main thread via some unspecified mechanism (signals? pipe
-writes? C<Async::Interrupt>?) and then waits until all pending watchers
-have been called (in a while loop because a) spurious wakeups are possible
-and b) skipping inter-thread-communication when there are no pending
-watchers is very beneficial):
-   static void
-   l_invoke (EV_P)
-   {
-     userdata *u = ev_userdata (EV_A);
-     while (ev_pending_count (EV_A))
-       {
-         wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
-         pthread_cond_wait (&u->invoke_cv, &u->lock);
-       }
-   }
-Now, whenever the main thread gets told to invoke pending watchers, it
-will grab the lock, call C<ev_invoke_pending> and then signal the loop
-thread to continue:
-   static void
-   real_invoke_pending (EV_P)
-   {
-     userdata *u = ev_userdata (EV_A);
-     pthread_mutex_lock (&u->lock);
-     ev_invoke_pending (EV_A);
-     pthread_cond_signal (&u->invoke_cv);
-     pthread_mutex_unlock (&u->lock);
-   }
-Whenever you want to start/stop a watcher or do other modifications to an
-event loop, you will now have to lock:
-   ev_timer timeout_watcher;
-   userdata *u = ev_userdata (EV_A);
-   ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
-   pthread_mutex_lock (&u->lock);
-   ev_timer_start (EV_A_ &timeout_watcher);
-   ev_async_send (EV_A_ &u->async_w);
-   pthread_mutex_unlock (&u->lock);
-Note that sending the C<ev_async> watcher is required because otherwise
-an event loop currently blocking in the kernel will have no knowledge
-about the newly added timer. By waking up the loop it will pick up any new
-watchers in the next event loop iteration.
 =head3 COROUTINES
 Libev is very accommodating to coroutines ("cooperative threads"):
 libev fully supports nesting calls to its functions from different

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.352 by root, Mon Jan 10 14:30:15 2011 UTC vs. Revision 1.356 by root, Tue Jan 11 01:42:47 2011 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.352 by root, Mon Jan 10 14:30:15 2011 UTC vs.
Revision 1.356 by root, Tue Jan 11 01:42:47 2011 UTC