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

Comparing libev/ev.pod (file contents):
Revision 1.270 by root, Fri Sep 18 21:02:12 2009 UTC vs.
Revision 1.286 by root, Tue Mar 16 00:26:41 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_NOSIGFD> 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).
789 797
790Ref/unref can be used to add or remove a reference count on the event 798Ref/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 799loop: Every watcher keeps one reference, and as long as the reference
792count is nonzero, C<ev_loop> will not return on its own. 800count is nonzero, C<ev_loop> will not return on its own.
793 801
794If you have a watcher you never unregister that should not keep C<ev_loop> 802This is useful when you have a watcher that you never intend to
795from returning, call ev_unref() after starting, and ev_ref() before 803unregister, but that nevertheless should not keep C<ev_loop> from
804returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
796stopping it. 805before stopping it.
797 806
798As an example, libev itself uses this for its internal signal pipe: It 807As 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 808is 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 809exiting 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 810excellent way to do this for generic recurring timers or from within
916 925
917While event loop modifications are allowed between invocations of 926While event loop modifications are allowed between invocations of
918C<release> and C<acquire> (that's their only purpose after all), no 927C<release> and C<acquire> (that's their only purpose after all), no
919modifications done will affect the event loop, i.e. adding watchers will 928modifications 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 929have 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 930waited. Use an C<ev_async> watcher to wake up C<ev_loop> when you want it
922to take note of any changes you made. 931to take note of any changes you made.
923 932
924In theory, threads executing C<ev_loop> will be async-cancel safe between 933In theory, threads executing C<ev_loop> will be async-cancel safe between
925invocations of C<release> and C<acquire>. 934invocations of C<release> and C<acquire>.
926 935
1123 1132
1124 ev_io w; 1133 ev_io w;
1125 ev_init (&w, my_cb); 1134 ev_init (&w, my_cb);
1126 ev_io_set (&w, STDIN_FILENO, EV_READ); 1135 ev_io_set (&w, STDIN_FILENO, EV_READ);
1127 1136
1128=item C<ev_TYPE_set> (ev_TYPE *, [args]) 1137=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
1129 1138
1130This macro initialises the type-specific parts of a watcher. You need to 1139This 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 1140call 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 1141call 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 1142macro on a watcher that is active (it can be pending, however, which is a
1146 1155
1147Example: Initialise and set an C<ev_io> watcher in one step. 1156Example: Initialise and set an C<ev_io> watcher in one step.
1148 1157
1149 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); 1158 ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
1150 1159
1151=item C<ev_TYPE_start> (loop *, ev_TYPE *watcher) 1160=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
1152 1161
1153Starts (activates) the given watcher. Only active watchers will receive 1162Starts (activates) the given watcher. Only active watchers will receive
1154events. If the watcher is already active nothing will happen. 1163events. If the watcher is already active nothing will happen.
1155 1164
1156Example: Start the C<ev_io> watcher that is being abused as example in this 1165Example: Start the C<ev_io> watcher that is being abused as example in this
1157whole section. 1166whole section.
1158 1167
1159 ev_io_start (EV_DEFAULT_UC, &w); 1168 ev_io_start (EV_DEFAULT_UC, &w);
1160 1169
1161=item C<ev_TYPE_stop> (loop *, ev_TYPE *watcher) 1170=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
1162 1171
1163Stops the given watcher if active, and clears the pending status (whether 1172Stops the given watcher if active, and clears the pending status (whether
1164the watcher was active or not). 1173the watcher was active or not).
1165 1174
1166It is possible that stopped watchers are pending - for example, 1175It is possible that stopped watchers are pending - for example,
1191=item ev_cb_set (ev_TYPE *watcher, callback) 1200=item ev_cb_set (ev_TYPE *watcher, callback)
1192 1201
1193Change the callback. You can change the callback at virtually any time 1202Change the callback. You can change the callback at virtually any time
1194(modulo threads). 1203(modulo threads).
1195 1204
1196=item ev_set_priority (ev_TYPE *watcher, priority) 1205=item ev_set_priority (ev_TYPE *watcher, int priority)
1197 1206
1198=item int ev_priority (ev_TYPE *watcher) 1207=item int ev_priority (ev_TYPE *watcher)
1199 1208
1200Set and query the priority of the watcher. The priority is a small 1209Set and query the priority of the watcher. The priority is a small
1201integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI> 1210integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
1232returns its C<revents> bitset (as if its callback was invoked). If the 1241returns its C<revents> bitset (as if its callback was invoked). If the
1233watcher isn't pending it does nothing and returns C<0>. 1242watcher isn't pending it does nothing and returns C<0>.
1234 1243
1235Sometimes it can be useful to "poll" a watcher instead of waiting for its 1244Sometimes it can be useful to "poll" a watcher instead of waiting for its
1236callback to be invoked, which can be accomplished with this function. 1245callback to be invoked, which can be accomplished with this function.
1246
1247=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1248
1249Feeds the given event set into the event loop, as if the specified event
1250had happened for the specified watcher (which must be a pointer to an
1251initialised but not necessarily started event watcher). Obviously you must
1252not free the watcher as long as it has pending events.
1253
1254Stopping the watcher, letting libev invoke it, or calling
1255C<ev_clear_pending> will clear the pending event, even if the watcher was
1256not started in the first place.
1257
1258See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
1259functions that do not need a watcher.
1237 1260
1238=back 1261=back
1239 1262
1240 1263
1241=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER 1264=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
1515 1538
1516So when you encounter spurious, unexplained daemon exits, make sure you 1539So when you encounter spurious, unexplained daemon exits, make sure you
1517ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1540ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1518somewhere, as that would have given you a big clue). 1541somewhere, as that would have given you a big clue).
1519 1542
1543=head3 The special problem of accept()ing when you can't
1544
1545Many implementations of the POSIX C<accept> function (for example,
1546found in port-2004 Linux) have the peculiar behaviour of not removing a
1547connection from the pending queue in all error cases.
1548
1549For example, larger servers often run out of file descriptors (because
1550of resource limits), causing C<accept> to fail with C<ENFILE> but not
1551rejecting the connection, leading to libev signalling readiness on
1552the next iteration again (the connection still exists after all), and
1553typically causing the program to loop at 100% CPU usage.
1554
1555Unfortunately, the set of errors that cause this issue differs between
1556operating systems, there is usually little the app can do to remedy the
1557situation, and no known thread-safe method of removing the connection to
1558cope with overload is known (to me).
1559
1560One of the easiest ways to handle this situation is to just ignore it
1561- when the program encounters an overload, it will just loop until the
1562situation is over. While this is a form of busy waiting, no OS offers an
1563event-based way to handle this situation, so it's the best one can do.
1564
1565A better way to handle the situation is to log any errors other than
1566C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
1567messages, and continue as usual, which at least gives the user an idea of
1568what could be wrong ("raise the ulimit!"). For extra points one could stop
1569the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
1570usage.
1571
1572If your program is single-threaded, then you could also keep a dummy file
1573descriptor for overload situations (e.g. by opening F</dev/null>), and
1574when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
1575close that fd, and create a new dummy fd. This will gracefully refuse
1576clients under typical overload conditions.
1577
1578The last way to handle it is to simply log the error and C<exit>, as
1579is often done with C<malloc> failures, but this results in an easy
1580opportunity for a DoS attack.
1520 1581
1521=head3 Watcher-Specific Functions 1582=head3 Watcher-Specific Functions
1522 1583
1523=over 4 1584=over 4
1524 1585
1837C<repeat> value), or reset the running timer to the C<repeat> value. 1898C<repeat> value), or reset the running timer to the C<repeat> value.
1838 1899
1839This sounds a bit complicated, see L<Be smart about timeouts>, above, for a 1900This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1840usage example. 1901usage example.
1841 1902
1842=item ev_timer_remaining (loop, ev_timer *) 1903=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
1843 1904
1844Returns the remaining time until a timer fires. If the timer is active, 1905Returns 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 1906then this time is relative to the current event loop time, otherwise it's
1846the timeout value currently configured. 1907the timeout value currently configured.
1847 1908
1848That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns 1909That 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> 1910C<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 1911will 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, 1912roughly C<7> (likely slightly less as callback invocation takes some time,
1852too), and so on. 1913too), and so on.
1853 1914
1854=item ev_tstamp repeat [read-write] 1915=item ev_tstamp repeat [read-write]
2114C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should 2175C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2115not be unduly interrupted. If you have a problem with system calls getting 2176not 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 2177interrupted by signals you can block all signals in an C<ev_check> watcher
2117and unblock them in an C<ev_prepare> watcher. 2178and unblock them in an C<ev_prepare> watcher.
2118 2179
2119=head3 The special problem of inheritance over execve 2180=head3 The special problem of inheritance over fork/execve/pthread_create
2120 2181
2121Both the signal mask (C<sigprocmask>) and the signal disposition 2182Both the signal mask (C<sigprocmask>) and the signal disposition
2122(C<sigaction>) are unspecified after starting a signal watcher (and after 2183(C<sigaction>) are unspecified after starting a signal watcher (and after
2123stopping it again), that is, libev might or might not block the signal, 2184stopping it again), that is, libev might or might not block the signal,
2124and might or might not set or restore the installed signal handler. 2185and might or might not set or restore the installed signal handler.
2134 2195
2135The simplest way to ensure that the signal mask is reset in the child is 2196The simplest way to ensure that the signal mask is reset in the child is
2136to install a fork handler with C<pthread_atfork> that resets it. That will 2197to install a fork handler with C<pthread_atfork> that resets it. That will
2137catch fork calls done by libraries (such as the libc) as well. 2198catch fork calls done by libraries (such as the libc) as well.
2138 2199
2139In current versions of libev, you can also ensure that the signal mask is 2200In current versions of libev, the signal will not be blocked indefinitely
2140not blocking any signals (except temporarily, so thread users watch out) 2201unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2141by specifying the C<EVFLAG_NOSIGNALFD> when creating the event loop. This 2202the window of opportunity for problems, it will not go away, as libev
2142is not guaranteed for future versions, however. 2203I<has> to modify the signal mask, at least temporarily.
2204
2205So I can't stress this enough: I<If you do not reset your signal mask when
2206you expect it to be empty, you have a race condition in your code>. This
2207is not a libev-specific thing, this is true for most event libraries.
2143 2208
2144=head3 Watcher-Specific Functions and Data Members 2209=head3 Watcher-Specific Functions and Data Members
2145 2210
2146=over 4 2211=over 4
2147 2212
2964=head3 Queueing 3029=head3 Queueing
2965 3030
2966C<ev_async> does not support queueing of data in any way. The reason 3031C<ev_async> does not support queueing of data in any way. The reason
2967is that the author does not know of a simple (or any) algorithm for a 3032is that the author does not know of a simple (or any) algorithm for a
2968multiple-writer-single-reader queue that works in all cases and doesn't 3033multiple-writer-single-reader queue that works in all cases and doesn't
2969need elaborate support such as pthreads. 3034need elaborate support such as pthreads or unportable memory access
3035semantics.
2970 3036
2971That means that if you want to queue data, you have to provide your own 3037That means that if you want to queue data, you have to provide your own
2972queue. But at least I can tell you how to implement locking around your 3038queue. But at least I can tell you how to implement locking around your
2973queue: 3039queue:
2974 3040
3132 /* doh, nothing entered */; 3198 /* doh, nothing entered */;
3133 } 3199 }
3134 3200
3135 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3201 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3136 3202
3137=item ev_feed_event (struct ev_loop *, watcher *, int revents)
3138
3139Feeds the given event set into the event loop, as if the specified event
3140had happened for the specified watcher (which must be a pointer to an
3141initialised but not necessarily started event watcher).
3142
3143=item ev_feed_fd_event (struct ev_loop *, int fd, int revents) 3203=item ev_feed_fd_event (loop, int fd, int revents)
3144 3204
3145Feed an event on the given fd, as if a file descriptor backend detected 3205Feed an event on the given fd, as if a file descriptor backend detected
3146the given events it. 3206the given events it.
3147 3207
3148=item ev_feed_signal_event (struct ev_loop *loop, int signum) 3208=item ev_feed_signal_event (loop, int signum)
3149 3209
3150Feed an event as if the given signal occurred (C<loop> must be the default 3210Feed an event as if the given signal occurred (C<loop> must be the default
3151loop!). 3211loop!).
3152 3212
3153=back 3213=back
3233 3293
3234=over 4 3294=over 4
3235 3295
3236=item ev::TYPE::TYPE () 3296=item ev::TYPE::TYPE ()
3237 3297
3238=item ev::TYPE::TYPE (struct ev_loop *) 3298=item ev::TYPE::TYPE (loop)
3239 3299
3240=item ev::TYPE::~TYPE 3300=item ev::TYPE::~TYPE
3241 3301
3242The constructor (optionally) takes an event loop to associate the watcher 3302The constructor (optionally) takes an event loop to associate the watcher
3243with. If it is omitted, it will use C<EV_DEFAULT>. 3303with. If it is omitted, it will use C<EV_DEFAULT>.
3320Example: Use a plain function as callback. 3380Example: Use a plain function as callback.
3321 3381
3322 static void io_cb (ev::io &w, int revents) { } 3382 static void io_cb (ev::io &w, int revents) { }
3323 iow.set <io_cb> (); 3383 iow.set <io_cb> ();
3324 3384
3325=item w->set (struct ev_loop *) 3385=item w->set (loop)
3326 3386
3327Associates a different C<struct ev_loop> with this watcher. You can only 3387Associates a different C<struct ev_loop> with this watcher. You can only
3328do this when the watcher is inactive (and not pending either). 3388do this when the watcher is inactive (and not pending either).
3329 3389
3330=item w->set ([arguments]) 3390=item w->set ([arguments])
3429Erkki Seppala has written Ocaml bindings for libev, to be found at 3489Erkki Seppala has written Ocaml bindings for libev, to be found at
3430L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 3490L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3431 3491
3432=item Lua 3492=item Lua
3433 3493
3434Brian Maher has written a partial interface to libev 3494Brian Maher has written a partial interface to libev for lua (at the
3435for lua (only C<ev_io> and C<ev_timer>), to be found at 3495time of this writing, only C<ev_io> and C<ev_timer>), to be found at
3436L<http://github.com/brimworks/lua-ev>. 3496L<http://github.com/brimworks/lua-ev>.
3437 3497
3438=back 3498=back
3439 3499
3440 3500
3595 libev.m4 3655 libev.m4
3596 3656
3597=head2 PREPROCESSOR SYMBOLS/MACROS 3657=head2 PREPROCESSOR SYMBOLS/MACROS
3598 3658
3599Libev can be configured via a variety of preprocessor symbols you have to 3659Libev can be configured via a variety of preprocessor symbols you have to
3600define before including any of its files. The default in the absence of 3660define before including (or compiling) any of its files. The default in
3601autoconf is documented for every option. 3661the absence of autoconf is documented for every option.
3662
3663Symbols marked with "(h)" do not change the ABI, and can have different
3664values when compiling libev vs. including F<ev.h>, so it is permissible
3665to redefine them before including F<ev.h> without breakign compatibility
3666to a compiled library. All other symbols change the ABI, which means all
3667users of libev and the libev code itself must be compiled with compatible
3668settings.
3602 3669
3603=over 4 3670=over 4
3604 3671
3605=item EV_STANDALONE 3672=item EV_STANDALONE (h)
3606 3673
3607Must always be C<1> if you do not use autoconf configuration, which 3674Must always be C<1> if you do not use autoconf configuration, which
3608keeps libev from including F<config.h>, and it also defines dummy 3675keeps libev from including F<config.h>, and it also defines dummy
3609implementations for some libevent functions (such as logging, which is not 3676implementations for some libevent functions (such as logging, which is not
3610supported). It will also not define any of the structs usually found in 3677supported). It will also not define any of the structs usually found in
3760as well as for signal and thread safety in C<ev_async> watchers. 3827as well as for signal and thread safety in C<ev_async> watchers.
3761 3828
3762In the absence of this define, libev will use C<sig_atomic_t volatile> 3829In the absence of this define, libev will use C<sig_atomic_t volatile>
3763(from F<signal.h>), which is usually good enough on most platforms. 3830(from F<signal.h>), which is usually good enough on most platforms.
3764 3831
3765=item EV_H 3832=item EV_H (h)
3766 3833
3767The name of the F<ev.h> header file used to include it. The default if 3834The name of the F<ev.h> header file used to include it. The default if
3768undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 3835undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
3769used to virtually rename the F<ev.h> header file in case of conflicts. 3836used to virtually rename the F<ev.h> header file in case of conflicts.
3770 3837
3771=item EV_CONFIG_H 3838=item EV_CONFIG_H (h)
3772 3839
3773If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 3840If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
3774F<ev.c>'s idea of where to find the F<config.h> file, similarly to 3841F<ev.c>'s idea of where to find the F<config.h> file, similarly to
3775C<EV_H>, above. 3842C<EV_H>, above.
3776 3843
3777=item EV_EVENT_H 3844=item EV_EVENT_H (h)
3778 3845
3779Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 3846Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
3780of how the F<event.h> header can be found, the default is C<"event.h">. 3847of how the F<event.h> header can be found, the default is C<"event.h">.
3781 3848
3782=item EV_PROTOTYPES 3849=item EV_PROTOTYPES (h)
3783 3850
3784If defined to be C<0>, then F<ev.h> will not define any function 3851If defined to be C<0>, then F<ev.h> will not define any function
3785prototypes, but still define all the structs and other symbols. This is 3852prototypes, but still define all the structs and other symbols. This is
3786occasionally useful if you want to provide your own wrapper functions 3853occasionally useful if you want to provide your own wrapper functions
3787around libev functions. 3854around libev functions.
3809fine. 3876fine.
3810 3877
3811If your embedding application does not need any priorities, defining these 3878If your embedding application does not need any priorities, defining these
3812both to C<0> will save some memory and CPU. 3879both to C<0> will save some memory and CPU.
3813 3880
3814=item EV_PERIODIC_ENABLE 3881=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
3882EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
3883EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3815 3884
3816If undefined or defined to be C<1>, then periodic timers are supported. If 3885If undefined or defined to be C<1> (and the platform supports it), then
3817defined to be C<0>, then they are not. Disabling them saves a few kB of 3886the respective watcher type is supported. If defined to be C<0>, then it
3818code. 3887is not. Disabling watcher types mainly saves codesize.
3819 3888
3820=item EV_IDLE_ENABLE 3889=item EV_FEATURES
3821
3822If undefined or defined to be C<1>, then idle watchers are supported. If
3823defined to be C<0>, then they are not. Disabling them saves a few kB of
3824code.
3825
3826=item EV_EMBED_ENABLE
3827
3828If undefined or defined to be C<1>, then embed watchers are supported. If
3829defined to be C<0>, then they are not. Embed watchers rely on most other
3830watcher types, which therefore must not be disabled.
3831
3832=item EV_STAT_ENABLE
3833
3834If undefined or defined to be C<1>, then stat watchers are supported. If
3835defined to be C<0>, then they are not.
3836
3837=item EV_FORK_ENABLE
3838
3839If undefined or defined to be C<1>, then fork watchers are supported. If
3840defined to be C<0>, then they are not.
3841
3842=item EV_ASYNC_ENABLE
3843
3844If undefined or defined to be C<1>, then async watchers are supported. If
3845defined to be C<0>, then they are not.
3846
3847=item EV_MINIMAL
3848 3890
3849If you need to shave off some kilobytes of code at the expense of some 3891If you need to shave off some kilobytes of code at the expense of some
3850speed (but with the full API), define this symbol to C<1>. Currently this 3892speed (but with the full API), you can define this symbol to request
3851is used to override some inlining decisions, saves roughly 30% code size 3893certain subsets of functionality. The default is to enable all features
3852on amd64. It also selects a much smaller 2-heap for timer management over 3894that can be enabled on the platform.
3853the default 4-heap.
3854 3895
3855You can save even more by disabling watcher types you do not need 3896Note that using autoconf will usually override most of the features, so
3856and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> 3897using this symbol makes sense mostly when embedding libev.
3857(C<-DNDEBUG>) will usually reduce code size a lot.
3858 3898
3859Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to 3899A typical way to use this symbol is to define it to C<0> (or to a bitset
3860provide a bare-bones event library. See C<ev.h> for details on what parts 3900with some broad features you want) and then selectively re-enable
3861of the API are still available, and do not complain if this subset changes 3901additional parts you want, for example if you want everything minimal,
3862over time. 3902but multiple event loop support, async and child watchers and the poll
3903backend, use this:
3904
3905 #define EV_FEATURES 0
3906 #define EV_MULTIPLICITY 1
3907 #define EV_USE_POLL 1
3908 #define EV_CHILD_ENABLE 1
3909 #define EV_ASYNC_ENABLE 1
3910
3911The actual value is a bitset, it can be a combination of the following
3912values:
3913
3914=over 4
3915
3916=item C<1> - faster/larger code
3917
3918Use larger code to speed up some operations.
3919
3920Currently this is used to override some inlining decisions (enlarging the roughly
392130% code size on amd64.
3922
3923When optimising for size, use of compiler flags such as C<-Os> with
3924gcc recommended, as well as C<-DNDEBUG>, as libev contains a number of
3925assertions.
3926
3927=item C<2> - faster/larger data structures
3928
3929Replaces the small 2-heap for timer management by a faster 4-heap, larger
3930hash table sizes and so on. This will usually further increase codesize
3931and can additionally have an effect on the size of data structures at
3932runtime.
3933
3934=item C<4> - full API configuration
3935
3936This enables priorities (sets C<EV_MAXPRI>=2 and C<EV_MINPRI>=-2), and
3937enables multiplicity (C<EV_MULTIPLICITY>=1).
3938
3939It also enables a lot of the "lesser used" core API functions. See C<ev.h>
3940for details on which parts of the API are still available without this
3941feature, and do not complain if this subset changes over time.
3942
3943=item C<8> - enable all optional watcher types
3944
3945Enables all optional watcher types. If you want to selectively enable
3946only some watcher types other than I/O and timers (e.g. prepare,
3947embed, async, child...) you can enable them manually by defining
3948C<EV_watchertype_ENABLE> to C<1> instead.
3949
3950=item C<16> - enable all backends
3951
3952This enables all backends - without this feature, you need to enable at
3953least one backend manually (C<EV_USE_SELECT> is a good choice).
3954
3955=item C<32> - enable OS-specific "helper" APIs
3956
3957Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
3958default.
3959
3960=back
3961
3962Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
3963reduces the compiled size of libev from 24.7Kb to 6.5Kb on my GNU/Linux
3964amd64 system, while still giving you I/O watchers, timers and monotonic
3965clock support.
3966
3967With an intelligent-enough linker (gcc+binutils are intelligent enough
3968when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
3969your program might be left out as well - a binary starting a timer and an
3970I/O watcher then might come out at only 5Kb.
3971
3972=item EV_AVOID_STDIO
3973
3974If this is set to C<1> at compiletime, then libev will avoid using stdio
3975functions (printf, scanf, perror etc.). This will increase the codesize
3976somewhat, but if your program doesn't otherwise depend on stdio and your
3977libc allows it, this avoids linking in the stdio library which is quite
3978big.
3979
3980Note that error messages might become less precise when this option is
3981enabled.
3863 3982
3864=item EV_NSIG 3983=item EV_NSIG
3865 3984
3866The highest supported signal number, +1 (or, the number of 3985The highest supported signal number, +1 (or, the number of
3867signals): Normally, libev tries to deduce the maximum number of signals 3986signals): Normally, libev tries to deduce the maximum number of signals
3871statically allocates some 12-24 bytes per signal number. 3990statically allocates some 12-24 bytes per signal number.
3872 3991
3873=item EV_PID_HASHSIZE 3992=item EV_PID_HASHSIZE
3874 3993
3875C<ev_child> watchers use a small hash table to distribute workload by 3994C<ev_child> watchers use a small hash table to distribute workload by
3876pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 3995pid. The default size is C<16> (or C<1> with C<EV_FEATURES> disabled),
3877than enough. If you need to manage thousands of children you might want to 3996usually more than enough. If you need to manage thousands of children you
3878increase this value (I<must> be a power of two). 3997might want to increase this value (I<must> be a power of two).
3879 3998
3880=item EV_INOTIFY_HASHSIZE 3999=item EV_INOTIFY_HASHSIZE
3881 4000
3882C<ev_stat> watchers use a small hash table to distribute workload by 4001C<ev_stat> watchers use a small hash table to distribute workload by
3883inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 4002inotify watch id. The default size is C<16> (or C<1> with C<EV_FEATURES>
3884usually more than enough. If you need to manage thousands of C<ev_stat> 4003disabled), usually more than enough. If you need to manage thousands of
3885watchers you might want to increase this value (I<must> be a power of 4004C<ev_stat> watchers you might want to increase this value (I<must> be a
3886two). 4005power of two).
3887 4006
3888=item EV_USE_4HEAP 4007=item EV_USE_4HEAP
3889 4008
3890Heaps are not very cache-efficient. To improve the cache-efficiency of the 4009Heaps are not very cache-efficient. To improve the cache-efficiency of the
3891timer and periodics heaps, libev uses a 4-heap when this symbol is defined 4010timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3892to C<1>. The 4-heap uses more complicated (longer) code but has noticeably 4011to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3893faster performance with many (thousands) of watchers. 4012faster performance with many (thousands) of watchers.
3894 4013
3895The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4014The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3896(disabled). 4015will be C<0>.
3897 4016
3898=item EV_HEAP_CACHE_AT 4017=item EV_HEAP_CACHE_AT
3899 4018
3900Heaps are not very cache-efficient. To improve the cache-efficiency of the 4019Heaps are not very cache-efficient. To improve the cache-efficiency of the
3901timer and periodics heaps, libev can cache the timestamp (I<at>) within 4020timer and periodics heaps, libev can cache the timestamp (I<at>) within
3902the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), 4021the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3903which uses 8-12 bytes more per watcher and a few hundred bytes more code, 4022which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3904but avoids random read accesses on heap changes. This improves performance 4023but avoids random read accesses on heap changes. This improves performance
3905noticeably with many (hundreds) of watchers. 4024noticeably with many (hundreds) of watchers.
3906 4025
3907The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4026The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3908(disabled). 4027will be C<0>.
3909 4028
3910=item EV_VERIFY 4029=item EV_VERIFY
3911 4030
3912Controls how much internal verification (see C<ev_loop_verify ()>) will 4031Controls how much internal verification (see C<ev_loop_verify ()>) will
3913be done: If set to C<0>, no internal verification code will be compiled 4032be done: If set to C<0>, no internal verification code will be compiled
3915called. If set to C<2>, then the internal verification code will be 4034called. If set to C<2>, then the internal verification code will be
3916called once per loop, which can slow down libev. If set to C<3>, then the 4035called once per loop, which can slow down libev. If set to C<3>, then the
3917verification code will be called very frequently, which will slow down 4036verification code will be called very frequently, which will slow down
3918libev considerably. 4037libev considerably.
3919 4038
3920The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be 4039The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3921C<0>. 4040will be C<0>.
3922 4041
3923=item EV_COMMON 4042=item EV_COMMON
3924 4043
3925By default, all watchers have a C<void *data> member. By redefining 4044By default, all watchers have a C<void *data> member. By redefining
3926this macro to a something else you can include more and other types of 4045this macro to a something else you can include more and other types of
3984file. 4103file.
3985 4104
3986The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 4105The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
3987that everybody includes and which overrides some configure choices: 4106that everybody includes and which overrides some configure choices:
3988 4107
3989 #define EV_MINIMAL 1 4108 #define EV_FEATURES 0
3990 #define EV_USE_POLL 0 4109 #define EV_USE_SELECT 1
3991 #define EV_MULTIPLICITY 0
3992 #define EV_PERIODIC_ENABLE 0
3993 #define EV_STAT_ENABLE 0
3994 #define EV_FORK_ENABLE 0
3995 #define EV_CONFIG_H <config.h> 4110 #define EV_CONFIG_H <config.h>
3996 #define EV_MINPRI 0
3997 #define EV_MAXPRI 0
3998 4111
3999 #include "ev++.h" 4112 #include "ev++.h"
4000 4113
4001And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 4114And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
4002 4115

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines