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

Comparing libev/ev.pod (file contents):
Revision 1.322 by root, Sun Oct 24 17:58:41 2010 UTC vs.
Revision 1.334 by root, Mon Oct 25 10:30:23 2010 UTC

 on event-based programming, nor will it introduce event-based programming
 with libev.
 Familiarity with event based programming techniques in general is assumed
 throughout this document.
+=head1 WHAT TO READ WHEN IN A HURRY
+This manual tries to be very detailed, but unfortunately, this also makes
+it very long. If you just want to know the basics of libev, I suggest
+reading L<ANATOMY OF A WATCHER>, then the L<EXAMPLE PROGRAM> above and
+look up the missing functions in L<GLOBAL FUNCTIONS> and the C<ev_io> and
+C<ev_timer> sections in L<WATCHER TYPES>.
 =head1 ABOUT LIBEV
 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
 An event loop is described by a C<struct ev_loop *> (the C<struct> is
 I<not> optional in this case unless libev 3 compatibility is disabled, as
 libev 3 had an C<ev_loop> function colliding with the struct name).
 The library knows two types of such loops, the I<default> loop, which
-supports signals and child events, and dynamically created event loops
+supports child process events, and dynamically created event loops which
-which do not.
+do not.
 =over 4
 =item struct ev_loop *ev_default_loop (unsigned int flags)
 Example: Restrict libev to the select and poll backends, and do not allow
 environment settings to be taken into account:
    ev_default_loop (EVBACKEND_POLL | EVBACKEND_SELECT | EVFLAG_NOENV);
-Example: Use whatever libev has to offer, but make sure that kqueue is
-used if available (warning, breaks stuff, best use only with your own
-private event loop and only if you know the OS supports your types of
-fds):
-   ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
 =item struct ev_loop *ev_loop_new (unsigned int flags)
 This will create and initialise a new event loop object. If the loop
 could not be initialised, returns false.
 Example: Try to create a event loop that uses epoll and nothing else.
    struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
    if (!epoller)
      fatal ("no epoll found here, maybe it hides under your chair");
+Example: Use whatever libev has to offer, but make sure that kqueue is
+used if available.
+   struct ev_loop *loop = ev_loop_new (ev_recommended_backends () | EVBACKEND_KQUEUE);
 =item ev_loop_destroy (loop)
 Destroys an event loop object (frees all memory and kernel state
 etc.). None of the active event watchers will be stopped in the normal
 =item C<EV_FORK>
 The event loop has been resumed in the child process after fork (see
 C<ev_fork>).
+=item C<EV_CLEANUP>
+The event loop is about to be destroyed (see C<ev_cleanup>).
 =item C<EV_ASYNC>
 The given async watcher has been asynchronously notified (see C<ev_async>).
 =item C<EV_CUSTOM>
 =head3 Watcher-Specific Functions and Data Members
 =over 4
-=item ev_fork_init (ev_signal *, callback)
+=item ev_fork_init (ev_fork *, callback)
 Initialises and configures the fork watcher - it has no parameters of any
 kind. There is a C<ev_fork_set> macro, but using it is utterly pointless,
-believe me.
+really.
 =back
+=head2 C<ev_cleanup> - even the best things end
+Cleanup watchers are called just before the event loop is being destroyed
+by a call to C<ev_loop_destroy>.
+While there is no guarantee that the event loop gets destroyed, cleanup
+watchers provide a convenient method to install cleanup hooks for your
+program, worker threads and so on - you just to make sure to destroy the
+loop when you want them to be invoked.
+Cleanup watchers are invoked in the same way as any other watcher. Unlike
+all other watchers, they do not keep a reference to the event loop (which
+makes a lot of sense if you think about it). Like all other watchers, you
+can call libev functions in the callback, except C<ev_cleanup_start>.
+=head3 Watcher-Specific Functions and Data Members
+=over 4
+=item ev_cleanup_init (ev_cleanup *, callback)
+Initialises and configures the cleanup watcher - it has no parameters of
+any kind. There is a C<ev_cleanup_set> macro, but using it is utterly
+pointless, I assure you.
+=back
+Example: Register an atexit handler to destroy the default loop, so any
+cleanup functions are called.
+   static void
+   program_exits (void)
+   {
+     ev_loop_destroy (EV_DEFAULT_UC);
+   }
+   ...
+   atexit (program_exits);
 =head2 C<ev_async> - how to wake up an event loop
 In general, you cannot use an C<ev_run> from multiple threads or other
 structure (guaranteed by POSIX but not by ISO C for example), but it also
 assumes that the same (machine) code can be used to call any watcher
 callback: The watcher callbacks have different type signatures, but libev
 calls them using an C<ev_watcher *> internally.
+=item pointer accesses must be thread-atomic
+Accessing a pointer value must be atomic, it must both be readable and
+writable in one piece - this is the case on all current architectures.
 =item C<sig_atomic_t volatile> must be thread-atomic as well
 The type C<sig_atomic_t volatile> (or whatever is defined as
 C<EV_ATOMIC_T>) must be atomic with respect to accesses from different
 threads. This is not part of the specification for C<sig_atomic_t>, but is
 =back
 =head1 PORTING FROM LIBEV 3.X TO 4.X
-The major version 4 introduced some minor incompatible changes to the API.
+The major version 4 introduced some incompatible changes to the API.
-At the moment, the C<ev.h> header file tries to implement superficial
+At the moment, the C<ev.h> header file provides compatibility definitions
-compatibility, so most programs should still compile. Those might be
+for all changes, so most programs should still compile. The compatibility
-removed in later versions of libev, so better update early than late.
+layer might be removed in later versions of libev, so better update to the
+new API early than late.
 =over 4
+=item C<EV_COMPAT3> backwards compatibility mechanism
+The backward compatibility mechanism can be controlled by
+C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING>
+section.
 =item C<ev_default_destroy> and C<ev_default_fork> have been removed
 These calls can be replaced easily by their C<ev_loop_xxx> counterparts:
-   ev_loop_destroy (EV_DEFAULT);
+   ev_loop_destroy (EV_DEFAULT_UC);
    ev_loop_fork (EV_DEFAULT);
 =item function/symbol renames
 A number of functions and symbols have been renamed:
 ev_loop> anymore and C<EV_TIMER> now follows the same naming scheme
 as all other watcher types. Note that C<ev_loop_fork> is still called
 C<ev_loop_fork> because it would otherwise clash with the C<ev_fork>
 typedef.
-=item C<EV_COMPAT3> backwards compatibility mechanism
-The backward compatibility mechanism can be controlled by
-C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING>
-section.
 =item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
 The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
 mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
 and work, but the library code will of course be larger.
 =back
 =head1 AUTHOR
-Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.
+Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael
+Magnusson and Emanuele Giaquinta.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.322 by root, Sun Oct 24 17:58:41 2010 UTC vs. Revision 1.334 by root, Mon Oct 25 10:30:23 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.322 by root, Sun Oct 24 17:58:41 2010 UTC vs.
Revision 1.334 by root, Mon Oct 25 10:30:23 2010 UTC