[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.320 by root, Fri Oct 22 10:48:54 2010 UTC

 this argument.
 =head2 TIME REPRESENTATION
 Libev represents time as a single floating point number, representing
-the (fractional) number of seconds since the (POSIX) epoch (in practise
+the (fractional) number of seconds since the (POSIX) epoch (in practice
 somewhere near the beginning of 1970, details are complicated, don't
 ask). This type is called C<ev_tstamp>, which is what you should use
 too. It usually aliases to the C<double> type in C. When you need to do
 any calculations on it, you should treat it as some floating point value.
 =item ev_tstamp ev_time ()
 Returns the current time as libev would use it. Please note that the
 C<ev_now> function is usually faster and also often returns the timestamp
-you actually want to know.
+you actually want to know. Also interetsing is the combination of
+C<ev_update_now> and C<ev_now>.
 =item ev_sleep (ev_tstamp interval)
 Sleep for the given interval: The current thread will be blocked until
 either it is interrupted or the given time interval has passed. Basically
 as this indicates an incompatible change. Minor versions are usually
 compatible to older versions, so a larger minor version alone is usually
 not a problem.
 Example: Make sure we haven't accidentally been linked against the wrong
-version (note, however, that this will not detect ABI mismatches :).
+version (note, however, that this will not detect other ABI mismatches,
+such as LFS or reentrancy).
    assert (("libev version mismatch",
             ev_version_major () == EV_VERSION_MAJOR
             && ev_version_minor () >= EV_VERSION_MINOR));
    assert (("sorry, no epoll, no sex",
             ev_supported_backends () & EVBACKEND_EPOLL));
 =item unsigned int ev_recommended_backends ()
-Return the set of all backends compiled into this binary of libev and also
+Return the set of all backends compiled into this binary of libev and
-recommended for this platform. This set is often smaller than the one
+also recommended for this platform, meaning it will work for most file
+descriptor types. This set is often smaller than the one returned by
-returned by C<ev_supported_backends>, as for example kqueue is broken on
+C<ev_supported_backends>, as for example kqueue is broken on most BSDs
-most BSDs and will not be auto-detected unless you explicitly request it
+and will not be auto-detected unless you explicitly request it (assuming
-(assuming you know what you are doing). This is the set of backends that
+you know what you are doing). This is the set of backends that libev will
-libev will probe for if you specify no backends explicitly.
+probe for if you specify no backends explicitly.
 =item unsigned int ev_embeddable_backends ()
 Returns the set of backends that are embeddable in other event loops. This
-is the theoretical, all-platform, value. To find which backends
+value is platform-specific but can include backends not available on the
-might be supported on the current system, you would need to look at
+current system. To find which embeddable backends might be supported on
-C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
+the current system, you would need to look at C<ev_embeddable_backends ()
-recommended ones.
+& ev_supported_backends ()>, likewise for recommended ones.
 See the description of C<ev_embed> watchers for more info.
 =item ev_set_allocator (void *(*cb)(void *ptr, long size)) [NOT REENTRANT]
 =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.320 by root, Fri Oct 22 10:48:54 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.320 by root, Fri Oct 22 10:48:54 2010 UTC