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

Comparing libev/ev.pod (file contents):
Revision 1.114 by root, Mon Dec 31 01:31:30 2007 UTC vs.
Revision 1.131 by root, Tue Feb 19 17:09:28 2008 UTC

 flags. If that is troubling you, check C<ev_backend ()> afterwards).
 If you don't know what event loop to use, use the one returned from this
 function.
+The default loop is the only loop that can handle C<ev_signal> and
+C<ev_child> watchers, and to do this, it always registers a handler
+for C<SIGCHLD>. If this is a problem for your app you can either
+create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
+can simply overwrite the C<SIGCHLD> signal handler I<after> calling
+C<ev_default_init>.
 The flags argument can be used to specify special behaviour or specific
 backends to use, and is usually specified as C<0> (or C<EVFLAG_AUTO>).
 The following flags are supported:
 While this backend scales well, it requires one system call per active
 file descriptor per loop iteration. For small and medium numbers of file
 descriptors a "slow" C<EVBACKEND_SELECT> or C<EVBACKEND_POLL> backend
 might perform better.
+On the positive side, ignoring the spurious readyness notifications, this
+backend actually performed to specification in all tests and is fully
+embeddable, which is a rare feat among the OS-specific backends.
 =item C<EVBACKEND_ALL>
 Try all backends (even potentially broken ones that wouldn't be tried
 with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
 C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
 It is definitely not recommended to use this flag.
 =back
 If one or more of these are ored into the flags value, then only these
-backends will be tried (in the reverse order as given here). If none are
+backends will be tried (in the reverse order as listed here). If none are
-specified, most compiled-in backend will be tried, usually in reverse
+specified, all backends in C<ev_recommended_backends ()> will be tried.
-order of their flag values :)
 The most typical usage is like this:
   if (!ev_default_loop (0))
     fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
 Like C<ev_default_destroy>, but destroys an event loop created by an
 earlier call to C<ev_loop_new>.
 =item ev_default_fork ()
+This function sets a flag that causes subsequent C<ev_loop> iterations
-This function reinitialises the kernel state for backends that have
+to reinitialise the kernel state for backends that have one. Despite the
-one. Despite the name, you can call it anytime, but it makes most sense
+name, you can call it anytime, but it makes most sense after forking, in
-after forking, in either the parent or child process (or both, but that
+the child process (or both child and parent, but that again makes little
-again makes little sense).
+sense). You I<must> call it in the child before using any of the libev
+functions, and it will only take effect at the next C<ev_loop> iteration.
-You I<must> call this function in the child process after forking if and
+On the other hand, you only need to call this function in the child
-only if you want to use the event library in both processes. If you just
+process if and only if you want to use the event library in the child. If
-fork+exec, you don't have to call it.
+you just fork+exec, you don't have to call it at all.
 The function itself is quite fast and it's usually not a problem to call
 it just in case after a fork. To make this easy, the function will fit in
 quite nicely into a call to C<pthread_atfork>:
     pthread_atfork (0, 0, ev_default_fork);
-At the moment, C<EVBACKEND_SELECT> and C<EVBACKEND_POLL> are safe to use
-without calling this function, so if you force one of those backends you
-do not need to care.
 =item ev_loop_fork (loop)
 Like C<ev_default_fork>, but acts on an event loop created by
 C<ev_loop_new>. Yes, you have to call this on every allocated event loop
 after fork, and how you do this is entirely your own problem.
+=item int ev_is_default_loop (loop)
+Returns true when the given loop actually is the default loop, false otherwise.
 =item unsigned int ev_loop_count (loop)
 Returns the count of loop iterations for the loop, which is identical to
 the number of times libev did poll for new events. It starts at C<0> and
 Can be used to make a call to C<ev_loop> return early (but only after it
 has processed all outstanding events). The C<how> argument must be either
 C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
 C<EVUNLOOP_ALL>, which will make all nested C<ev_loop> calls return.
+This "unloop state" will be cleared when entering C<ev_loop> again.
 =item ev_ref (loop)
 =item ev_unref (loop)
 Ref/unref can be used to add or remove a reference count on the event
 returning, ev_unref() after starting, and ev_ref() before stopping it. For
 example, libev itself uses this for its internal signal pipe: It is not
 visible to the libev user and should not keep C<ev_loop> from exiting if
 no event watchers registered by it are active. It is also an excellent
 way to do this for generic recurring timers or from within third-party
-libraries. Just remember to I<unref after start> and I<ref before stop>.
+libraries. Just remember to I<unref after start> and I<ref before stop>
+(but only if the watcher wasn't active before, or was active before,
+respectively).
 Example: Create a signal watcher, but keep it from keeping C<ev_loop>
 running when nothing else is active.
   struct ev_signal exitsig;
 =item C<EV_FORK>
 The event loop has been resumed in the child process after fork (see
 C<ev_fork>).
+=item C<EV_ASYNC>
+The given async watcher has been asynchronously notified (see C<ev_async>).
 =item C<EV_ERROR>
 An unspecified error has occured, the watcher has been stopped. This might
 happen because the watcher could not be properly started because libev
 =head3 Watcher-Specific Functions and Data Members
 =over 4
-=item ev_child_init (ev_child *, callback, int pid)
+=item ev_child_init (ev_child *, callback, int pid, int trace)
-=item ev_child_set (ev_child *, int pid)
+=item ev_child_set (ev_child *, int pid, int trace)
 Configures the watcher to wait for status changes of process C<pid> (or
 I<any> process if C<pid> is specified as C<0>). The callback can look
 at the C<rstatus> member of the C<ev_child> watcher structure to see
 the status word (use the macros from C<sys/wait.h> and see your systems
 C<waitpid> documentation). The C<rpid> member contains the pid of the
-process causing the status change.
+process causing the status change. C<trace> must be either C<0> (only
+activate the watcher when the process terminates) or C<1> (additionally
+activate the watcher when the process is stopped or continued).
 =item int pid [read-only]
 The process id this watcher watches out for, or C<0>, meaning any process id.
   static void
   idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents)
   {
     free (w);
     // now do something you wanted to do when the program has
-    // no longer asnything immediate to do.
+    // no longer anything immediate to do.
   }
   struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
   ev_idle_init (idle_watcher, idle_cb);
   ev_idle_start (loop, idle_cb);
 believe me.
 =back
+=head2 C<ev_async> - how to wake up another event loop
+In general, you cannot use an C<ev_loop> from multiple threads or other
+asynchronous sources such as signal handlers (as opposed to multiple event
+loops - those are of course safe to use in different threads).
+Sometimes, however, you need to wake up another event loop you do not
+control, for example because it belongs to another thread. This is what
+C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you
+can signal it by calling C<ev_async_send>, which is thread- and signal
+safe.
+This functionality is very similar to C<ev_signal> watchers, as signals,
+too, are asynchronous in nature, and signals, too, will be compressed
+(i.e. the number of callback invocations may be less than the number of
+C<ev_async_sent> calls).
+Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not
+just the default loop.
+=head3 Queueing
+C<ev_async> does not support queueing of data in any way. The reason
+is that the author does not know of a simple (or any) algorithm for a
+multiple-writer-single-reader queue that works in all cases and doesn't
+need elaborate support such as pthreads.
+That means that if you want to queue data, you have to provide your own
+queue. But at least I can tell you would implement locking around your
+queue:
+=over 4
+=item queueing from a signal handler context
+To implement race-free queueing, you simply add to the queue in the signal
+handler but you block the signal handler in the watcher callback. Here is an example that does that for
+some fictitiuous SIGUSR1 handler:
+   static ev_async mysig;
+   static void
+   sigusr1_handler (void)
+   {
+     sometype data;
+     // no locking etc.
+     queue_put (data);
+     ev_async_send (DEFAULT_ &mysig);
+   }
+   static void
+   mysig_cb (EV_P_ ev_async *w, int revents)
+   {
+     sometype data;
+     sigset_t block, prev;
+     sigemptyset (&block);
+     sigaddset (&block, SIGUSR1);
+     sigprocmask (SIG_BLOCK, &block, &prev);
+     while (queue_get (&data))
+       process (data);
+     if (sigismember (&prev, SIGUSR1)
+       sigprocmask (SIG_UNBLOCK, &block, 0);
+   }
+(Note: pthreads in theory requires you to use C<pthread_setmask>
+instead of C<sigprocmask> when you use threads, but libev doesn't do it
+either...).
+=item queueing from a thread context
+The strategy for threads is different, as you cannot (easily) block
+threads but you can easily preempt them, so to queue safely you need to
+employ a traditional mutex lock, such as in this pthread example:
+   static ev_async mysig;
+   static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER;
+   static void
+   otherthread (void)
+   {
+     // only need to lock the actual queueing operation
+     pthread_mutex_lock (&mymutex);
+     queue_put (data);
+     pthread_mutex_unlock (&mymutex);
+     ev_async_send (DEFAULT_ &mysig);
+   }
+   static void
+   mysig_cb (EV_P_ ev_async *w, int revents)
+   {
+     pthread_mutex_lock (&mymutex);
+     while (queue_get (&data))
+       process (data);
+     pthread_mutex_unlock (&mymutex);
+   }
+=back
+=head3 Watcher-Specific Functions and Data Members
+=over 4
+=item ev_async_init (ev_async *, callback)
+Initialises and configures the async watcher - it has no parameters of any
+kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless,
+believe me.
+=item ev_async_send (loop, ev_async *)
+Sends/signals/activates the given C<ev_async> watcher, that is, feeds
+an C<EV_ASYNC> event on the watcher into the event loop. Unlike
+C<ev_feed_event>, this call is safe to do in other threads, signal or
+similar contexts (see the dicusssion of C<EV_ATOMIC_T> in the embedding
+section below on what exactly this means).
+This call incurs the overhead of a syscall only once per loop iteration,
+so while the overhead might be noticable, it doesn't apply to repeated
+calls to C<ev_async_send>.
+=back
 =head1 OTHER FUNCTIONS
 There are some other functions of possible interest. Described. Here. Now.
 =over 4
 Example: Define a class with an IO and idle watcher, start one of them in
 the constructor.
   class myclass
   {
-    ev_io   io;   void io_cb   (ev::io   &w, int revents);
+    ev::io   io;  void io_cb   (ev::io   &w, int revents);
-    ev_idle idle  void idle_cb (ev::idle &w, int revents);
+    ev:idle idle  void idle_cb (ev::idle &w, int revents);
-    myclass ();
+    myclass (int fd)
-  }
-  myclass::myclass (int fd)
-  {
+    {
-    io  .set <myclass, &myclass::io_cb  > (this);
+      io  .set <myclass, &myclass::io_cb  > (this);
-    idle.set <myclass, &myclass::idle_cb> (this);
+      idle.set <myclass, &myclass::idle_cb> (this);
-    io.start (fd, ev::READ);
+      io.start (fd, ev::READ);
+    }
-  }
+  };
 =head1 MACRO MAGIC
 Libev can be compiled with a variety of options, the most fundamantal
 If defined to be C<1>, libev will compile in support for the Linux inotify
 interface to speed up C<ev_stat> watchers. Its actual availability will
 be detected at runtime.
+=item EV_ATOMIC_T
+Libev requires an integer type (suitable for storing C<0> or C<1>) whose
+access is atomic with respect to other threads or signal contexts. No such
+type is easily found in the C language, so you can provide your own type
+that you know is safe for your purposes. It is used both for signal handler "locking"
+as well as for signal and thread safety in C<ev_async> watchers.
+In the absense of this define, libev will use C<sig_atomic_t volatile>
+(from F<signal.h>), which is usually good enough on most platforms.
 =item EV_H
 The name of the F<ev.h> header file used to include it. The default if
-undefined is C<"ev.h"> in F<event.h> and F<ev.c>. This can be used to
+undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
-virtually rename the F<ev.h> header file in case of conflicts.
+used to virtually rename the F<ev.h> header file in case of conflicts.
 =item EV_CONFIG_H
 If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
 F<ev.c>'s idea of where to find the F<config.h> file, similarly to
 C<EV_H>, above.
 =item EV_EVENT_H
 Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
-of how the F<event.h> header can be found, the dfeault is C<"event.h">.
+of how the F<event.h> header can be found, the default is C<"event.h">.
 =item EV_PROTOTYPES
 If defined to be C<0>, then F<ev.h> will not define any function
 prototypes, but still define all the structs and other symbols. This is
 defined to be C<0>, then they are not.
 =item EV_FORK_ENABLE
 If undefined or defined to be C<1>, then fork watchers are supported. If
+defined to be C<0>, then they are not.
+=item EV_ASYNC_ENABLE
+If undefined or defined to be C<1>, then async watchers are supported. If
 defined to be C<0>, then they are not.
 =item EV_MINIMAL
 If you need to shave off some kilobytes of code at the expense of some
 =item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)
 That means that changing a timer costs less than removing/adding them
 as only the relative motion in the event queue has to be paid for.
-=item Starting io/check/prepare/idle/signal/child watchers: O(1)
+=item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)
 These just add the watcher into an array or at the head of a list.
-=item Stopping check/prepare/idle watchers: O(1)
+=item Stopping check/prepare/idle/fork/async watchers: O(1)
 =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
 These watchers are stored in lists then need to be walked to find the
 correct watcher to remove. The lists are usually short (you don't usually
 =item Priority handling: O(number_of_priorities)
 Priorities are implemented by allocating some space for each
 priority. When doing priority-based operations, libev usually has to
 linearly search all the priorities, but starting/stopping and activating
-watchers becomes O(1) w.r.t. prioritiy handling.
+watchers becomes O(1) w.r.t. priority handling.
+=item Sending an ev_async: O(1)
+=item Processing ev_async_send: O(number_of_async_watchers)
+=item Processing signals: O(max_signal_number)
+Sending involves a syscall I<iff> there were no other C<ev_async_send>
+calls in the current loop iteration. Checking for async and signal events
+involves iterating over all running async watchers or all signal numbers.
 =back
 =head1 Win32 platform limitations and workarounds

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.114 by root, Mon Dec 31 01:31:30 2007 UTC vs. Revision 1.131 by root, Tue Feb 19 17:09:28 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.114 by root, Mon Dec 31 01:31:30 2007 UTC vs.
Revision 1.131 by root, Tue Feb 19 17:09:28 2008 UTC