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

Comparing libev/ev.pod (file contents):
Revision 1.265 by root, Wed Aug 26 17:11:42 2009 UTC vs.
Revision 1.290 by root, Tue Mar 16 18:03:01 2010 UTC

118Libev is very configurable. In this manual the default (and most common) 118Libev is very configurable. In this manual the default (and most common)
119configuration will be described, which supports multiple event loops. For 119configuration will be described, which supports multiple event loops. For
120more info about various configuration options please have a look at 120more info about various configuration options please have a look at
121B<EMBED> section in this manual. If libev was configured without support 121B<EMBED> section in this manual. If libev was configured without support
122for multiple event loops, then all functions taking an initial argument of 122for multiple event loops, then all functions taking an initial argument of
123name C<loop> (which is always of type C<ev_loop *>) will not have 123name C<loop> (which is always of type C<struct ev_loop *>) will not have
124this argument. 124this argument.
125 125
126=head2 TIME REPRESENTATION 126=head2 TIME REPRESENTATION
127 127
128Libev represents time as a single floating point number, representing 128Libev represents time as a single floating point number, representing
370When this flag is specified, then libev will not attempt to use the 370When this flag is specified, then libev will not attempt to use the
371I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and 371I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
372testing, this flag can be useful to conserve inotify file descriptors, as 372testing, this flag can be useful to conserve inotify file descriptors, as
373otherwise each loop using C<ev_stat> watchers consumes one inotify handle. 373otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
374 374
375=item C<EVFLAG_NOSIGNALFD> 375=item C<EVFLAG_SIGNALFD>
376 376
377When this flag is specified, then libev will not attempt to use the 377When this flag is specified, then libev will attempt to use the
378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is 378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
379probably only useful to work around any bugs in libev. Consequently, this 379delivers signals synchronously, which makes it both faster and might make
380flag might go away once the signalfd functionality is considered stable, 380it possible to get the queued signal data. It can also simplify signal
381so it's useful mostly in environment variables and not in program code. 381handling with threads, as long as you properly block signals in your
382threads that are not interested in handling them.
383
384Signalfd will not be used by default as this changes your signal mask, and
385there are a lot of shoddy libraries and programs (glib's threadpool for
386example) that can't properly initialise their signal masks.
382 387
383=item C<EVBACKEND_SELECT> (value 1, portable select backend) 388=item C<EVBACKEND_SELECT> (value 1, portable select backend)
384 389
385This is your standard select(2) backend. Not I<completely> standard, as 390This is your standard select(2) backend. Not I<completely> standard, as
386libev tries to roll its own fd_set with no limits on the number of fds, 391libev tries to roll its own fd_set with no limits on the number of fds,
410 415
411This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and 416This backend maps C<EV_READ> to C<POLLIN | POLLERR | POLLHUP>, and
412C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>. 417C<EV_WRITE> to C<POLLOUT | POLLERR | POLLHUP>.
413 418
414=item C<EVBACKEND_EPOLL> (value 4, Linux) 419=item C<EVBACKEND_EPOLL> (value 4, Linux)
420
421Use the linux-specific epoll(7) interface (for both pre- and post-2.6.9
422kernels).
415 423
416For few fds, this backend is a bit little slower than poll and select, 424For few fds, this backend is a bit little slower than poll and select,
417but it scales phenomenally better. While poll and select usually scale 425but it scales phenomenally better. While poll and select usually scale
418like O(total_fds) where n is the total number of fds (or the highest fd), 426like O(total_fds) where n is the total number of fds (or the highest fd),
419epoll scales either O(1) or O(active_fds). 427epoll scales either O(1) or O(active_fds).
559 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); 567 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
560 568
561=item struct ev_loop *ev_loop_new (unsigned int flags) 569=item struct ev_loop *ev_loop_new (unsigned int flags)
562 570
563Similar to C<ev_default_loop>, but always creates a new event loop that is 571Similar to C<ev_default_loop>, but always creates a new event loop that is
564always distinct from the default loop. Unlike the default loop, it cannot 572always distinct from the default loop.
565handle signal and child watchers, and attempts to do so will be greeted by
566undefined behaviour (or a failed assertion if assertions are enabled).
567 573
568Note that this function I<is> thread-safe, and the recommended way to use 574Note that this function I<is> thread-safe, and one common way to use
569libev with threads is indeed to create one loop per thread, and using the 575libev with threads is indeed to create one loop per thread, and using the
570default loop in the "main" or "initial" thread. 576default loop in the "main" or "initial" thread.
571 577
572Example: Try to create a event loop that uses epoll and nothing else. 578Example: Try to create a event loop that uses epoll and nothing else.
573 579
575 if (!epoller) 581 if (!epoller)
576 fatal ("no epoll found here, maybe it hides under your chair"); 582 fatal ("no epoll found here, maybe it hides under your chair");
577 583
578=item ev_default_destroy () 584=item ev_default_destroy ()
579 585
580Destroys the default loop again (frees all memory and kernel state 586Destroys the default loop (frees all memory and kernel state etc.). None
581etc.). None of the active event watchers will be stopped in the normal 587of the active event watchers will be stopped in the normal sense, so
582sense, so e.g. C<ev_is_active> might still return true. It is your 588e.g. C<ev_is_active> might still return true. It is your responsibility to
583responsibility to either stop all watchers cleanly yourself I<before> 589either stop all watchers cleanly yourself I<before> calling this function,
584calling this function, or cope with the fact afterwards (which is usually 590or cope with the fact afterwards (which is usually the easiest thing, you
585the easiest thing, you can just ignore the watchers and/or C<free ()> them 591can just ignore the watchers and/or C<free ()> them for example).
586for example).
587 592
588Note that certain global state, such as signal state (and installed signal 593Note that certain global state, such as signal state (and installed signal
589handlers), will not be freed by this function, and related watchers (such 594handlers), will not be freed by this function, and related watchers (such
590as signal and child watchers) would need to be stopped manually. 595as signal and child watchers) would need to be stopped manually.
591 596
592In general it is not advisable to call this function except in the 597In general it is not advisable to call this function except in the
593rare occasion where you really need to free e.g. the signal handling 598rare occasion where you really need to free e.g. the signal handling
594pipe fds. If you need dynamically allocated loops it is better to use 599pipe fds. If you need dynamically allocated loops it is better to use
595C<ev_loop_new> and C<ev_loop_destroy>). 600C<ev_loop_new> and C<ev_loop_destroy>.
596 601
597=item ev_loop_destroy (loop) 602=item ev_loop_destroy (loop)
598 603
599Like C<ev_default_destroy>, but destroys an event loop created by an 604Like C<ev_default_destroy>, but destroys an event loop created by an
600earlier call to C<ev_loop_new>. 605earlier call to C<ev_loop_new>.
704event loop time (see C<ev_now_update>). 709event loop time (see C<ev_now_update>).
705 710
706=item ev_loop (loop, int flags) 711=item ev_loop (loop, int flags)
707 712
708Finally, this is it, the event handler. This function usually is called 713Finally, this is it, the event handler. This function usually is called
709after you initialised all your watchers and you want to start handling 714after you have initialised all your watchers and you want to start
710events. 715handling events.
711 716
712If the flags argument is specified as C<0>, it will not return until 717If the flags argument is specified as C<0>, it will not return until
713either no event watchers are active anymore or C<ev_unloop> was called. 718either no event watchers are active anymore or C<ev_unloop> was called.
714 719
715Please note that an explicit C<ev_unloop> is usually better than 720Please note that an explicit C<ev_unloop> is usually better than
789 794
790Ref/unref can be used to add or remove a reference count on the event 795Ref/unref can be used to add or remove a reference count on the event
791loop: Every watcher keeps one reference, and as long as the reference 796loop: Every watcher keeps one reference, and as long as the reference
792count is nonzero, C<ev_loop> will not return on its own. 797count is nonzero, C<ev_loop> will not return on its own.
793 798
794If you have a watcher you never unregister that should not keep C<ev_loop> 799This is useful when you have a watcher that you never intend to
795from returning, call ev_unref() after starting, and ev_ref() before 800unregister, but that nevertheless should not keep C<ev_loop> from
801returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
796stopping it. 802before stopping it.
797 803
798As an example, libev itself uses this for its internal signal pipe: It 804As an example, libev itself uses this for its internal signal pipe: It
799is not visible to the libev user and should not keep C<ev_loop> from 805is not visible to the libev user and should not keep C<ev_loop> from
800exiting if no event watchers registered by it are active. It is also an 806exiting if no event watchers registered by it are active. It is also an
801excellent way to do this for generic recurring timers or from within 807excellent way to do this for generic recurring timers or from within
916 922
917While event loop modifications are allowed between invocations of 923While event loop modifications are allowed between invocations of
918C<release> and C<acquire> (that's their only purpose after all), no 924C<release> and C<acquire> (that's their only purpose after all), no
919modifications done will affect the event loop, i.e. adding watchers will 925modifications done will affect the event loop, i.e. adding watchers will
920have no effect on the set of file descriptors being watched, or the time 926have no effect on the set of file descriptors being watched, or the time
921waited. USe an C<ev_async> watcher to wake up C<ev_loop> when you want it 927waited. Use an C<ev_async> watcher to wake up C<ev_loop> when you want it
922to take note of any changes you made. 928to take note of any changes you made.
923 929
924In theory, threads executing C<ev_loop> will be async-cancel safe between 930In theory, threads executing C<ev_loop> will be async-cancel safe between
925invocations of C<release> and C<acquire>. 931invocations of C<release> and C<acquire>.
926 932
1023=item C<EV_WRITE> 1029=item C<EV_WRITE>
1024 1030
1025The file descriptor in the C<ev_io> watcher has become readable and/or 1031The file descriptor in the C<ev_io> watcher has become readable and/or
1026writable. 1032writable.
1027 1033
1028=item C<EV_TIMEOUT> 1034=item C<EV_TIMER>
1029 1035
1030The C<ev_timer> watcher has timed out. 1036The C<ev_timer> watcher has timed out.
1031 1037
1032=item C<EV_PERIODIC> 1038=item C<EV_PERIODIC>
1033 1039
1123 1129
1124 ev_io w; 1130 ev_io w;
1125 ev_init (&w, my_cb); 1131 ev_init (&w, my_cb);
1126 ev_io_set (&w, STDIN_FILENO, EV_READ); 1132 ev_io_set (&w, STDIN_FILENO, EV_READ);
1127 1133
1128=item C<ev_TYPE_set> (ev_TYPE *, [args]) 1134=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
1129 1135
1130This macro initialises the type-specific parts of a watcher. You need to 1136This macro initialises the type-specific parts of a watcher. You need to
1131call C<ev_init> at least once before you call this macro, but you can 1137call C<ev_init> at least once before you call this macro, but you can
1132call C<ev_TYPE_set> any number of times. You must not, however, call this 1138call C<ev_TYPE_set> any number of times. You must not, however, call this
1133macro on a watcher that is active (it can be pending, however, which is a 1139macro on a watcher that is active (it can be pending, however, which is a
1146 1152
1147Example: Initialise and set an C<ev_io> watcher in one step. 1153Example: Initialise and set an C<ev_io> watcher in one step.
1148 1154
1149 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); 1155 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
1150 1156
1151=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 1157=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
1152 1158
1153Starts (activates) the given watcher. Only active watchers will receive 1159Starts (activates) the given watcher. Only active watchers will receive
1154events. If the watcher is already active nothing will happen. 1160events. If the watcher is already active nothing will happen.
1155 1161
1156Example: Start the C<ev_io> watcher that is being abused as example in this 1162Example: Start the C<ev_io> watcher that is being abused as example in this
1157whole section. 1163whole section.
1158 1164
1159 ev_io_start (EV_DEFAULT_UC, &w); 1165 ev_io_start (EV_DEFAULT_UC, &w);
1160 1166
1161=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 1167=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
1162 1168
1163Stops the given watcher if active, and clears the pending status (whether 1169Stops the given watcher if active, and clears the pending status (whether
1164the watcher was active or not). 1170the watcher was active or not).
1165 1171
1166It is possible that stopped watchers are pending - for example, 1172It is possible that stopped watchers are pending - for example,
1191=item ev_cb_set (ev_TYPE *watcher, callback) 1197=item ev_cb_set (ev_TYPE *watcher, callback)
1192 1198
1193Change the callback. You can change the callback at virtually any time 1199Change the callback. You can change the callback at virtually any time
1194(modulo threads). 1200(modulo threads).
1195 1201
1196=item ev_set_priority (ev_TYPE *watcher, priority) 1202=item ev_set_priority (ev_TYPE *watcher, int priority)
1197 1203
1198=item int ev_priority (ev_TYPE *watcher) 1204=item int ev_priority (ev_TYPE *watcher)
1199 1205
1200Set and query the priority of the watcher. The priority is a small 1206Set and query the priority of the watcher. The priority is a small
1201integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1207integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1232returns its C<revents> bitset (as if its callback was invoked). If the 1238returns its C<revents> bitset (as if its callback was invoked). If the
1233watcher isn't pending it does nothing and returns C<0>. 1239watcher isn't pending it does nothing and returns C<0>.
1234 1240
1235Sometimes it can be useful to "poll" a watcher instead of waiting for its 1241Sometimes it can be useful to "poll" a watcher instead of waiting for its
1236callback to be invoked, which can be accomplished with this function. 1242callback to be invoked, which can be accomplished with this function.
1243
1244=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1245
1246Feeds the given event set into the event loop, as if the specified event
1247had happened for the specified watcher (which must be a pointer to an
1248initialised but not necessarily started event watcher). Obviously you must
1249not free the watcher as long as it has pending events.
1250
1251Stopping the watcher, letting libev invoke it, or calling
1252C<ev_clear_pending> will clear the pending event, even if the watcher was
1253not started in the first place.
1254
1255See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1256functions that do not need a watcher.
1237 1257
1238=back 1258=back
1239 1259
1240 1260
1241=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1261=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
1515 1535
1516So when you encounter spurious, unexplained daemon exits, make sure you 1536So when you encounter spurious, unexplained daemon exits, make sure you
1517ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1537ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1518somewhere, as that would have given you a big clue). 1538somewhere, as that would have given you a big clue).
1519 1539
1540=head3 The special problem of accept()ing when you can't
1541
1542Many implementations of the POSIX C<accept> function (for example,
1543found in port-2004 Linux) have the peculiar behaviour of not removing a
1544connection from the pending queue in all error cases.
1545
1546For example, larger servers often run out of file descriptors (because
1547of resource limits), causing C<accept> to fail with C<ENFILE> but not
1548rejecting the connection, leading to libev signalling readiness on
1549the next iteration again (the connection still exists after all), and
1550typically causing the program to loop at 100% CPU usage.
1551
1552Unfortunately, the set of errors that cause this issue differs between
1553operating systems, there is usually little the app can do to remedy the
1554situation, and no known thread-safe method of removing the connection to
1555cope with overload is known (to me).
1556
1557One of the easiest ways to handle this situation is to just ignore it
1558- when the program encounters an overload, it will just loop until the
1559situation is over. While this is a form of busy waiting, no OS offers an
1560event-based way to handle this situation, so it's the best one can do.
1561
1562A better way to handle the situation is to log any errors other than
1563C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
1564messages, and continue as usual, which at least gives the user an idea of
1565what could be wrong ("raise the ulimit!"). For extra points one could stop
1566the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
1567usage.
1568
1569If your program is single-threaded, then you could also keep a dummy file
1570descriptor for overload situations (e.g. by opening F</dev/null>), and
1571when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
1572close that fd, and create a new dummy fd. This will gracefully refuse
1573clients under typical overload conditions.
1574
1575The last way to handle it is to simply log the error and C<exit>, as
1576is often done with C<malloc> failures, but this results in an easy
1577opportunity for a DoS attack.
1520 1578
1521=head3 Watcher-Specific Functions 1579=head3 Watcher-Specific Functions
1522 1580
1523=over 4 1581=over 4
1524 1582
1703to the current time (meaning we just have some activity :), then call the 1761to the current time (meaning we just have some activity :), then call the
1704callback, which will "do the right thing" and start the timer: 1762callback, which will "do the right thing" and start the timer:
1705 1763
1706 ev_init (timer, callback); 1764 ev_init (timer, callback);
1707 last_activity = ev_now (loop); 1765 last_activity = ev_now (loop);
1708 callback (loop, timer, EV_TIMEOUT); 1766 callback (loop, timer, EV_TIMER);
1709 1767
1710And when there is some activity, simply store the current time in 1768And when there is some activity, simply store the current time in
1711C<last_activity>, no libev calls at all: 1769C<last_activity>, no libev calls at all:
1712 1770
1713 last_actiivty = ev_now (loop); 1771 last_actiivty = ev_now (loop);
1837C<repeat> value), or reset the running timer to the C<repeat> value. 1895C<repeat> value), or reset the running timer to the C<repeat> value.
1838 1896
1839This sounds a bit complicated, see L<Be smart about timeouts>, above, for a 1897This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1840usage example. 1898usage example.
1841 1899
1842=item ev_timer_remaining (loop, ev_timer *) 1900=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
1843 1901
1844Returns the remaining time until a timer fires. If the timer is active, 1902Returns the remaining time until a timer fires. If the timer is active,
1845then this time is relative to the current event loop time, otherwise it's 1903then this time is relative to the current event loop time, otherwise it's
1846the timeout value currently configured. 1904the timeout value currently configured.
1847 1905
1848That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns 1906That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
1849C<5>. When the timer is started and one second passes, C<ev_timer_remain> 1907C<5>. When the timer is started and one second passes, C<ev_timer_remaining>
1850will return C<4>. When the timer expires and is restarted, it will return 1908will return C<4>. When the timer expires and is restarted, it will return
1851roughly C<7> (likely slightly less as callback invocation takes some time, 1909roughly C<7> (likely slightly less as callback invocation takes some time,
1852too), and so on. 1910too), and so on.
1853 1911
1854=item ev_tstamp repeat [read-write] 1912=item ev_tstamp repeat [read-write]
2114C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should 2172C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2115not be unduly interrupted. If you have a problem with system calls getting 2173not be unduly interrupted. If you have a problem with system calls getting
2116interrupted by signals you can block all signals in an C<ev_check> watcher 2174interrupted by signals you can block all signals in an C<ev_check> watcher
2117and unblock them in an C<ev_prepare> watcher. 2175and unblock them in an C<ev_prepare> watcher.
2118 2176
2119=head3 The special problem of inheritance over execve 2177=head3 The special problem of inheritance over fork/execve/pthread_create
2120 2178
2121Both the signal mask (C<sigprocmask>) and the signal disposition 2179Both the signal mask (C<sigprocmask>) and the signal disposition
2122(C<sigaction>) are unspecified after starting a signal watcher (and after 2180(C<sigaction>) are unspecified after starting a signal watcher (and after
2123stopping it again), that is, libev might or might not block the signal, 2181stopping it again), that is, libev might or might not block the signal,
2124and might or might not set or restore the installed signal handler. 2182and might or might not set or restore the installed signal handler.
2125 2183
2126While this does not matter for the signal disposition (libev never 2184While this does not matter for the signal disposition (libev never
2127sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on 2185sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on
2128C<execve>), this matters for the signal mask: many programs do not expect 2186C<execve>), this matters for the signal mask: many programs do not expect
2129many signals to be blocked. 2187certain signals to be blocked.
2130 2188
2131This means that before calling C<exec> (from the child) you should reset 2189This means that before calling C<exec> (from the child) you should reset
2132the signal mask to whatever "default" you expect (all clear is a good 2190the signal mask to whatever "default" you expect (all clear is a good
2133choice usually). 2191choice usually).
2192
2193The simplest way to ensure that the signal mask is reset in the child is
2194to install a fork handler with C<pthread_atfork> that resets it. That will
2195catch fork calls done by libraries (such as the libc) as well.
2196
2197In current versions of libev, the signal will not be blocked indefinitely
2198unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2199the window of opportunity for problems, it will not go away, as libev
2200I<has> to modify the signal mask, at least temporarily.
2201
2202So I can't stress this enough: I<If you do not reset your signal mask when
2203you expect it to be empty, you have a race condition in your code>. This
2204is not a libev-specific thing, this is true for most event libraries.
2134 2205
2135=head3 Watcher-Specific Functions and Data Members 2206=head3 Watcher-Specific Functions and Data Members
2136 2207
2137=over 4 2208=over 4
2138 2209
2955=head3 Queueing 3026=head3 Queueing
2956 3027
2957C<ev_async> does not support queueing of data in any way. The reason 3028C<ev_async> does not support queueing of data in any way. The reason
2958is that the author does not know of a simple (or any) algorithm for a 3029is that the author does not know of a simple (or any) algorithm for a
2959multiple-writer-single-reader queue that works in all cases and doesn't 3030multiple-writer-single-reader queue that works in all cases and doesn't
2960need elaborate support such as pthreads. 3031need elaborate support such as pthreads or unportable memory access
3032semantics.
2961 3033
2962That means that if you want to queue data, you have to provide your own 3034That means that if you want to queue data, you have to provide your own
2963queue. But at least I can tell you how to implement locking around your 3035queue. But at least I can tell you how to implement locking around your
2964queue: 3036queue:
2965 3037
3104 3176
3105If C<timeout> is less than 0, then no timeout watcher will be 3177If C<timeout> is less than 0, then no timeout watcher will be
3106started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 3178started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
3107repeat = 0) will be started. C<0> is a valid timeout. 3179repeat = 0) will be started. C<0> is a valid timeout.
3108 3180
3109The callback has the type C<void (*cb)(int revents, void *arg)> and gets 3181The callback has the type C<void (*cb)(int revents, void *arg)> and is
3110passed an C<revents> set like normal event callbacks (a combination of 3182passed an C<revents> set like normal event callbacks (a combination of
3111C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> 3183C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
3112value passed to C<ev_once>. Note that it is possible to receive I<both> 3184value passed to C<ev_once>. Note that it is possible to receive I<both>
3113a timeout and an io event at the same time - you probably should give io 3185a timeout and an io event at the same time - you probably should give io
3114events precedence. 3186events precedence.
3115 3187
3116Example: wait up to ten seconds for data to appear on STDIN_FILENO. 3188Example: wait up to ten seconds for data to appear on STDIN_FILENO.
3117 3189
3118 static void stdin_ready (int revents, void *arg) 3190 static void stdin_ready (int revents, void *arg)
3119 { 3191 {
3120 if (revents & EV_READ) 3192 if (revents & EV_READ)
3121 /* stdin might have data for us, joy! */; 3193 /* stdin might have data for us, joy! */;
3122 else if (revents & EV_TIMEOUT) 3194 else if (revents & EV_TIMER)
3123 /* doh, nothing entered */; 3195 /* doh, nothing entered */;
3124 } 3196 }
3125 3197
3126 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3198 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3127 3199
3128=item ev_feed_event (struct ev_loop *, watcher *, int revents)
3129
3130Feeds the given event set into the event loop, as if the specified event
3131had happened for the specified watcher (which must be a pointer to an
3132initialised but not necessarily started event watcher).
3133
3134=item ev_feed_fd_event (struct ev_loop *, int fd, int revents) 3200=item ev_feed_fd_event (loop, int fd, int revents)
3135 3201
3136Feed an event on the given fd, as if a file descriptor backend detected 3202Feed an event on the given fd, as if a file descriptor backend detected
3137the given events it. 3203the given events it.
3138 3204
3139=item ev_feed_signal_event (struct ev_loop *loop, int signum) 3205=item ev_feed_signal_event (loop, int signum)
3140 3206
3141Feed an event as if the given signal occurred (C<loop> must be the default 3207Feed an event as if the given signal occurred (C<loop> must be the default
3142loop!). 3208loop!).
3143 3209
3144=back 3210=back
3224 3290
3225=over 4 3291=over 4
3226 3292
3227=item ev::TYPE::TYPE () 3293=item ev::TYPE::TYPE ()
3228 3294
3229=item ev::TYPE::TYPE (struct ev_loop *) 3295=item ev::TYPE::TYPE (loop)
3230 3296
3231=item ev::TYPE::~TYPE 3297=item ev::TYPE::~TYPE
3232 3298
3233The constructor (optionally) takes an event loop to associate the watcher 3299The constructor (optionally) takes an event loop to associate the watcher
3234with. If it is omitted, it will use C<EV_DEFAULT>. 3300with. If it is omitted, it will use C<EV_DEFAULT>.
3311Example: Use a plain function as callback. 3377Example: Use a plain function as callback.
3312 3378
3313 static void io_cb (ev::io &w, int revents) { } 3379 static void io_cb (ev::io &w, int revents) { }
3314 iow.set <io_cb> (); 3380 iow.set <io_cb> ();
3315 3381
3316=item w->set (struct ev_loop *) 3382=item w->set (loop)
3317 3383
3318Associates a different C<struct ev_loop> with this watcher. You can only 3384Associates a different C<struct ev_loop> with this watcher. You can only
3319do this when the watcher is inactive (and not pending either). 3385do this when the watcher is inactive (and not pending either).
3320 3386
3321=item w->set ([arguments]) 3387=item w->set ([arguments])
3420Erkki Seppala has written Ocaml bindings for libev, to be found at 3486Erkki Seppala has written Ocaml bindings for libev, to be found at
3421L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 3487L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3422 3488
3423=item Lua 3489=item Lua
3424 3490
3425Brian Maher has written a partial interface to libev 3491Brian Maher has written a partial interface to libev for lua (at the
3426for lua (only C<ev_io> and C<ev_timer>), to be found at 3492time of this writing, only C<ev_io> and C<ev_timer>), to be found at
3427L<http://github.com/brimworks/lua-ev>. 3493L<http://github.com/brimworks/lua-ev>.
3428 3494
3429=back 3495=back
3430 3496
3431 3497
3586 libev.m4 3652 libev.m4
3587 3653
3588=head2 PREPROCESSOR SYMBOLS/MACROS 3654=head2 PREPROCESSOR SYMBOLS/MACROS
3589 3655
3590Libev can be configured via a variety of preprocessor symbols you have to 3656Libev can be configured via a variety of preprocessor symbols you have to
3591define before including any of its files. The default in the absence of 3657define before including (or compiling) any of its files. The default in
3592autoconf is documented for every option. 3658the absence of autoconf is documented for every option.
3659
3660Symbols marked with "(h)" do not change the ABI, and can have different
3661values when compiling libev vs. including F<ev.h>, so it is permissible
3662to redefine them before including F<ev.h> without breakign compatibility
3663to a compiled library. All other symbols change the ABI, which means all
3664users of libev and the libev code itself must be compiled with compatible
3665settings.
3593 3666
3594=over 4 3667=over 4
3595 3668
3596=item EV_STANDALONE 3669=item EV_STANDALONE (h)
3597 3670
3598Must always be C<1> if you do not use autoconf configuration, which 3671Must always be C<1> if you do not use autoconf configuration, which
3599keeps libev from including F<config.h>, and it also defines dummy 3672keeps libev from including F<config.h>, and it also defines dummy
3600implementations for some libevent functions (such as logging, which is not 3673implementations for some libevent functions (such as logging, which is not
3601supported). It will also not define any of the structs usually found in 3674supported). It will also not define any of the structs usually found in
3751as well as for signal and thread safety in C<ev_async> watchers. 3824as well as for signal and thread safety in C<ev_async> watchers.
3752 3825
3753In the absence of this define, libev will use C<sig_atomic_t volatile> 3826In the absence of this define, libev will use C<sig_atomic_t volatile>
3754(from F<signal.h>), which is usually good enough on most platforms. 3827(from F<signal.h>), which is usually good enough on most platforms.
3755 3828
3756=item EV_H 3829=item EV_H (h)
3757 3830
3758The name of the F<ev.h> header file used to include it. The default if 3831The name of the F<ev.h> header file used to include it. The default if
3759undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 3832undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
3760used to virtually rename the F<ev.h> header file in case of conflicts. 3833used to virtually rename the F<ev.h> header file in case of conflicts.
3761 3834
3762=item EV_CONFIG_H 3835=item EV_CONFIG_H (h)
3763 3836
3764If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 3837If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
3765F<ev.c>'s idea of where to find the F<config.h> file, similarly to 3838F<ev.c>'s idea of where to find the F<config.h> file, similarly to
3766C<EV_H>, above. 3839C<EV_H>, above.
3767 3840
3768=item EV_EVENT_H 3841=item EV_EVENT_H (h)
3769 3842
3770Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 3843Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
3771of how the F<event.h> header can be found, the default is C<"event.h">. 3844of how the F<event.h> header can be found, the default is C<"event.h">.
3772 3845
3773=item EV_PROTOTYPES 3846=item EV_PROTOTYPES (h)
3774 3847
3775If defined to be C<0>, then F<ev.h> will not define any function 3848If defined to be C<0>, then F<ev.h> will not define any function
3776prototypes, but still define all the structs and other symbols. This is 3849prototypes, but still define all the structs and other symbols. This is
3777occasionally useful if you want to provide your own wrapper functions 3850occasionally useful if you want to provide your own wrapper functions
3778around libev functions. 3851around libev functions.
3800fine. 3873fine.
3801 3874
3802If your embedding application does not need any priorities, defining these 3875If your embedding application does not need any priorities, defining these
3803both to C<0> will save some memory and CPU. 3876both to C<0> will save some memory and CPU.
3804 3877
3805=item EV_PERIODIC_ENABLE 3878=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
3879EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
3880EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3806 3881
3807If undefined or defined to be C<1>, then periodic timers are supported. If 3882If undefined or defined to be C<1> (and the platform supports it), then
3808defined to be C<0>, then they are not. Disabling them saves a few kB of 3883the respective watcher type is supported. If defined to be C<0>, then it
3809code. 3884is not. Disabling watcher types mainly saves codesize.
3810 3885
3811=item EV_IDLE_ENABLE 3886=item EV_FEATURES
3812
3813If undefined or defined to be C<1>, then idle watchers are supported. If
3814defined to be C<0>, then they are not. Disabling them saves a few kB of
3815code.
3816
3817=item EV_EMBED_ENABLE
3818
3819If undefined or defined to be C<1>, then embed watchers are supported. If
3820defined to be C<0>, then they are not. Embed watchers rely on most other
3821watcher types, which therefore must not be disabled.
3822
3823=item EV_STAT_ENABLE
3824
3825If undefined or defined to be C<1>, then stat watchers are supported. If
3826defined to be C<0>, then they are not.
3827
3828=item EV_FORK_ENABLE
3829
3830If undefined or defined to be C<1>, then fork watchers are supported. If
3831defined to be C<0>, then they are not.
3832
3833=item EV_ASYNC_ENABLE
3834
3835If undefined or defined to be C<1>, then async watchers are supported. If
3836defined to be C<0>, then they are not.
3837
3838=item EV_MINIMAL
3839 3887
3840If you need to shave off some kilobytes of code at the expense of some 3888If you need to shave off some kilobytes of code at the expense of some
3841speed (but with the full API), define this symbol to C<1>. Currently this 3889speed (but with the full API), you can define this symbol to request
3842is used to override some inlining decisions, saves roughly 30% code size 3890certain subsets of functionality. The default is to enable all features
3843on amd64. It also selects a much smaller 2-heap for timer management over 3891that can be enabled on the platform.
3844the default 4-heap.
3845 3892
3846You can save even more by disabling watcher types you do not need 3893A typical way to use this symbol is to define it to C<0> (or to a bitset
3847and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> 3894with some broad features you want) and then selectively re-enable
3848(C<-DNDEBUG>) will usually reduce code size a lot. 3895additional parts you want, for example if you want everything minimal,
3896but multiple event loop support, async and child watchers and the poll
3897backend, use this:
3849 3898
3850Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to 3899 #define EV_FEATURES 0
3851provide a bare-bones event library. See C<ev.h> for details on what parts 3900 #define EV_MULTIPLICITY 1
3852of the API are still available, and do not complain if this subset changes 3901 #define EV_USE_POLL 1
3853over time. 3902 #define EV_CHILD_ENABLE 1
3903 #define EV_ASYNC_ENABLE 1
3904
3905The actual value is a bitset, it can be a combination of the following
3906values:
3907
3908=over 4
3909
3910=item C<1> - faster/larger code
3911
3912Use larger code to speed up some operations.
3913
3914Currently this is used to override some inlining decisions (enlarging the roughly
391530% code size on amd64.
3916
3917When optimising for size, use of compiler flags such as C<-Os> with
3918gcc recommended, as well as C<-DNDEBUG>, as libev contains a number of
3919assertions.
3920
3921=item C<2> - faster/larger data structures
3922
3923Replaces the small 2-heap for timer management by a faster 4-heap, larger
3924hash table sizes and so on. This will usually further increase codesize
3925and can additionally have an effect on the size of data structures at
3926runtime.
3927
3928=item C<4> - full API configuration
3929
3930This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
3931enables multiplicity (C<EV_MULTIPLICITY>=1).
3932
3933=item C<8> - full API
3934
3935This enables a lot of the "lesser used" API functions. See C<ev.h> for
3936details on which parts of the API are still available without this
3937feature, and do not complain if this subset changes over time.
3938
3939=item C<16> - enable all optional watcher types
3940
3941Enables all optional watcher types. If you want to selectively enable
3942only some watcher types other than I/O and timers (e.g. prepare,
3943embed, async, child...) you can enable them manually by defining
3944C<EV_watchertype_ENABLE> to C<1> instead.
3945
3946=item C<32> - enable all backends
3947
3948This enables all backends - without this feature, you need to enable at
3949least one backend manually (C<EV_USE_SELECT> is a good choice).
3950
3951=item C<64> - enable OS-specific "helper" APIs
3952
3953Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
3954default.
3955
3956=back
3957
3958Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
3959reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb
3960code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
3961watchers, timers and monotonic clock support.
3962
3963With an intelligent-enough linker (gcc+binutils are intelligent enough
3964when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
3965your program might be left out as well - a binary starting a timer and an
3966I/O watcher then might come out at only 5Kb.
3967
3968=item EV_AVOID_STDIO
3969
3970If this is set to C<1> at compiletime, then libev will avoid using stdio
3971functions (printf, scanf, perror etc.). This will increase the codesize
3972somewhat, but if your program doesn't otherwise depend on stdio and your
3973libc allows it, this avoids linking in the stdio library which is quite
3974big.
3975
3976Note that error messages might become less precise when this option is
3977enabled.
3854 3978
3855=item EV_NSIG 3979=item EV_NSIG
3856 3980
3857The highest supported signal number, +1 (or, the number of 3981The highest supported signal number, +1 (or, the number of
3858signals): Normally, libev tries to deduce the maximum number of signals 3982signals): Normally, libev tries to deduce the maximum number of signals
3862statically allocates some 12-24 bytes per signal number. 3986statically allocates some 12-24 bytes per signal number.
3863 3987
3864=item EV_PID_HASHSIZE 3988=item EV_PID_HASHSIZE
3865 3989
3866C<ev_child> watchers use a small hash table to distribute workload by 3990C<ev_child> watchers use a small hash table to distribute workload by
3867pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 3991pid. The default size is C<16> (or C<1> with C<EV_FEATURES> disabled),
3868than enough. If you need to manage thousands of children you might want to 3992usually more than enough. If you need to manage thousands of children you
3869increase this value (I<must> be a power of two). 3993might want to increase this value (I<must> be a power of two).
3870 3994
3871=item EV_INOTIFY_HASHSIZE 3995=item EV_INOTIFY_HASHSIZE
3872 3996
3873C<ev_stat> watchers use a small hash table to distribute workload by 3997C<ev_stat> watchers use a small hash table to distribute workload by
3874inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 3998inotify watch id. The default size is C<16> (or C<1> with C<EV_FEATURES>
3875usually more than enough. If you need to manage thousands of C<ev_stat> 3999disabled), usually more than enough. If you need to manage thousands of
3876watchers you might want to increase this value (I<must> be a power of 4000C<ev_stat> watchers you might want to increase this value (I<must> be a
3877two). 4001power of two).
3878 4002
3879=item EV_USE_4HEAP 4003=item EV_USE_4HEAP
3880 4004
3881Heaps are not very cache-efficient. To improve the cache-efficiency of the 4005Heaps are not very cache-efficient. To improve the cache-efficiency of the
3882timer and periodics heaps, libev uses a 4-heap when this symbol is defined 4006timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3883to C<1>. The 4-heap uses more complicated (longer) code but has noticeably 4007to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3884faster performance with many (thousands) of watchers. 4008faster performance with many (thousands) of watchers.
3885 4009
3886The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4010The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3887(disabled). 4011will be C<0>.
3888 4012
3889=item EV_HEAP_CACHE_AT 4013=item EV_HEAP_CACHE_AT
3890 4014
3891Heaps are not very cache-efficient. To improve the cache-efficiency of the 4015Heaps are not very cache-efficient. To improve the cache-efficiency of the
3892timer and periodics heaps, libev can cache the timestamp (I<at>) within 4016timer and periodics heaps, libev can cache the timestamp (I<at>) within
3893the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), 4017the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3894which uses 8-12 bytes more per watcher and a few hundred bytes more code, 4018which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3895but avoids random read accesses on heap changes. This improves performance 4019but avoids random read accesses on heap changes. This improves performance
3896noticeably with many (hundreds) of watchers. 4020noticeably with many (hundreds) of watchers.
3897 4021
3898The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4022The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3899(disabled). 4023will be C<0>.
3900 4024
3901=item EV_VERIFY 4025=item EV_VERIFY
3902 4026
3903Controls how much internal verification (see C<ev_loop_verify ()>) will 4027Controls how much internal verification (see C<ev_loop_verify ()>) will
3904be done: If set to C<0>, no internal verification code will be compiled 4028be done: If set to C<0>, no internal verification code will be compiled
3906called. If set to C<2>, then the internal verification code will be 4030called. If set to C<2>, then the internal verification code will be
3907called once per loop, which can slow down libev. If set to C<3>, then the 4031called once per loop, which can slow down libev. If set to C<3>, then the
3908verification code will be called very frequently, which will slow down 4032verification code will be called very frequently, which will slow down
3909libev considerably. 4033libev considerably.
3910 4034
3911The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be 4035The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3912C<0>. 4036will be C<0>.
3913 4037
3914=item EV_COMMON 4038=item EV_COMMON
3915 4039
3916By default, all watchers have a C<void *data> member. By redefining 4040By default, all watchers have a C<void *data> member. By redefining
3917this macro to a something else you can include more and other types of 4041this macro to a something else you can include more and other types of
3975file. 4099file.
3976 4100
3977The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 4101The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
3978that everybody includes and which overrides some configure choices: 4102that everybody includes and which overrides some configure choices:
3979 4103
3980 #define EV_MINIMAL 1 4104 #define EV_FEATURES 8
3981 #define EV_USE_POLL 0 4105 #define EV_USE_SELECT 1
3982 #define EV_MULTIPLICITY 0
3983 #define EV_PERIODIC_ENABLE 0 4106 #define EV_PREPARE_ENABLE 1
4107 #define EV_IDLE_ENABLE 1
3984 #define EV_STAT_ENABLE 0 4108 #define EV_SIGNAL_ENABLE 1
3985 #define EV_FORK_ENABLE 0 4109 #define EV_CHILD_ENABLE 1
4110 #define EV_USE_STDEXCEPT 0
3986 #define EV_CONFIG_H <config.h> 4111 #define EV_CONFIG_H <config.h>
3987 #define EV_MINPRI 0
3988 #define EV_MAXPRI 0
3989 4112
3990 #include "ev++.h" 4113 #include "ev++.h"
3991 4114
3992And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 4115And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
3993 4116
4495involves iterating over all running async watchers or all signal numbers. 4618involves iterating over all running async watchers or all signal numbers.
4496 4619
4497=back 4620=back
4498 4621
4499 4622
4623=head1 PORTING FROM 3.X TO 4.X
4624
4625The major version 4 introduced some minor incompatible changes to the API.
4626
4627=over 4
4628
4629=item C<EV_TIMEOUT> replaced by C<EV_TIMER> in C<revents>
4630
4631This is a simple rename - all other watcher types use their name
4632as revents flag, and now C<ev_timer> does, too.
4633
4634Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions
4635and continue to be present for the forseeable future, so this is mostly a
4636documentation change.
4637
4638=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
4639
4640The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
4641mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
4642and work, but the library code will of course be larger.
4643
4644=back
4645
4646
4500=head1 GLOSSARY 4647=head1 GLOSSARY
4501 4648
4502=over 4 4649=over 4
4503 4650
4504=item active 4651=item active
4525A change of state of some external event, such as data now being available 4672A change of state of some external event, such as data now being available
4526for reading on a file descriptor, time having passed or simply not having 4673for reading on a file descriptor, time having passed or simply not having
4527any other events happening anymore. 4674any other events happening anymore.
4528 4675
4529In libev, events are represented as single bits (such as C<EV_READ> or 4676In libev, events are represented as single bits (such as C<EV_READ> or
4530C<EV_TIMEOUT>). 4677C<EV_TIMER>).
4531 4678
4532=item event library 4679=item event library
4533 4680
4534A software package implementing an event model and loop. 4681A software package implementing an event model and loop.
4535 4682

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines