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

Comparing libev/ev.pod (file contents):
Revision 1.277 by root, Thu Dec 31 06:50:17 2009 UTC vs.
Revision 1.297 by root, Tue Jun 29 11:49:02 2010 UTC

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
129the (fractional) number of seconds since the (POSIX) epoch (somewhere 129the (fractional) number of seconds since the (POSIX) epoch (in practise
130near the beginning of 1970, details are complicated, don't ask). This 130somewhere near the beginning of 1970, details are complicated, don't
131type is called C<ev_tstamp>, which is what you should use too. It usually 131ask). This type is called C<ev_tstamp>, which is what you should use
132aliases to the C<double> type in C. When you need to do any calculations 132too. It usually aliases to the C<double> type in C. When you need to do
133on it, you should treat it as some floating point value. Unlike the name 133any calculations on it, you should treat it as some floating point value.
134
134component C<stamp> might indicate, it is also used for time differences 135Unlike the name component C<stamp> might indicate, it is also used for
135throughout libev. 136time differences (e.g. delays) throughout libev.
136 137
137=head1 ERROR HANDLING 138=head1 ERROR HANDLING
138 139
139Libev knows three classes of errors: operating system errors, usage errors 140Libev knows three classes of errors: operating system errors, usage errors
140and internal errors (bugs). 141and internal errors (bugs).
191as this indicates an incompatible change. Minor versions are usually 192as this indicates an incompatible change. Minor versions are usually
192compatible to older versions, so a larger minor version alone is usually 193compatible to older versions, so a larger minor version alone is usually
193not a problem. 194not a problem.
194 195
195Example: Make sure we haven't accidentally been linked against the wrong 196Example: Make sure we haven't accidentally been linked against the wrong
196version. 197version (note, however, that this will not detect ABI mismatches :).
197 198
198 assert (("libev version mismatch", 199 assert (("libev version mismatch",
199 ev_version_major () == EV_VERSION_MAJOR 200 ev_version_major () == EV_VERSION_MAJOR
200 && ev_version_minor () >= EV_VERSION_MINOR)); 201 && ev_version_minor () >= EV_VERSION_MINOR));
201 202
345useful to try out specific backends to test their performance, or to work 346useful to try out specific backends to test their performance, or to work
346around bugs. 347around bugs.
347 348
348=item C<EVFLAG_FORKCHECK> 349=item C<EVFLAG_FORKCHECK>
349 350
350Instead of calling C<ev_default_fork> or C<ev_loop_fork> manually after 351Instead of calling C<ev_loop_fork> manually after a fork, you can also
351a fork, you can also make libev check for a fork in each iteration by 352make libev check for a fork in each iteration by enabling this flag.
352enabling this flag.
353 353
354This works by calling C<getpid ()> on every iteration of the loop, 354This works by calling C<getpid ()> on every iteration of the loop,
355and thus this might slow down your event loop if you do a lot of loop 355and thus this might slow down your event loop if you do a lot of loop
356iterations and little real work, but is usually not noticeable (on my 356iterations and little real work, but is usually not noticeable (on my
357GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence 357GNU/Linux system for example, C<getpid> is actually a simple 5-insn sequence
374 374
375=item C<EVFLAG_SIGNALFD> 375=item C<EVFLAG_SIGNALFD>
376 376
377When this flag is specified, then libev will 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 API 378I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
379delivers signals synchronously, which makes is both faster and might make 379delivers signals synchronously, which makes it both faster and might make
380it possible to get the queued signal data. 380it possible to get the queued signal data. It can also simplify signal
381handling with threads, as long as you properly block signals in your
382threads that are not interested in handling them.
381 383
382Signalfd will not be used by default as this changes your signal mask, and 384Signalfd will not be used by default as this changes your signal mask, and
383there are a lot of shoddy libraries and programs (glib's threadpool for 385there are a lot of shoddy libraries and programs (glib's threadpool for
384example) that can't properly initialise their signal masks. 386example) that can't properly initialise their signal masks.
385 387
565 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); 567 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
566 568
567=item struct ev_loop *ev_loop_new (unsigned int flags) 569=item struct ev_loop *ev_loop_new (unsigned int flags)
568 570
569Similar 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
570always distinct from the default loop. Unlike the default loop, it cannot 572always distinct from the default loop.
571handle signal and child watchers, and attempts to do so will be greeted by
572undefined behaviour (or a failed assertion if assertions are enabled).
573 573
574Note 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
575libev 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
576default loop in the "main" or "initial" thread. 576default loop in the "main" or "initial" thread.
577 577
578Example: 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.
579 579
581 if (!epoller) 581 if (!epoller)
582 fatal ("no epoll found here, maybe it hides under your chair"); 582 fatal ("no epoll found here, maybe it hides under your chair");
583 583
584=item ev_default_destroy () 584=item ev_default_destroy ()
585 585
586Destroys the default loop again (frees all memory and kernel state 586Destroys the default loop (frees all memory and kernel state etc.). None
587etc.). 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
588sense, 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
589responsibility to either stop all watchers cleanly yourself I<before> 589either stop all watchers cleanly yourself I<before> calling this function,
590calling this function, or cope with the fact afterwards (which is usually 590or cope with the fact afterwards (which is usually the easiest thing, you
591the 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).
592for example).
593 592
594Note that certain global state, such as signal state (and installed signal 593Note that certain global state, such as signal state (and installed signal
595handlers), will not be freed by this function, and related watchers (such 594handlers), will not be freed by this function, and related watchers (such
596as signal and child watchers) would need to be stopped manually. 595as signal and child watchers) would need to be stopped manually.
597 596
612name, you can call it anytime, but it makes most sense after forking, in 611name, you can call it anytime, but it makes most sense after forking, in
613the child process (or both child and parent, but that again makes little 612the child process (or both child and parent, but that again makes little
614sense). You I<must> call it in the child before using any of the libev 613sense). You I<must> call it in the child before using any of the libev
615functions, and it will only take effect at the next C<ev_loop> iteration. 614functions, and it will only take effect at the next C<ev_loop> iteration.
616 615
616Again, you I<have> to call it on I<any> loop that you want to re-use after
617a fork, I<even if you do not plan to use the loop in the parent>. This is
618because some kernel interfaces *cough* I<kqueue> *cough* do funny things
619during fork.
620
617On the other hand, you only need to call this function in the child 621On the other hand, you only need to call this function in the child
618process if and only if you want to use the event library in the child. If 622process if and only if you want to use the event loop in the child. If you
619you just fork+exec, you don't have to call it at all. 623just fork+exec or create a new loop in the child, you don't have to call
624it at all.
620 625
621The function itself is quite fast and it's usually not a problem to call 626The function itself is quite fast and it's usually not a problem to call
622it just in case after a fork. To make this easy, the function will fit in 627it just in case after a fork. To make this easy, the function will fit in
623quite nicely into a call to C<pthread_atfork>: 628quite nicely into a call to C<pthread_atfork>:
624 629
626 631
627=item ev_loop_fork (loop) 632=item ev_loop_fork (loop)
628 633
629Like C<ev_default_fork>, but acts on an event loop created by 634Like C<ev_default_fork>, but acts on an event loop created by
630C<ev_loop_new>. Yes, you have to call this on every allocated event loop 635C<ev_loop_new>. Yes, you have to call this on every allocated event loop
631after fork that you want to re-use in the child, and how you do this is 636after fork that you want to re-use in the child, and how you keep track of
632entirely your own problem. 637them is entirely your own problem.
633 638
634=item int ev_is_default_loop (loop) 639=item int ev_is_default_loop (loop)
635 640
636Returns true when the given loop is, in fact, the default loop, and false 641Returns true when the given loop is, in fact, the default loop, and false
637otherwise. 642otherwise.
638 643
639=item unsigned int ev_loop_count (loop) 644=item unsigned int ev_iteration (loop)
640 645
641Returns the count of loop iterations for the loop, which is identical to 646Returns the current iteration count for the loop, which is identical to
642the number of times libev did poll for new events. It starts at C<0> and 647the number of times libev did poll for new events. It starts at C<0> and
643happily wraps around with enough iterations. 648happily wraps around with enough iterations.
644 649
645This value can sometimes be useful as a generation counter of sorts (it 650This value can sometimes be useful as a generation counter of sorts (it
646"ticks" the number of loop iterations), as it roughly corresponds with 651"ticks" the number of loop iterations), as it roughly corresponds with
647C<ev_prepare> and C<ev_check> calls. 652C<ev_prepare> and C<ev_check> calls - and is incremented between the
653prepare and check phases.
648 654
649=item unsigned int ev_loop_depth (loop) 655=item unsigned int ev_depth (loop)
650 656
651Returns the number of times C<ev_loop> was entered minus the number of 657Returns the number of times C<ev_loop> was entered minus the number of
652times C<ev_loop> was exited, in other words, the recursion depth. 658times C<ev_loop> was exited, in other words, the recursion depth.
653 659
654Outside C<ev_loop>, this number is zero. In a callback, this number is 660Outside C<ev_loop>, this number is zero. In a callback, this number is
655C<1>, unless C<ev_loop> was invoked recursively (or from another thread), 661C<1>, unless C<ev_loop> was invoked recursively (or from another thread),
656in which case it is higher. 662in which case it is higher.
657 663
658Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread 664Leaving C<ev_loop> abnormally (setjmp/longjmp, cancelling the thread
659etc.), doesn't count as exit. 665etc.), doesn't count as "exit" - consider this as a hint to avoid such
666ungentleman behaviour unless it's really convenient.
660 667
661=item unsigned int ev_backend (loop) 668=item unsigned int ev_backend (loop)
662 669
663Returns one of the C<EVBACKEND_*> flags indicating the event backend in 670Returns one of the C<EVBACKEND_*> flags indicating the event backend in
664use. 671use.
1030=item C<EV_WRITE> 1037=item C<EV_WRITE>
1031 1038
1032The file descriptor in the C<ev_io> watcher has become readable and/or 1039The file descriptor in the C<ev_io> watcher has become readable and/or
1033writable. 1040writable.
1034 1041
1035=item C<EV_TIMEOUT> 1042=item C<EV_TIMER>
1036 1043
1037The C<ev_timer> watcher has timed out. 1044The C<ev_timer> watcher has timed out.
1038 1045
1039=item C<EV_PERIODIC> 1046=item C<EV_PERIODIC>
1040 1047
1397 { 1404 {
1398 // stop the I/O watcher, we received the event, but 1405 // stop the I/O watcher, we received the event, but
1399 // are not yet ready to handle it. 1406 // are not yet ready to handle it.
1400 ev_io_stop (EV_A_ w); 1407 ev_io_stop (EV_A_ w);
1401 1408
1402 // start the idle watcher to ahndle the actual event. 1409 // start the idle watcher to handle the actual event.
1403 // it will not be executed as long as other watchers 1410 // it will not be executed as long as other watchers
1404 // with the default priority are receiving events. 1411 // with the default priority are receiving events.
1405 ev_idle_start (EV_A_ &idle); 1412 ev_idle_start (EV_A_ &idle);
1406 } 1413 }
1407 1414
1536 1543
1537So when you encounter spurious, unexplained daemon exits, make sure you 1544So when you encounter spurious, unexplained daemon exits, make sure you
1538ignore SIGPIPE (and maybe make sure you log the exit status of your daemon 1545ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1539somewhere, as that would have given you a big clue). 1546somewhere, as that would have given you a big clue).
1540 1547
1548=head3 The special problem of accept()ing when you can't
1549
1550Many implementations of the POSIX C<accept> function (for example,
1551found in post-2004 Linux) have the peculiar behaviour of not removing a
1552connection from the pending queue in all error cases.
1553
1554For example, larger servers often run out of file descriptors (because
1555of resource limits), causing C<accept> to fail with C<ENFILE> but not
1556rejecting the connection, leading to libev signalling readiness on
1557the next iteration again (the connection still exists after all), and
1558typically causing the program to loop at 100% CPU usage.
1559
1560Unfortunately, the set of errors that cause this issue differs between
1561operating systems, there is usually little the app can do to remedy the
1562situation, and no known thread-safe method of removing the connection to
1563cope with overload is known (to me).
1564
1565One of the easiest ways to handle this situation is to just ignore it
1566- when the program encounters an overload, it will just loop until the
1567situation is over. While this is a form of busy waiting, no OS offers an
1568event-based way to handle this situation, so it's the best one can do.
1569
1570A better way to handle the situation is to log any errors other than
1571C<EAGAIN> and C<EWOULDBLOCK>, making sure not to flood the log with such
1572messages, and continue as usual, which at least gives the user an idea of
1573what could be wrong ("raise the ulimit!"). For extra points one could stop
1574the C<ev_io> watcher on the listening fd "for a while", which reduces CPU
1575usage.
1576
1577If your program is single-threaded, then you could also keep a dummy file
1578descriptor for overload situations (e.g. by opening F</dev/null>), and
1579when you run into C<ENFILE> or C<EMFILE>, close it, run C<accept>,
1580close that fd, and create a new dummy fd. This will gracefully refuse
1581clients under typical overload conditions.
1582
1583The last way to handle it is to simply log the error and C<exit>, as
1584is often done with C<malloc> failures, but this results in an easy
1585opportunity for a DoS attack.
1541 1586
1542=head3 Watcher-Specific Functions 1587=head3 Watcher-Specific Functions
1543 1588
1544=over 4 1589=over 4
1545 1590
1724to the current time (meaning we just have some activity :), then call the 1769to the current time (meaning we just have some activity :), then call the
1725callback, which will "do the right thing" and start the timer: 1770callback, which will "do the right thing" and start the timer:
1726 1771
1727 ev_init (timer, callback); 1772 ev_init (timer, callback);
1728 last_activity = ev_now (loop); 1773 last_activity = ev_now (loop);
1729 callback (loop, timer, EV_TIMEOUT); 1774 callback (loop, timer, EV_TIMER);
1730 1775
1731And when there is some activity, simply store the current time in 1776And when there is some activity, simply store the current time in
1732C<last_activity>, no libev calls at all: 1777C<last_activity>, no libev calls at all:
1733 1778
1734 last_actiivty = ev_now (loop); 1779 last_activity = ev_now (loop);
1735 1780
1736This technique is slightly more complex, but in most cases where the 1781This technique is slightly more complex, but in most cases where the
1737time-out is unlikely to be triggered, much more efficient. 1782time-out is unlikely to be triggered, much more efficient.
1738 1783
1739Changing the timeout is trivial as well (if it isn't hard-coded in the 1784Changing the timeout is trivial as well (if it isn't hard-coded in the
1865Returns the remaining time until a timer fires. If the timer is active, 1910Returns the remaining time until a timer fires. If the timer is active,
1866then this time is relative to the current event loop time, otherwise it's 1911then this time is relative to the current event loop time, otherwise it's
1867the timeout value currently configured. 1912the timeout value currently configured.
1868 1913
1869That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns 1914That is, after an C<ev_timer_set (w, 5, 7)>, C<ev_timer_remaining> returns
1870C<5>. When the timer is started and one second passes, C<ev_timer_remain> 1915C<5>. When the timer is started and one second passes, C<ev_timer_remaining>
1871will return C<4>. When the timer expires and is restarted, it will return 1916will return C<4>. When the timer expires and is restarted, it will return
1872roughly C<7> (likely slightly less as callback invocation takes some time, 1917roughly C<7> (likely slightly less as callback invocation takes some time,
1873too), and so on. 1918too), and so on.
1874 1919
1875=item ev_tstamp repeat [read-write] 1920=item ev_tstamp repeat [read-write]
2160In current versions of libev, the signal will not be blocked indefinitely 2205In current versions of libev, the signal will not be blocked indefinitely
2161unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces 2206unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2162the window of opportunity for problems, it will not go away, as libev 2207the window of opportunity for problems, it will not go away, as libev
2163I<has> to modify the signal mask, at least temporarily. 2208I<has> to modify the signal mask, at least temporarily.
2164 2209
2165So I can't stress this enough I<if you do not reset your signal mask 2210So I can't stress this enough: I<If you do not reset your signal mask when
2166when you expect it to be empty, you have a race condition in your 2211you expect it to be empty, you have a race condition in your code>. This
2167program>. This is not a libev-specific thing, this is true for most event 2212is not a libev-specific thing, this is true for most event libraries.
2168libraries.
2169 2213
2170=head3 Watcher-Specific Functions and Data Members 2214=head3 Watcher-Specific Functions and Data Members
2171 2215
2172=over 4 2216=over 4
2173 2217
3140 3184
3141If C<timeout> is less than 0, then no timeout watcher will be 3185If C<timeout> is less than 0, then no timeout watcher will be
3142started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 3186started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
3143repeat = 0) will be started. C<0> is a valid timeout. 3187repeat = 0) will be started. C<0> is a valid timeout.
3144 3188
3145The callback has the type C<void (*cb)(int revents, void *arg)> and gets 3189The callback has the type C<void (*cb)(int revents, void *arg)> and is
3146passed an C<revents> set like normal event callbacks (a combination of 3190passed an C<revents> set like normal event callbacks (a combination of
3147C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMEOUT>) and the C<arg> 3191C<EV_ERROR>, C<EV_READ>, C<EV_WRITE> or C<EV_TIMER>) and the C<arg>
3148value passed to C<ev_once>. Note that it is possible to receive I<both> 3192value passed to C<ev_once>. Note that it is possible to receive I<both>
3149a timeout and an io event at the same time - you probably should give io 3193a timeout and an io event at the same time - you probably should give io
3150events precedence. 3194events precedence.
3151 3195
3152Example: wait up to ten seconds for data to appear on STDIN_FILENO. 3196Example: wait up to ten seconds for data to appear on STDIN_FILENO.
3153 3197
3154 static void stdin_ready (int revents, void *arg) 3198 static void stdin_ready (int revents, void *arg)
3155 { 3199 {
3156 if (revents & EV_READ) 3200 if (revents & EV_READ)
3157 /* stdin might have data for us, joy! */; 3201 /* stdin might have data for us, joy! */;
3158 else if (revents & EV_TIMEOUT) 3202 else if (revents & EV_TIMER)
3159 /* doh, nothing entered */; 3203 /* doh, nothing entered */;
3160 } 3204 }
3161 3205
3162 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3206 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3163 3207
3297 myclass obj; 3341 myclass obj;
3298 ev::io iow; 3342 ev::io iow;
3299 iow.set <myclass, &myclass::io_cb> (&obj); 3343 iow.set <myclass, &myclass::io_cb> (&obj);
3300 3344
3301=item w->set (object *) 3345=item w->set (object *)
3302
3303This is an B<experimental> feature that might go away in a future version.
3304 3346
3305This is a variation of a method callback - leaving out the method to call 3347This is a variation of a method callback - leaving out the method to call
3306will default the method to C<operator ()>, which makes it possible to use 3348will default the method to C<operator ()>, which makes it possible to use
3307functor objects without having to manually specify the C<operator ()> all 3349functor objects without having to manually specify the C<operator ()> all
3308the time. Incidentally, you can then also leave out the template argument 3350the time. Incidentally, you can then also leave out the template argument
3450Erkki Seppala has written Ocaml bindings for libev, to be found at 3492Erkki Seppala has written Ocaml bindings for libev, to be found at
3451L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>. 3493L<http://modeemi.cs.tut.fi/~flux/software/ocaml-ev/>.
3452 3494
3453=item Lua 3495=item Lua
3454 3496
3455Brian Maher has written a partial interface to libev 3497Brian Maher has written a partial interface to libev for lua (at the
3456for lua (only C<ev_io> and C<ev_timer>), to be found at 3498time of this writing, only C<ev_io> and C<ev_timer>), to be found at
3457L<http://github.com/brimworks/lua-ev>. 3499L<http://github.com/brimworks/lua-ev>.
3458 3500
3459=back 3501=back
3460 3502
3461 3503
3616 libev.m4 3658 libev.m4
3617 3659
3618=head2 PREPROCESSOR SYMBOLS/MACROS 3660=head2 PREPROCESSOR SYMBOLS/MACROS
3619 3661
3620Libev can be configured via a variety of preprocessor symbols you have to 3662Libev can be configured via a variety of preprocessor symbols you have to
3621define before including any of its files. The default in the absence of 3663define before including (or compiling) any of its files. The default in
3622autoconf is documented for every option. 3664the absence of autoconf is documented for every option.
3665
3666Symbols marked with "(h)" do not change the ABI, and can have different
3667values when compiling libev vs. including F<ev.h>, so it is permissible
3668to redefine them before including F<ev.h> without breaking compatibility
3669to a compiled library. All other symbols change the ABI, which means all
3670users of libev and the libev code itself must be compiled with compatible
3671settings.
3623 3672
3624=over 4 3673=over 4
3625 3674
3626=item EV_STANDALONE 3675=item EV_STANDALONE (h)
3627 3676
3628Must always be C<1> if you do not use autoconf configuration, which 3677Must always be C<1> if you do not use autoconf configuration, which
3629keeps libev from including F<config.h>, and it also defines dummy 3678keeps libev from including F<config.h>, and it also defines dummy
3630implementations for some libevent functions (such as logging, which is not 3679implementations for some libevent functions (such as logging, which is not
3631supported). It will also not define any of the structs usually found in 3680supported). It will also not define any of the structs usually found in
3781as well as for signal and thread safety in C<ev_async> watchers. 3830as well as for signal and thread safety in C<ev_async> watchers.
3782 3831
3783In the absence of this define, libev will use C<sig_atomic_t volatile> 3832In the absence of this define, libev will use C<sig_atomic_t volatile>
3784(from F<signal.h>), which is usually good enough on most platforms. 3833(from F<signal.h>), which is usually good enough on most platforms.
3785 3834
3786=item EV_H 3835=item EV_H (h)
3787 3836
3788The name of the F<ev.h> header file used to include it. The default if 3837The name of the F<ev.h> header file used to include it. The default if
3789undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 3838undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
3790used to virtually rename the F<ev.h> header file in case of conflicts. 3839used to virtually rename the F<ev.h> header file in case of conflicts.
3791 3840
3792=item EV_CONFIG_H 3841=item EV_CONFIG_H (h)
3793 3842
3794If C<EV_STANDALONE> isn't C<1>, this variable can be used to override 3843If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
3795F<ev.c>'s idea of where to find the F<config.h> file, similarly to 3844F<ev.c>'s idea of where to find the F<config.h> file, similarly to
3796C<EV_H>, above. 3845C<EV_H>, above.
3797 3846
3798=item EV_EVENT_H 3847=item EV_EVENT_H (h)
3799 3848
3800Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea 3849Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
3801of how the F<event.h> header can be found, the default is C<"event.h">. 3850of how the F<event.h> header can be found, the default is C<"event.h">.
3802 3851
3803=item EV_PROTOTYPES 3852=item EV_PROTOTYPES (h)
3804 3853
3805If defined to be C<0>, then F<ev.h> will not define any function 3854If defined to be C<0>, then F<ev.h> will not define any function
3806prototypes, but still define all the structs and other symbols. This is 3855prototypes, but still define all the structs and other symbols. This is
3807occasionally useful if you want to provide your own wrapper functions 3856occasionally useful if you want to provide your own wrapper functions
3808around libev functions. 3857around libev functions.
3830fine. 3879fine.
3831 3880
3832If your embedding application does not need any priorities, defining these 3881If your embedding application does not need any priorities, defining these
3833both to C<0> will save some memory and CPU. 3882both to C<0> will save some memory and CPU.
3834 3883
3835=item EV_PERIODIC_ENABLE 3884=item EV_PERIODIC_ENABLE, EV_IDLE_ENABLE, EV_EMBED_ENABLE, EV_STAT_ENABLE,
3885EV_PREPARE_ENABLE, EV_CHECK_ENABLE, EV_FORK_ENABLE, EV_SIGNAL_ENABLE,
3886EV_ASYNC_ENABLE, EV_CHILD_ENABLE.
3836 3887
3837If undefined or defined to be C<1>, then periodic timers are supported. If 3888If undefined or defined to be C<1> (and the platform supports it), then
3838defined to be C<0>, then they are not. Disabling them saves a few kB of 3889the respective watcher type is supported. If defined to be C<0>, then it
3839code. 3890is not. Disabling watcher types mainly saves codesize.
3840 3891
3841=item EV_IDLE_ENABLE 3892=item EV_FEATURES
3842
3843If undefined or defined to be C<1>, then idle watchers are supported. If
3844defined to be C<0>, then they are not. Disabling them saves a few kB of
3845code.
3846
3847=item EV_EMBED_ENABLE
3848
3849If undefined or defined to be C<1>, then embed watchers are supported. If
3850defined to be C<0>, then they are not. Embed watchers rely on most other
3851watcher types, which therefore must not be disabled.
3852
3853=item EV_STAT_ENABLE
3854
3855If undefined or defined to be C<1>, then stat watchers are supported. If
3856defined to be C<0>, then they are not.
3857
3858=item EV_FORK_ENABLE
3859
3860If undefined or defined to be C<1>, then fork watchers are supported. If
3861defined to be C<0>, then they are not.
3862
3863=item EV_ASYNC_ENABLE
3864
3865If undefined or defined to be C<1>, then async watchers are supported. If
3866defined to be C<0>, then they are not.
3867
3868=item EV_MINIMAL
3869 3893
3870If you need to shave off some kilobytes of code at the expense of some 3894If you need to shave off some kilobytes of code at the expense of some
3871speed (but with the full API), define this symbol to C<1>. Currently this 3895speed (but with the full API), you can define this symbol to request
3872is used to override some inlining decisions, saves roughly 30% code size 3896certain subsets of functionality. The default is to enable all features
3873on amd64. It also selects a much smaller 2-heap for timer management over 3897that can be enabled on the platform.
3874the default 4-heap.
3875 3898
3876You can save even more by disabling watcher types you do not need 3899A typical way to use this symbol is to define it to C<0> (or to a bitset
3877and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> 3900with some broad features you want) and then selectively re-enable
3878(C<-DNDEBUG>) will usually reduce code size a lot. 3901additional parts you want, for example if you want everything minimal,
3902but multiple event loop support, async and child watchers and the poll
3903backend, use this:
3879 3904
3880Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to 3905 #define EV_FEATURES 0
3881provide a bare-bones event library. See C<ev.h> for details on what parts 3906 #define EV_MULTIPLICITY 1
3882of the API are still available, and do not complain if this subset changes 3907 #define EV_USE_POLL 1
3883over time. 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
3939=item C<8> - full API
3940
3941This enables a lot of the "lesser used" API functions. See C<ev.h> for
3942details on which parts of the API are still available without this
3943feature, and do not complain if this subset changes over time.
3944
3945=item C<16> - enable all optional watcher types
3946
3947Enables all optional watcher types. If you want to selectively enable
3948only some watcher types other than I/O and timers (e.g. prepare,
3949embed, async, child...) you can enable them manually by defining
3950C<EV_watchertype_ENABLE> to C<1> instead.
3951
3952=item C<32> - enable all backends
3953
3954This enables all backends - without this feature, you need to enable at
3955least one backend manually (C<EV_USE_SELECT> is a good choice).
3956
3957=item C<64> - enable OS-specific "helper" APIs
3958
3959Enable inotify, eventfd, signalfd and similar OS-specific helper APIs by
3960default.
3961
3962=back
3963
3964Compiling with C<gcc -Os -DEV_STANDALONE -DEV_USE_EPOLL=1 -DEV_FEATURES=0>
3965reduces the compiled size of libev from 24.7Kb code/2.8Kb data to 6.5Kb
3966code/0.3Kb data on my GNU/Linux amd64 system, while still giving you I/O
3967watchers, timers and monotonic clock support.
3968
3969With an intelligent-enough linker (gcc+binutils are intelligent enough
3970when you use C<-Wl,--gc-sections -ffunction-sections>) functions unused by
3971your program might be left out as well - a binary starting a timer and an
3972I/O watcher then might come out at only 5Kb.
3973
3974=item EV_AVOID_STDIO
3975
3976If this is set to C<1> at compiletime, then libev will avoid using stdio
3977functions (printf, scanf, perror etc.). This will increase the codesize
3978somewhat, but if your program doesn't otherwise depend on stdio and your
3979libc allows it, this avoids linking in the stdio library which is quite
3980big.
3981
3982Note that error messages might become less precise when this option is
3983enabled.
3884 3984
3885=item EV_NSIG 3985=item EV_NSIG
3886 3986
3887The highest supported signal number, +1 (or, the number of 3987The highest supported signal number, +1 (or, the number of
3888signals): Normally, libev tries to deduce the maximum number of signals 3988signals): Normally, libev tries to deduce the maximum number of signals
3892statically allocates some 12-24 bytes per signal number. 3992statically allocates some 12-24 bytes per signal number.
3893 3993
3894=item EV_PID_HASHSIZE 3994=item EV_PID_HASHSIZE
3895 3995
3896C<ev_child> watchers use a small hash table to distribute workload by 3996C<ev_child> watchers use a small hash table to distribute workload by
3897pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 3997pid. The default size is C<16> (or C<1> with C<EV_FEATURES> disabled),
3898than enough. If you need to manage thousands of children you might want to 3998usually more than enough. If you need to manage thousands of children you
3899increase this value (I<must> be a power of two). 3999might want to increase this value (I<must> be a power of two).
3900 4000
3901=item EV_INOTIFY_HASHSIZE 4001=item EV_INOTIFY_HASHSIZE
3902 4002
3903C<ev_stat> watchers use a small hash table to distribute workload by 4003C<ev_stat> watchers use a small hash table to distribute workload by
3904inotify watch id. The default size is C<16> (or C<1> with C<EV_MINIMAL>), 4004inotify watch id. The default size is C<16> (or C<1> with C<EV_FEATURES>
3905usually more than enough. If you need to manage thousands of C<ev_stat> 4005disabled), usually more than enough. If you need to manage thousands of
3906watchers you might want to increase this value (I<must> be a power of 4006C<ev_stat> watchers you might want to increase this value (I<must> be a
3907two). 4007power of two).
3908 4008
3909=item EV_USE_4HEAP 4009=item EV_USE_4HEAP
3910 4010
3911Heaps are not very cache-efficient. To improve the cache-efficiency of the 4011Heaps are not very cache-efficient. To improve the cache-efficiency of the
3912timer and periodics heaps, libev uses a 4-heap when this symbol is defined 4012timer and periodics heaps, libev uses a 4-heap when this symbol is defined
3913to C<1>. The 4-heap uses more complicated (longer) code but has noticeably 4013to C<1>. The 4-heap uses more complicated (longer) code but has noticeably
3914faster performance with many (thousands) of watchers. 4014faster performance with many (thousands) of watchers.
3915 4015
3916The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4016The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3917(disabled). 4017will be C<0>.
3918 4018
3919=item EV_HEAP_CACHE_AT 4019=item EV_HEAP_CACHE_AT
3920 4020
3921Heaps are not very cache-efficient. To improve the cache-efficiency of the 4021Heaps are not very cache-efficient. To improve the cache-efficiency of the
3922timer and periodics heaps, libev can cache the timestamp (I<at>) within 4022timer and periodics heaps, libev can cache the timestamp (I<at>) within
3923the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>), 4023the heap structure (selected by defining C<EV_HEAP_CACHE_AT> to C<1>),
3924which uses 8-12 bytes more per watcher and a few hundred bytes more code, 4024which uses 8-12 bytes more per watcher and a few hundred bytes more code,
3925but avoids random read accesses on heap changes. This improves performance 4025but avoids random read accesses on heap changes. This improves performance
3926noticeably with many (hundreds) of watchers. 4026noticeably with many (hundreds) of watchers.
3927 4027
3928The default is C<1> unless C<EV_MINIMAL> is set in which case it is C<0> 4028The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3929(disabled). 4029will be C<0>.
3930 4030
3931=item EV_VERIFY 4031=item EV_VERIFY
3932 4032
3933Controls how much internal verification (see C<ev_loop_verify ()>) will 4033Controls how much internal verification (see C<ev_loop_verify ()>) will
3934be done: If set to C<0>, no internal verification code will be compiled 4034be done: If set to C<0>, no internal verification code will be compiled
3936called. If set to C<2>, then the internal verification code will be 4036called. If set to C<2>, then the internal verification code will be
3937called once per loop, which can slow down libev. If set to C<3>, then the 4037called once per loop, which can slow down libev. If set to C<3>, then the
3938verification code will be called very frequently, which will slow down 4038verification code will be called very frequently, which will slow down
3939libev considerably. 4039libev considerably.
3940 4040
3941The default is C<1>, unless C<EV_MINIMAL> is set, in which case it will be 4041The default is C<1>, unless C<EV_FEATURES> overrides it, in which case it
3942C<0>. 4042will be C<0>.
3943 4043
3944=item EV_COMMON 4044=item EV_COMMON
3945 4045
3946By default, all watchers have a C<void *data> member. By redefining 4046By default, all watchers have a C<void *data> member. By redefining
3947this macro to a something else you can include more and other types of 4047this macro to a something else you can include more and other types of
4005file. 4105file.
4006 4106
4007The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file 4107The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
4008that everybody includes and which overrides some configure choices: 4108that everybody includes and which overrides some configure choices:
4009 4109
4010 #define EV_MINIMAL 1 4110 #define EV_FEATURES 8
4011 #define EV_USE_POLL 0 4111 #define EV_USE_SELECT 1
4012 #define EV_MULTIPLICITY 0
4013 #define EV_PERIODIC_ENABLE 0 4112 #define EV_PREPARE_ENABLE 1
4113 #define EV_IDLE_ENABLE 1
4014 #define EV_STAT_ENABLE 0 4114 #define EV_SIGNAL_ENABLE 1
4015 #define EV_FORK_ENABLE 0 4115 #define EV_CHILD_ENABLE 1
4116 #define EV_USE_STDEXCEPT 0
4016 #define EV_CONFIG_H <config.h> 4117 #define EV_CONFIG_H <config.h>
4017 #define EV_MINPRI 0
4018 #define EV_MAXPRI 0
4019 4118
4020 #include "ev++.h" 4119 #include "ev++.h"
4021 4120
4022And a F<ev_cpp.C> implementation file that contains libev proper and is compiled: 4121And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
4023 4122
4525involves iterating over all running async watchers or all signal numbers. 4624involves iterating over all running async watchers or all signal numbers.
4526 4625
4527=back 4626=back
4528 4627
4529 4628
4629=head1 PORTING FROM LIBEV 3.X TO 4.X
4630
4631The major version 4 introduced some minor incompatible changes to the API.
4632
4633At the moment, the C<ev.h> header file tries to implement superficial
4634compatibility, so most programs should still compile. Those might be
4635removed in later versions of libev, so better update early than late.
4636
4637=over 4
4638
4639=item C<ev_loop_count> renamed to C<ev_iteration>
4640
4641=item C<ev_loop_depth> renamed to C<ev_depth>
4642
4643=item C<ev_loop_verify> renamed to C<ev_verify>
4644
4645Most functions working on C<struct ev_loop> objects don't have an
4646C<ev_loop_> prefix, so it was removed. Note that C<ev_loop_fork> is
4647still called C<ev_loop_fork> because it would otherwise clash with the
4648C<ev_fork> typedef.
4649
4650=item C<EV_TIMEOUT> renamed to C<EV_TIMER> in C<revents>
4651
4652This is a simple rename - all other watcher types use their name
4653as revents flag, and now C<ev_timer> does, too.
4654
4655Both C<EV_TIMER> and C<EV_TIMEOUT> symbols were present in 3.x versions
4656and continue to be present for the forseeable future, so this is mostly a
4657documentation change.
4658
4659=item C<EV_MINIMAL> mechanism replaced by C<EV_FEATURES>
4660
4661The preprocessor symbol C<EV_MINIMAL> has been replaced by a different
4662mechanism, C<EV_FEATURES>. Programs using C<EV_MINIMAL> usually compile
4663and work, but the library code will of course be larger.
4664
4665=back
4666
4667
4530=head1 GLOSSARY 4668=head1 GLOSSARY
4531 4669
4532=over 4 4670=over 4
4533 4671
4534=item active 4672=item active
4555A change of state of some external event, such as data now being available 4693A change of state of some external event, such as data now being available
4556for reading on a file descriptor, time having passed or simply not having 4694for reading on a file descriptor, time having passed or simply not having
4557any other events happening anymore. 4695any other events happening anymore.
4558 4696
4559In libev, events are represented as single bits (such as C<EV_READ> or 4697In libev, events are represented as single bits (such as C<EV_READ> or
4560C<EV_TIMEOUT>). 4698C<EV_TIMER>).
4561 4699
4562=item event library 4700=item event library
4563 4701
4564A software package implementing an event model and loop. 4702A software package implementing an event model and loop.
4565 4703

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines