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

Comparing libev/ev.pod (file contents):
Revision 1.310 by root, Thu Oct 21 12:32:47 2010 UTC vs.
Revision 1.316 by root, Fri Oct 22 09:34:01 2010 UTC

 =back
 =head1 FUNCTIONS CONTROLLING THE EVENT LOOP
 An event loop is described by a C<struct ev_loop *> (the C<struct> is
-I<not> optional in case unless libev 3 compatibility is disabled, as libev
+I<not> optional in this case unless libev 3 compatibility is disabled, as
-3 had an C<ev_loop> function colliding with the struct name).
+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
 which do not.
 =item ev_invoke_pending (loop)
 This call will simply invoke all pending watchers while resetting their
 pending state. Normally, C<ev_run> does this automatically when required,
-but when overriding the invoke callback this call comes handy.
+but when overriding the invoke callback this call comes handy. This
+function can be invoked from a watcher - this can be useful for example
+when you want to do some lengthy calculation and want to pass further
+event handling to another thread (you still have to make sure only one
+thread executes within C<ev_invoke_pending> or C<ev_run> of course).
 =item int ev_pending_count (loop)
 Returns the number of pending watchers - zero indicates that no watchers
 are pending.
 In the following description, uppercase C<TYPE> in names stands for the
 watcher type, e.g. C<ev_TYPE_start> can mean C<ev_timer_start> for timer
 watchers and C<ev_io_start> for I/O watchers.
-A watcher is a structure that you create and register to record your
+A watcher is an opaque structure that you allocate and register to record
-interest in some event. For instance, if you want to wait for STDIN to
+your interest in some event. To make a concrete example, imagine you want
-become readable, you would create an C<ev_io> watcher for that:
+to wait for STDIN to become readable, you would create an C<ev_io> watcher
+for that:
    static void my_cb (struct ev_loop *loop, ev_io *w, int revents)
    {
      ev_io_stop (w);
      ev_break (loop, EVBREAK_ALL);
 stack).
 Each watcher has an associated watcher structure (called C<struct ev_TYPE>
 or simply C<ev_TYPE>, as typedefs are provided for all watcher structs).
-Each watcher structure must be initialised by a call to C<ev_init
+Each watcher structure must be initialised by a call to C<ev_init (watcher
-(watcher *, callback)>, which expects a callback to be provided. This
+*, callback)>, which expects a callback to be provided. This callback is
-callback gets invoked each time the event occurs (or, in the case of I/O
+invoked each time the event occurs (or, in the case of I/O watchers, each
-watchers, each time the event loop detects that the file descriptor given
+time the event loop detects that the file descriptor given is readable
-is readable and/or writable).
+and/or writable).
 Each watcher type further has its own C<< ev_TYPE_set (watcher *, ...) >>
 macro to configure it, with arguments specific to the watcher type. There
 is also a macro to combine initialisation and setting in one call: C<<
 ev_TYPE_init (watcher *, callback, ...) >>.
 example it might indicate that a fd is readable or writable, and if your
 callbacks is well-written it can just attempt the operation and cope with
 the error from read() or write(). This will not work in multi-threaded
 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
 =head3 C<kqueue> is buggy
 The kqueue syscall is broken in all known versions - most versions support
 only sockets, many support pipes.
-Libev tries to work around this by not using C<kqueue> by default on
+Libev tries to work around this by not using C<kqueue> by default on this
-this rotten platform, but of course you can still ask for it when creating
+rotten platform, but of course you can still ask for it when creating a
-a loop.
+loop - embedding a socket-only kqueue loop into a select-based one is
+probably going to work well.
 =head3 C<poll> is buggy
 Instead of fixing C<kqueue>, Apple replaced their (working) C<poll>
 implementation by something calling C<kqueue> internally around the 10.5.6
 =head3 C<errno> reentrancy
 The default compile environment on Solaris is unfortunately so
 thread-unsafe that you can't even use components/libraries compiled
-without C<-D_REENTRANT> (as long as they use C<errno>), which, of course,
+without C<-D_REENTRANT> in a threaded program, which, of course, isn't
-isn't defined by default.
+defined by default. A valid, if stupid, implementation choice.
 If you want to use libev in threaded environments you have to make sure
 it's compiled with C<_REENTRANT> defined.
 =head3 Event port backend
-The scalable event interface for Solaris is called "event ports". Unfortunately,
+The scalable event interface for Solaris is called "event
-this mechanism is very buggy. If you run into high CPU usage, your program
+ports". Unfortunately, this mechanism is very buggy in all major
+releases. If you run into high CPU usage, your program freezes or you get
-freezes or you get a large number of spurious wakeups, make sure you have
+a large number of spurious wakeups, make sure you have all the relevant
-all the relevant and latest kernel patches applied. No, I don't know which
+and latest kernel patches applied. No, I don't know which ones, but there
-ones, but there are multiple ones.
+are multiple ones to apply, and afterwards, event ports actually work
+great.
 If you can't get it to work, you can try running the program by setting
 the environment variable C<LIBEV_FLAGS=3> to only allow C<poll> and
 C<select> backends.
 =head2 AIX POLL BUG
 AIX unfortunately has a broken C<poll.h> header. Libev works around
 this by trying to avoid the poll backend altogether (i.e. it's not even
 compiled in), which normally isn't a big problem as C<select> works fine
-with large bitsets, and AIX is dead anyway.
+with large bitsets on AIX, and AIX is dead anyway.
 =head2 WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS
 =head3 General issues
 =over 4
 =item active
-A watcher is active as long as it has been started (has been attached to
+A watcher is active as long as it has been started and not yet stopped.
-an event loop) but not yet stopped (disassociated from the event loop).
+See L<WATCHER STATES> for details.
 =item application
 In this document, an application is whatever is using libev.
+=item backend
+The part of the code dealing with the operating system interfaces.
 =item callback
 The address of a function that is called when some event has been
 detected. Callbacks are being passed the event loop, the watcher that
 received the event, and the actual event bitset.
-=item callback invocation
+=item callback/watcher invocation
 The act of calling the callback associated with a watcher.
 =item event
 The model used to describe how an event loop handles and processes
 watchers and events.
 =item pending
-A watcher is pending as soon as the corresponding event has been detected,
+A watcher is pending as soon as the corresponding event has been
-and stops being pending as soon as the watcher will be invoked or its
+detected. See L<WATCHER STATES> for details.
-pending status is explicitly cleared by the application.
-A watcher can be pending, but not active. Stopping a watcher also clears
-its pending status.
 =item real time
 The physical time that is observed. It is apparently strictly monotonic :)
 =item watcher
 A data structure that describes interest in certain events. Watchers need
 to be started (attached to an event loop) before they can receive events.
-=item watcher invocation
-The act of calling the callback associated with a watcher.
 =back
 =head1 AUTHOR
 Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael Magnusson.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.310 by root, Thu Oct 21 12:32:47 2010 UTC vs. Revision 1.316 by root, Fri Oct 22 09:34:01 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.310 by root, Thu Oct 21 12:32:47 2010 UTC vs.
Revision 1.316 by root, Fri Oct 22 09:34:01 2010 UTC