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

Comparing libev/ev.pod (file contents):
Revision 1.286 by root, Tue Mar 16 00:26:41 2010 UTC vs.
Revision 1.290 by root, Tue Mar 16 18:03:01 2010 UTC

    ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
 =item struct ev_loop *ev_loop_new (unsigned int flags)
 Similar to C<ev_default_loop>, but always creates a new event loop that is
-always distinct from the default loop. Unlike the default loop, it cannot
+always distinct from the default loop.
-handle signal and child watchers, and attempts to do so will be greeted by
-undefined behaviour (or a failed assertion if assertions are enabled).
-Note that this function I<is> thread-safe, and the recommended way to use
+Note that this function I<is> thread-safe, and one common way to use
 libev with threads is indeed to create one loop per thread, and using the
 default loop in the "main" or "initial" thread.
 Example: Try to create a event loop that uses epoll and nothing else.
    if (!epoller)
      fatal ("no epoll found here, maybe it hides under your chair");
 =item ev_default_destroy ()
-Destroys the default loop again (frees all memory and kernel state
+Destroys the default loop (frees all memory and kernel state etc.). None
-etc.). None of the active event watchers will be stopped in the normal
+of the active event watchers will be stopped in the normal sense, so
-sense, so e.g. C<ev_is_active> might still return true. It is your
+e.g. C<ev_is_active> might still return true. It is your responsibility to
-responsibility to either stop all watchers cleanly yourself I<before>
+either stop all watchers cleanly yourself I<before> calling this function,
-calling this function, or cope with the fact afterwards (which is usually
+or cope with the fact afterwards (which is usually the easiest thing, you
-the easiest thing, you can just ignore the watchers and/or C<free ()> them
+can just ignore the watchers and/or C<free ()> them for example).
-for example).
 Note that certain global state, such as signal state (and installed signal
 handlers), will not be freed by this function, and related watchers (such
 as signal and child watchers) would need to be stopped manually.
 =item C<EV_WRITE>
 The file descriptor in the C<ev_io> watcher has become readable and/or
 writable.
-=item C<EV_TIMEOUT>
+=item C<EV_TIMER>
 The C<ev_timer> watcher has timed out.
 =item C<EV_PERIODIC>
 to the current time (meaning we just have some activity :), then call the
 callback, which will "do the right thing" and start the timer:
    ev_init (timer, callback);
    last_activity = ev_now (loop);
-   callback (loop, timer, EV_TIMEOUT);
+   callback (loop, timer, EV_TIMER);
 And when there is some activity, simply store the current time in
 C<last_activity>, no libev calls at all:
    last_actiivty = ev_now (loop);
 If C<timeout> is less than 0, then no timeout watcher will be
 started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
 repeat = 0) will be started. C<0> is a valid timeout.
-The callback has the type C<void (*cb)(int revents, void *arg)> and gets
+The callback has the type C<void (*cb)(int revents, void *arg)> and is
 passed an C<revents> set like normal event callbacks (a combination of
-C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg>
+C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
 value passed to C<ev_once>. Note that it is possible to receive I<both>
 a timeout and an io event at the same time - you probably should give io
 events precedence.
 Example: wait up to ten seconds for data to appear on STDIN_FILENO.
    static void stdin_ready (int revents, void *arg)
    {
      if (revents & EV_READ)
        /* stdin might have data for us, joy! */;
-     else if (revents & EV_TIMEOUT)
+     else if (revents & EV_TIMER)
        /* doh, nothing entered */;
    }
    ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
 If you need to shave off some kilobytes of code at the expense of some
 speed (but with the full API), you can define this symbol to request
 certain subsets of functionality. The default is to enable all features
 that can be enabled on the platform.
-Note that using autoconf will usually override most of the features, so
-using this symbol makes sense mostly when embedding libev.
 A typical way to use this symbol is to define it to C<0> (or to a bitset
 with some broad features you want) and then selectively re-enable
 additional parts you want, for example if you want everything minimal,
 but multiple event loop support, async and child watchers and the poll
 backend, use this:
 =item C<4> - full API configuration
 This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
 enables multiplicity (C<EV_MULTIPLICITY>=1).
+=item C<8> - full API
-It also enables a lot of the "lesser used" core API functions. See C<ev.h>
+This enables a lot of the "lesser used" API functions. See C<ev.h> for
-for details on which parts of the API are still available without this
+details on which parts of the API are still available without this
 feature, and do not complain if this subset changes over time.
-=item C<8> - enable all optional watcher types
+=item C<16> - enable all optional watcher types
 Enables all optional watcher types.  If you want to selectively enable
 only some watcher types other than I/O and timers (e.g. prepare,
 embed, async, child...) you can enable them manually by defining
 C<EV_watchertype_ENABLE> to C<1> instead.
-=item C<16> - enable all backends
+=item C<32> - enable all backends
 This enables all backends - without this feature, you need to enable at
 least one backend manually (C<EV_USE_SELECT> is a good choice).
-=item C<32> - enable OS-specific "helper" APIs
+=item C<64> - enable OS-specific "helper" APIs
 Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
 default.
 =back
 Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
-reduces the compiled size of libev from 24.7Kb to 6.5Kb on my GNU/Linux
+reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb
-amd64 system, while still giving you I/O watchers, timers and monotonic
+code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
-clock support.
+watchers, timers and monotonic clock support.
 With an intelligent-enough linker (gcc+binutils are intelligent enough
 when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
 your program might be left out as well - a binary starting a timer and an
 I/O watcher then might come out at only 5Kb.
 file.
 The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
 that everybody includes and which overrides some configure choices:
-   #define EV_FEATURES 0
+   #define EV_FEATURES 8
    #define EV_USE_SELECT 1
+   #define EV_PREPARE_ENABLE 1
+   #define EV_IDLE_ENABLE 1
+   #define EV_SIGNAL_ENABLE 1
+   #define EV_CHILD_ENABLE 1
+   #define EV_USE_STDEXCEPT 0
    #define EV_CONFIG_H <config.h>
    #include "ev++.h"
 And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
 involves iterating over all running async watchers or all signal numbers.
 =back
+=head1 PORTING FROM 3.X TO 4.X
+The major version 4 introduced some minor incompatible changes to the API.
+=over 4
+=item C<EV_TIMEOUT> replaced by C<EV_TIMER> in C<revents>
+This is a simple rename - all other watcher types use their name
+as revents flag, and now C<ev_timer> does, too.
+Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions
+and continue to be present for the forseeable future, so this is mostly a
+documentation change.
+=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 GLOSSARY
 =over 4
 =item active
 A change of state of some external event, such as data now being available
 for reading on a file descriptor, time having passed or simply not having
 any other events happening anymore.
 In libev, events are represented as single bits (such as C<EV_READ> or
-C<EV_TIMEOUT>).
+C<EV_TIMER>).
 =item event library
 A software package implementing an event model and loop.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.286 by root, Tue Mar 16 00:26:41 2010 UTC vs. Revision 1.290 by root, Tue Mar 16 18:03:01 2010 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.286 by root, Tue Mar 16 00:26:41 2010 UTC vs.
Revision 1.290 by root, Tue Mar 16 18:03:01 2010 UTC