ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.61 by root, Thu Nov 29 12:21:05 2007 UTC vs.
Revision 1.72 by root, Fri Dec 7 20:19:16 2007 UTC

47 47
48 return 0; 48 return 0;
49 } 49 }
50 50
51=head1 DESCRIPTION 51=head1 DESCRIPTION
52
53The newest version of this document is also available as a html-formatted
54web page you might find easier to navigate when reading it for the first
55time: L<http://cvs.schmorp.de/libev/ev.html>.
52 56
53Libev is an event loop: you register interest in certain events (such as a 57Libev is an event loop: you register interest in certain events (such as a
54file descriptor being readable or a timeout occuring), and it will manage 58file descriptor being readable or a timeout occuring), and it will manage
55these event sources and provide your program with events. 59these event sources and provide your program with events.
56 60
266C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will 270C<LIBEV_FLAGS>. Otherwise (the default), this environment variable will
267override the flags completely if it is found in the environment. This is 271override the flags completely if it is found in the environment. This is
268useful to try out specific backends to test their performance, or to work 272useful to try out specific backends to test their performance, or to work
269around bugs. 273around bugs.
270 274
275=item C<EVFLAG_FORKCHECK>
276
277Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after
278a fork, you can also make libev check for a fork in each iteration by
279enabling this flag.
280
281This works by calling C<getpid ()> on every iteration of the loop,
282and thus this might slow down your event loop if you do a lot of loop
283iterations and little real work, but is usually not noticeable (on my
284Linux system for example, C<getpid> is actually a simple 5-insn sequence
285without a syscall and thus I<very> fast, but my Linux system also has
286C<pthread_atfork> which is even faster).
287
288The big advantage of this flag is that you can forget about fork (and
289forget about forgetting to tell libev about forking) when you use this
290flag.
291
292This flag setting cannot be overriden or specified in the C<LIBEV_FLAGS>
293environment variable.
294
271=item C<EVBACKEND_SELECT> (value 1, portable select backend) 295=item C<EVBACKEND_SELECT> (value 1, portable select backend)
272 296
273This is your standard select(2) backend. Not I<completely> standard, as 297This is your standard select(2) backend. Not I<completely> standard, as
274libev tries to roll its own fd_set with no limits on the number of fds, 298libev tries to roll its own fd_set with no limits on the number of fds,
275but if that fails, expect a fairly low limit on the number of fds when 299but if that fails, expect a fairly low limit on the number of fds when
409=item ev_loop_fork (loop) 433=item ev_loop_fork (loop)
410 434
411Like C<ev_default_fork>, but acts on an event loop created by 435Like C<ev_default_fork>, but acts on an event loop created by
412C<ev_loop_new>. Yes, you have to call this on every allocated event loop 436C<ev_loop_new>. Yes, you have to call this on every allocated event loop
413after fork, and how you do this is entirely your own problem. 437after fork, and how you do this is entirely your own problem.
438
439=item unsigned int ev_loop_count (loop)
440
441Returns the count of loop iterations for the loop, which is identical to
442the number of times libev did poll for new events. It starts at C<0> and
443happily wraps around with enough iterations.
444
445This value can sometimes be useful as a generation counter of sorts (it
446"ticks" the number of loop iterations), as it roughly corresponds with
447C<ev_prepare> and C<ev_check> calls.
414 448
415=item unsigned int ev_backend (loop) 449=item unsigned int ev_backend (loop)
416 450
417Returns one of the C<EVBACKEND_*> flags indicating the event backend in 451Returns one of the C<EVBACKEND_*> flags indicating the event backend in
418use. 452use.
714=item ev_cb_set (ev_TYPE *watcher, callback) 748=item ev_cb_set (ev_TYPE *watcher, callback)
715 749
716Change the callback. You can change the callback at virtually any time 750Change the callback. You can change the callback at virtually any time
717(modulo threads). 751(modulo threads).
718 752
753=item ev_set_priority (ev_TYPE *watcher, priority)
754
755=item int ev_priority (ev_TYPE *watcher)
756
757Set and query the priority of the watcher. The priority is a small
758integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
759(default: C<-2>). Pending watchers with higher priority will be invoked
760before watchers with lower priority, but priority will not keep watchers
761from being executed (except for C<ev_idle> watchers).
762
763This means that priorities are I<only> used for ordering callback
764invocation after new events have been received. This is useful, for
765example, to reduce latency after idling, or more often, to bind two
766watchers on the same event and make sure one is called first.
767
768If you need to suppress invocation when higher priority events are pending
769you need to look at C<ev_idle> watchers, which provide this functionality.
770
771The default priority used by watchers when no priority has been set is
772always C<0>, which is supposed to not be too high and not be too low :).
773
774Setting a priority outside the range of C<EV_MINPRI> to C<EV_MAXPRI> is
775fine, as long as you do not mind that the priority value you query might
776or might not have been adjusted to be within valid range.
777
719=back 778=back
720 779
721 780
722=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 781=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
723 782
828it is best to always use non-blocking I/O: An extra C<read>(2) returning 887it is best to always use non-blocking I/O: An extra C<read>(2) returning
829C<EAGAIN> is far preferable to a program hanging until some data arrives. 888C<EAGAIN> is far preferable to a program hanging until some data arrives.
830 889
831If you cannot run the fd in non-blocking mode (for example you should not 890If you cannot run the fd in non-blocking mode (for example you should not
832play around with an Xlib connection), then you have to seperately re-test 891play around with an Xlib connection), then you have to seperately re-test
833wether a file descriptor is really ready with a known-to-be good interface 892whether a file descriptor is really ready with a known-to-be good interface
834such as poll (fortunately in our Xlib example, Xlib already does this on 893such as poll (fortunately in our Xlib example, Xlib already does this on
835its own, so its quite safe to use). 894its own, so its quite safe to use).
836 895
837=over 4 896=over 4
838 897
1321 ev_stat_start (loop, &passwd); 1380 ev_stat_start (loop, &passwd);
1322 1381
1323 1382
1324=head2 C<ev_idle> - when you've got nothing better to do... 1383=head2 C<ev_idle> - when you've got nothing better to do...
1325 1384
1326Idle watchers trigger events when there are no other events are pending 1385Idle watchers trigger events when no other events of the same or higher
1327(prepare, check and other idle watchers do not count). That is, as long 1386priority are pending (prepare, check and other idle watchers do not
1328as your process is busy handling sockets or timeouts (or even signals, 1387count).
1329imagine) it will not be triggered. But when your process is idle all idle 1388
1330watchers are being called again and again, once per event loop iteration - 1389That is, as long as your process is busy handling sockets or timeouts
1390(or even signals, imagine) of the same or higher priority it will not be
1391triggered. But when your process is idle (or only lower-priority watchers
1392are pending), the idle watchers are being called once per event loop
1331until stopped, that is, or your process receives more events and becomes 1393iteration - until stopped, that is, or your process receives more events
1332busy. 1394and becomes busy again with higher priority stuff.
1333 1395
1334The most noteworthy effect is that as long as any idle watchers are 1396The most noteworthy effect is that as long as any idle watchers are
1335active, the process will not block when waiting for new events. 1397active, the process will not block when waiting for new events.
1336 1398
1337Apart from keeping your process non-blocking (which is a useful 1399Apart from keeping your process non-blocking (which is a useful
1437 1499
1438 // create io watchers for each fd and a timer before blocking 1500 // create io watchers for each fd and a timer before blocking
1439 static void 1501 static void
1440 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents) 1502 adns_prepare_cb (ev_loop *loop, ev_prepare *w, int revents)
1441 { 1503 {
1442 int timeout = 3600000;truct pollfd fds [nfd]; 1504 int timeout = 3600000;
1505 struct pollfd fds [nfd];
1443 // actual code will need to loop here and realloc etc. 1506 // actual code will need to loop here and realloc etc.
1444 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ())); 1507 adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
1445 1508
1446 /* the callback is illegal, but won't be called as we stop during check */ 1509 /* the callback is illegal, but won't be called as we stop during check */
1447 ev_timer_init (&tw, 0, timeout * 1e-3); 1510 ev_timer_init (&tw, 0, timeout * 1e-3);
1681 1744
1682To use it, 1745To use it,
1683 1746
1684 #include <ev++.h> 1747 #include <ev++.h>
1685 1748
1686(it is not installed by default). This automatically includes F<ev.h> 1749This automatically includes F<ev.h> and puts all of its definitions (many
1687and puts all of its definitions (many of them macros) into the global 1750of them macros) into the global namespace. All C++ specific things are
1688namespace. All C++ specific things are put into the C<ev> namespace. 1751put into the C<ev> namespace. It should support all the same embedding
1752options as F<ev.h>, most notably C<EV_MULTIPLICITY>.
1689 1753
1690It should support all the same embedding options as F<ev.h>, most notably 1754Care has been taken to keep the overhead low. The only data member the C++
1691C<EV_MULTIPLICITY>. 1755classes add (compared to plain C-style watchers) is the event loop pointer
1756that the watcher is associated with (or no additional members at all if
1757you disable C<EV_MULTIPLICITY> when embedding libev).
1758
1759Currently, functions, and static and non-static member functions can be
1760used as callbacks. Other types should be easy to add as long as they only
1761need one additional pointer for context. If you need support for other
1762types of functors please contact the author (preferably after implementing
1763it).
1692 1764
1693Here is a list of things available in the C<ev> namespace: 1765Here is a list of things available in the C<ev> namespace:
1694 1766
1695=over 4 1767=over 4
1696 1768
1712 1784
1713All of those classes have these methods: 1785All of those classes have these methods:
1714 1786
1715=over 4 1787=over 4
1716 1788
1717=item ev::TYPE::TYPE (object *, object::method *) 1789=item ev::TYPE::TYPE ()
1718 1790
1719=item ev::TYPE::TYPE (object *, object::method *, struct ev_loop *) 1791=item ev::TYPE::TYPE (struct ev_loop *)
1720 1792
1721=item ev::TYPE::~TYPE 1793=item ev::TYPE::~TYPE
1722 1794
1723The constructor takes a pointer to an object and a method pointer to 1795The constructor (optionally) takes an event loop to associate the watcher
1724the event handler callback to call in this class. The constructor calls 1796with. If it is omitted, it will use C<EV_DEFAULT>.
1725C<ev_init> for you, which means you have to call the C<set> method 1797
1726before starting it. If you do not specify a loop then the constructor 1798The constructor calls C<ev_init> for you, which means you have to call the
1727automatically associates the default loop with this watcher. 1799C<set> method before starting it.
1800
1801It will not set a callback, however: You have to call the templated C<set>
1802method to set a callback before you can start the watcher.
1803
1804(The reason why you have to use a method is a limitation in C++ which does
1805not allow explicit template arguments for constructors).
1728 1806
1729The destructor automatically stops the watcher if it is active. 1807The destructor automatically stops the watcher if it is active.
1808
1809=item w->set<class, &class::method> (object *)
1810
1811This method sets the callback method to call. The method has to have a
1812signature of C<void (*)(ev_TYPE &, int)>, it receives the watcher as
1813first argument and the C<revents> as second. The object must be given as
1814parameter and is stored in the C<data> member of the watcher.
1815
1816This method synthesizes efficient thunking code to call your method from
1817the C callback that libev requires. If your compiler can inline your
1818callback (i.e. it is visible to it at the place of the C<set> call and
1819your compiler is good :), then the method will be fully inlined into the
1820thunking function, making it as fast as a direct C callback.
1821
1822Example: simple class declaration and watcher initialisation
1823
1824 struct myclass
1825 {
1826 void io_cb (ev::io &w, int revents) { }
1827 }
1828
1829 myclass obj;
1830 ev::io iow;
1831 iow.set <myclass, &myclass::io_cb> (&obj);
1832
1833=item w->set (void (*function)(watcher &w, int), void *data = 0)
1834
1835Also sets a callback, but uses a static method or plain function as
1836callback. The optional C<data> argument will be stored in the watcher's
1837C<data> member and is free for you to use.
1838
1839See the method-C<set> above for more details.
1730 1840
1731=item w->set (struct ev_loop *) 1841=item w->set (struct ev_loop *)
1732 1842
1733Associates a different C<struct ev_loop> with this watcher. You can only 1843Associates a different C<struct ev_loop> with this watcher. You can only
1734do this when the watcher is inactive (and not pending either). 1844do this when the watcher is inactive (and not pending either).
1735 1845
1736=item w->set ([args]) 1846=item w->set ([args])
1737 1847
1738Basically the same as C<ev_TYPE_set>, with the same args. Must be 1848Basically the same as C<ev_TYPE_set>, with the same args. Must be
1739called at least once. Unlike the C counterpart, an active watcher gets 1849called at least once. Unlike the C counterpart, an active watcher gets
1740automatically stopped and restarted. 1850automatically stopped and restarted when reconfiguring it with this
1851method.
1741 1852
1742=item w->start () 1853=item w->start ()
1743 1854
1744Starts the watcher. Note that there is no C<loop> argument as the 1855Starts the watcher. Note that there is no C<loop> argument, as the
1745constructor already takes the loop. 1856constructor already stores the event loop.
1746 1857
1747=item w->stop () 1858=item w->stop ()
1748 1859
1749Stops the watcher if it is active. Again, no C<loop> argument. 1860Stops the watcher if it is active. Again, no C<loop> argument.
1750 1861
1775 1886
1776 myclass (); 1887 myclass ();
1777 } 1888 }
1778 1889
1779 myclass::myclass (int fd) 1890 myclass::myclass (int fd)
1780 : io (this, &myclass::io_cb),
1781 idle (this, &myclass::idle_cb)
1782 { 1891 {
1892 io .set <myclass, &myclass::io_cb > (this);
1893 idle.set <myclass, &myclass::idle_cb> (this);
1894
1783 io.start (fd, ev::READ); 1895 io.start (fd, ev::READ);
1784 } 1896 }
1785 1897
1786 1898
1787=head1 MACRO MAGIC 1899=head1 MACRO MAGIC
1788 1900
1789Libev can be compiled with a variety of options, the most fundemantal is 1901Libev can be compiled with a variety of options, the most fundemantal is
1790C<EV_MULTIPLICITY>. This option determines wether (most) functions and 1902C<EV_MULTIPLICITY>. This option determines whether (most) functions and
1791callbacks have an initial C<struct ev_loop *> argument. 1903callbacks have an initial C<struct ev_loop *> argument.
1792 1904
1793To make it easier to write programs that cope with either variant, the 1905To make it easier to write programs that cope with either variant, the
1794following macros are defined: 1906following macros are defined:
1795 1907
1828Similar to the other two macros, this gives you the value of the default 1940Similar to the other two macros, this gives you the value of the default
1829loop, if multiple loops are supported ("ev loop default"). 1941loop, if multiple loops are supported ("ev loop default").
1830 1942
1831=back 1943=back
1832 1944
1833Example: Declare and initialise a check watcher, working regardless of 1945Example: Declare and initialise a check watcher, utilising the above
1834wether multiple loops are supported or not. 1946macros so it will work regardless of whether multiple loops are supported
1947or not.
1835 1948
1836 static void 1949 static void
1837 check_cb (EV_P_ ev_timer *w, int revents) 1950 check_cb (EV_P_ ev_timer *w, int revents)
1838 { 1951 {
1839 ev_check_stop (EV_A_ w); 1952 ev_check_stop (EV_A_ w);
1841 1954
1842 ev_check check; 1955 ev_check check;
1843 ev_check_init (&check, check_cb); 1956 ev_check_init (&check, check_cb);
1844 ev_check_start (EV_DEFAULT_ &check); 1957 ev_check_start (EV_DEFAULT_ &check);
1845 ev_loop (EV_DEFAULT_ 0); 1958 ev_loop (EV_DEFAULT_ 0);
1846
1847 1959
1848=head1 EMBEDDING 1960=head1 EMBEDDING
1849 1961
1850Libev can (and often is) directly embedded into host 1962Libev can (and often is) directly embedded into host
1851applications. Examples of applications that embed it include the Deliantra 1963applications. Examples of applications that embed it include the Deliantra
1891 ev_vars.h 2003 ev_vars.h
1892 ev_wrap.h 2004 ev_wrap.h
1893 2005
1894 ev_win32.c required on win32 platforms only 2006 ev_win32.c required on win32 platforms only
1895 2007
1896 ev_select.c only when select backend is enabled (which is by default) 2008 ev_select.c only when select backend is enabled (which is enabled by default)
1897 ev_poll.c only when poll backend is enabled (disabled by default) 2009 ev_poll.c only when poll backend is enabled (disabled by default)
1898 ev_epoll.c only when the epoll backend is enabled (disabled by default) 2010 ev_epoll.c only when the epoll backend is enabled (disabled by default)
1899 ev_kqueue.c only when the kqueue backend is enabled (disabled by default) 2011 ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
1900 ev_port.c only when the solaris port backend is enabled (disabled by default) 2012 ev_port.c only when the solaris port backend is enabled (disabled by default)
1901 2013
2064will have the C<struct ev_loop *> as first argument, and you can create 2176will have the C<struct ev_loop *> as first argument, and you can create
2065additional independent event loops. Otherwise there will be no support 2177additional independent event loops. Otherwise there will be no support
2066for multiple event loops and there is no first event loop pointer 2178for multiple event loops and there is no first event loop pointer
2067argument. Instead, all functions act on the single default loop. 2179argument. Instead, all functions act on the single default loop.
2068 2180
2181=item EV_MINPRI
2182
2183=item EV_MAXPRI
2184
2185The range of allowed priorities. C<EV_MINPRI> must be smaller or equal to
2186C<EV_MAXPRI>, but otherwise there are no non-obvious limitations. You can
2187provide for more priorities by overriding those symbols (usually defined
2188to be C<-2> and C<2>, respectively).
2189
2190When doing priority-based operations, libev usually has to linearly search
2191all the priorities, so having many of them (hundreds) uses a lot of space
2192and time, so using the defaults of five priorities (-2 .. +2) is usually
2193fine.
2194
2195If your embedding app does not need any priorities, defining these both to
2196C<0> will save some memory and cpu.
2197
2069=item EV_PERIODIC_ENABLE 2198=item EV_PERIODIC_ENABLE
2070 2199
2071If undefined or defined to be C<1>, then periodic timers are supported. If 2200If undefined or defined to be C<1>, then periodic timers are supported. If
2201defined to be C<0>, then they are not. Disabling them saves a few kB of
2202code.
2203
2204=item EV_IDLE_ENABLE
2205
2206If undefined or defined to be C<1>, then idle watchers are supported. If
2072defined to be C<0>, then they are not. Disabling them saves a few kB of 2207defined to be C<0>, then they are not. Disabling them saves a few kB of
2073code. 2208code.
2074 2209
2075=item EV_EMBED_ENABLE 2210=item EV_EMBED_ENABLE
2076 2211
2143interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file 2278interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file
2144will be compiled. It is pretty complex because it provides its own header 2279will be compiled. It is pretty complex because it provides its own header
2145file. 2280file.
2146 2281
2147The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 2282The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
2148that everybody includes and which overrides some autoconf choices: 2283that everybody includes and which overrides some configure choices:
2149 2284
2285 #define EV_MINIMAL 1
2150 #define EV_USE_POLL 0 2286 #define EV_USE_POLL 0
2151 #define EV_MULTIPLICITY 0 2287 #define EV_MULTIPLICITY 0
2152 #define EV_PERIODICS 0 2288 #define EV_PERIODIC_ENABLE 0
2289 #define EV_STAT_ENABLE 0
2290 #define EV_FORK_ENABLE 0
2153 #define EV_CONFIG_H <config.h> 2291 #define EV_CONFIG_H <config.h>
2292 #define EV_MINPRI 0
2293 #define EV_MAXPRI 0
2154 2294
2155 #include "ev++.h" 2295 #include "ev++.h"
2156 2296
2157And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 2297And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
2158 2298
2164 2304
2165In this section the complexities of (many of) the algorithms used inside 2305In this section the complexities of (many of) the algorithms used inside
2166libev will be explained. For complexity discussions about backends see the 2306libev will be explained. For complexity discussions about backends see the
2167documentation for C<ev_default_init>. 2307documentation for C<ev_default_init>.
2168 2308
2309All of the following are about amortised time: If an array needs to be
2310extended, libev needs to realloc and move the whole array, but this
2311happens asymptotically never with higher number of elements, so O(1) might
2312mean it might do a lengthy realloc operation in rare cases, but on average
2313it is much faster and asymptotically approaches constant time.
2314
2169=over 4 2315=over 4
2170 2316
2171=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers) 2317=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
2172 2318
2319This means that, when you have a watcher that triggers in one hour and
2320there are 100 watchers that would trigger before that then inserting will
2321have to skip those 100 watchers.
2322
2173=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers) 2323=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)
2174 2324
2325That means that for changing a timer costs less than removing/adding them
2326as only the relative motion in the event queue has to be paid for.
2327
2175=item Starting io/check/prepare/idle/signal/child watchers: O(1) 2328=item Starting io/check/prepare/idle/signal/child watchers: O(1)
2176 2329
2330These just add the watcher into an array or at the head of a list.
2177=item Stopping check/prepare/idle watchers: O(1) 2331=item Stopping check/prepare/idle watchers: O(1)
2178 2332
2179=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) 2333=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))
2180 2334
2335These watchers are stored in lists then need to be walked to find the
2336correct watcher to remove. The lists are usually short (you don't usually
2337have many watchers waiting for the same fd or signal).
2338
2181=item Finding the next timer per loop iteration: O(1) 2339=item Finding the next timer per loop iteration: O(1)
2182 2340
2183=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd) 2341=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
2184 2342
2343A change means an I/O watcher gets started or stopped, which requires
2344libev to recalculate its status (and possibly tell the kernel).
2345
2185=item Activating one watcher: O(1) 2346=item Activating one watcher: O(1)
2186 2347
2348=item Priority handling: O(number_of_priorities)
2349
2350Priorities are implemented by allocating some space for each
2351priority. When doing priority-based operations, libev usually has to
2352linearly search all the priorities.
2353
2187=back 2354=back
2188 2355
2189 2356
2190=head1 AUTHOR 2357=head1 AUTHOR
2191 2358

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines