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

Comparing libev/ev.pod (file contents):
Revision 1.134 by root, Sat Mar 8 07:04:56 2008 UTC vs.
Revision 1.137 by root, Sun Mar 16 16:42:56 2008 UTC

   #include <ev.h>
 =head2 EXAMPLE PROGRAM
+  // a single header file is required
   #include <ev.h>
+  // every watcher type has its own typedef'd struct
+  // with the name ev_<type>
   ev_io stdin_watcher;
   ev_timer timeout_watcher;
+  // all watcher callbacks have a similar signature
-  /* called when data readable on stdin */
+  // this callback is called when data is readable on stdin
   static void
   stdin_cb (EV_P_ struct ev_io *w, int revents)
   {
-    /* puts ("stdin ready"); */
+    puts ("stdin ready");
-    ev_io_stop (EV_A_ w); /* just a syntax example */
+    // for one-shot events, one must manually stop the watcher
-    ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */
+    // with its corresponding stop function.
+    ev_io_stop (EV_A_ w);
+    // this causes all nested ev_loop's to stop iterating
+    ev_unloop (EV_A_ EVUNLOOP_ALL);
   }
+  // another callback, this time for a time-out
   static void
   timeout_cb (EV_P_ struct ev_timer *w, int revents)
   {
-    /* puts ("timeout"); */
+    puts ("timeout");
-    ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */
+    // this causes the innermost ev_loop to stop iterating
+    ev_unloop (EV_A_ EVUNLOOP_ONE);
   }
   int
   main (void)
   {
+    // use the default event loop unless you have special needs
     struct ev_loop *loop = ev_default_loop (0);
-    /* initialise an io watcher, then start it */
+    // initialise an io watcher, then start it
+    // this one will watch for stdin to become readable
     ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ);
     ev_io_start (loop, &stdin_watcher);
+    // initialise a timer watcher, then start it
-    /* simple non-repeating 5.5 second timeout */
+    // simple non-repeating 5.5 second timeout
     ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
     ev_timer_start (loop, &timeout_watcher);
-    /* loop till timeout or data ready */
+    // now wait for events to arrive
     ev_loop (loop, 0);
+    // unloop was called, so exit
     return 0;
   }
 =head1 DESCRIPTION
-The newest version of this document is also available as a html-formatted
+The newest version of this document is also available as an html-formatted
 web page you might find easier to navigate when reading it for the first
 time: L<http://cvs.schmorp.de/libev/ev.html>.
 Libev is an event loop: you register interest in certain events (such as a
 file descriptor being readable or a timeout occurring), and it will manage
 L<benchmark|http://libev.schmorp.de/bench.html> comparing it to libevent
 for example).
 =head2 CONVENTIONS
-Libev is very configurable. In this manual the default configuration will
+Libev is very configurable. In this manual the default (and most common)
-be described, which supports multiple event loops. For more info about
+configuration will be described, which supports multiple event loops. For
-various configuration options please have a look at B<EMBED> section in
+more info about various configuration options please have a look at
-this manual. If libev was configured without support for multiple event
+B<EMBED> section in this manual. If libev was configured without support
-loops, then all functions taking an initial argument of name C<loop>
+for multiple event loops, then all functions taking an initial argument of
-(which is always of type C<struct ev_loop *>) will not have this argument.
+name C<loop> (which is always of type C<struct ev_loop *>) will not have
+this argument.
 =head2 TIME REPRESENTATION
 Libev represents time as a single floating point number, representing the
 (fractional) number of seconds since the (POSIX) epoch (somewhere near
 enabling this flag.
 This works by calling C<getpid ()> on every iteration of the loop,
 and thus this might slow down your event loop if you do a lot of loop
 iterations and little real work, but is usually not noticeable (on my
-Linux system for example, C<getpid> is actually a simple 5-insn sequence
+GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
-without a syscall and thus I<very> fast, but my Linux system also has
+without a syscall and thus I<very> fast, but my GNU/Linux system also has
 C<pthread_atfork> which is even faster).
 The big advantage of this flag is that you can forget about fork (and
 forget about forgetting to tell libev about forking) when you use this
 flag.
 with the kernel (thus it coexists with your own signal handlers as long
 as you don't register any with libev). Similarly, when the last signal
 watcher for a signal is stopped libev will reset the signal handler to
 SIG_DFL (regardless of what it was set to before).
+If possible and supported, libev will install its handlers with
+C<SA_RESTART> behaviour enabled, so syscalls should not be unduly
+interrupted. If you have a problem with syscalls getting interrupted by
+signals you can block all signals in an C<ev_check> watcher and unblock
+them in an C<ev_prepare> watcher.
 =head3 Watcher-Specific Functions and Data Members
 =over 4
 =item ev_signal_init (ev_signal *, callback, int signum)
 reader). Inotify will be used to give hints only and should not change the
 semantics of C<ev_stat> watchers, which means that libev sometimes needs
 to fall back to regular polling again even with inotify, but changes are
 usually detected immediately, and if the file exists there will be no
 polling.
+=head3 ABI Issues (Largefile Support)
+Libev by default (unless the user overrides this) uses the default
+compilation environment, which means that on systems with optionally
+disabled large file support, you get the 32 bit version of the stat
+structure. When using the library from programs that change the ABI to
+use 64 bit file offsets the programs will fail. In that case you have to
+compile libev with the same flags to get binary compatibility. This is
+obviously the case with any flags that change the ABI, but the problem is
+most noticably with ev_stat and largefile support.
 =head3 Inotify
 When C<inotify (7)> support has been compiled into libev (generally only
 available on Linux) and present at runtime, it will be used to speed up
       io.start (fd, ev::READ);
     }
   };
+=head1 OTHER LANGUAGE BINDINGS
+Libev does not offer other language bindings itself, but bindings for a
+numbe rof languages exist in the form of third-party packages. If you know
+any interesting language binding in addition to the ones listed here, drop
+me a note.
+=over 4
+=item Perl
+The EV module implements the full libev API and is actually used to test
+libev. EV is developed together with libev. Apart from the EV core module,
+there are additional modules that implement libev-compatible interfaces
+to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the
+C<libglib> event core (C<Glib::EV> and C<EV::Glib>).
+It can be found and installed via CPAN, its homepage is found at
+L<http://software.schmorp.de/pkg/EV>.
+=item Ruby
+Tony Arcieri has written a ruby extension that offers access to a subset
+of the libev API and adds filehandle abstractions, asynchronous DNS and
+more on top of it. It can be found via gem servers. Its homepage is at
+L<http://rev.rubyforge.org/>.
+=item D
+Leandro Lucarella has written a D language binding (F<ev.d>) for libev, to
+be found at L<http://git.llucax.com.ar/?p=software/ev.d.git;a=summary>.
+=back
 =head1 MACRO MAGIC
 Libev can be compiled with a variety of options, the most fundamantal
 of which is C<EV_MULTIPLICITY>. This option determines whether (most)
 functions and callbacks have an initial C<struct ev_loop *> argument.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.134 by root, Sat Mar 8 07:04:56 2008 UTC vs. Revision 1.137 by root, Sun Mar 16 16:42:56 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.134 by root, Sat Mar 8 07:04:56 2008 UTC vs.
Revision 1.137 by root, Sun Mar 16 16:42:56 2008 UTC