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

Comparing libev/ev.pod (file contents):
Revision 1.323 by root, Sun Oct 24 18:01:26 2010 UTC vs.
Revision 1.335 by root, Mon Oct 25 10:32:05 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)
 =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>
 programs, though, as the fd could already be closed and reused for another
 thing, so beware.
 =back
-=head2 WATCHER STATES
-There are various watcher states mentioned throughout this manual -
-active, pending and so on. In this section these states and the rules to
-transition between them will be described in more detail - and while these
-rules might look complicated, they usually do "the right thing".
-=over 4
-=item initialiased
-Before a watcher can be registered with the event looop it has to be
-initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
-C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
-In this state it is simply some block of memory that is suitable for use
-in an event loop. It can be moved around, freed, reused etc. at will.
-=item started/running/active
-Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
-property of the event loop, and is actively waiting for events. While in
-this state it cannot be accessed (except in a few documented ways), moved,
-freed or anything else - the only legal thing is to keep a pointer to it,
-and call libev functions on it that are documented to work on active watchers.
-=item pending
-If a watcher is active and libev determines that an event it is interested
-in has occurred (such as a timer expiring), it will become pending. It will
-stay in this pending state until either it is stopped or its callback is
-about to be invoked, so it is not normally pending inside the watcher
-callback.
-The watcher might or might not be active while it is pending (for example,
-an expired non-repeating timer can be pending but no longer active). If it
-is stopped, it can be freely accessed (e.g. by calling C<ev_TYPE_set>),
-but it is still property of the event loop at this time, so cannot be
-moved, freed or reused. And if it is active the rules described in the
-previous item still apply.
-It is also possible to feed an event on a watcher that is not active (e.g.
-via C<ev_feed_event>), in which case it becomes pending without being
-active.
-=item stopped
-A watcher can be stopped implicitly by libev (in which case it might still
-be pending), or explicitly by calling its C<ev_TYPE_stop> function. The
-latter will clear any pending state the watcher might be in, regardless
-of whether it was active or not, so stopping a watcher explicitly before
-freeing it is often a good idea.
-While stopped (and not pending) the watcher is essentially in the
-initialised state, that is it can be reused, moved, modified in any way
-you wish.
-=back
 =head2 GENERIC WATCHER FUNCTIONS
 =over 4
 =item C<ev_init> (ev_TYPE *watcher, callback)
 See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
 functions that do not need a watcher.
 =back
 =head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
 Each watcher has, by default, a member C<void *data> that you can change
 and read at any time: libev will completely ignore it. This can be used
    t2_cb (EV_P_ ev_timer *w, int revents)
    {
      struct my_biggy big = (struct my_biggy *)
        (((char *)w) - offsetof (struct my_biggy, t2));
    }
+=head2 WATCHER STATES
+There are various watcher states mentioned throughout this manual -
+active, pending and so on. In this section these states and the rules to
+transition between them will be described in more detail - and while these
+rules might look complicated, they usually do "the right thing".
+=over 4
+=item initialiased
+Before a watcher can be registered with the event looop it has to be
+initialised. This can be done with a call to C<ev_TYPE_init>, or calls to
+C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function.
+In this state it is simply some block of memory that is suitable for use
+in an event loop. It can be moved around, freed, reused etc. at will.
+=item started/running/active
+Once a watcher has been started with a call to C<ev_TYPE_start> it becomes
+property of the event loop, and is actively waiting for events. While in
+this state it cannot be accessed (except in a few documented ways), moved,
+freed or anything else - the only legal thing is to keep a pointer to it,
+and call libev functions on it that are documented to work on active watchers.
+=item pending
+If a watcher is active and libev determines that an event it is interested
+in has occurred (such as a timer expiring), it will become pending. It will
+stay in this pending state until either it is stopped or its callback is
+about to be invoked, so it is not normally pending inside the watcher
+callback.
+The watcher might or might not be active while it is pending (for example,
+an expired non-repeating timer can be pending but no longer active). If it
+is stopped, it can be freely accessed (e.g. by calling C<ev_TYPE_set>),
+but it is still property of the event loop at this time, so cannot be
+moved, freed or reused. And if it is active the rules described in the
+previous item still apply.
+It is also possible to feed an event on a watcher that is not active (e.g.
+via C<ev_feed_event>), in which case it becomes pending without being
+active.
+=item stopped
+A watcher can be stopped implicitly by libev (in which case it might still
+be pending), or explicitly by calling its C<ev_TYPE_stop> function. The
+latter will clear any pending state the watcher might be in, regardless
+of whether it was active or not, so stopping a watcher explicitly before
+freeing it is often a good idea.
+While stopped (and not pending) the watcher is essentially in the
+initialised state, that is it can be reused, moved, modified in any way
+you wish.
+=back
 =head2 WATCHER PRIORITY MODELS
 Many event loops support I<watcher priorities>, which are usually small
 integers that influence the ordering of event callback invocation
 =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.323 by root, Sun Oct 24 18:01:26 2010 UTC vs. Revision 1.335 by root, Mon Oct 25 10:32:05 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.323 by root, Sun Oct 24 18:01:26 2010 UTC vs.
Revision 1.335 by root, Mon Oct 25 10:32:05 2010 UTC