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

Comparing libev/ev.pod (file contents):
Revision 1.119 by root, Tue Jan 15 04:07:37 2008 UTC vs.
Revision 1.123 by root, Thu Jan 31 13:25:10 2008 UTC

 =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
 ran out of memory, a file descriptor was found to be closed or any other
 =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 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 using, so you cna provide your own type that you know is safe.
+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>, F<ev.c> and F<ev++.h>. This can be
 used to virtually rename the F<ev.h> header file in case of conflicts.
 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

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.119 by root, Tue Jan 15 04:07:37 2008 UTC vs. Revision 1.123 by root, Thu Jan 31 13:25:10 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.119 by root, Tue Jan 15 04:07:37 2008 UTC vs.
Revision 1.123 by root, Thu Jan 31 13:25:10 2008 UTC