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

Comparing libev/ev.pod (file contents):
Revision 1.283 by root, Wed Mar 10 09:18:25 2010 UTC vs.
Revision 1.290 by root, Tue Mar 16 18:03:01 2010 UTC

567 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE); 567 ev_default_loop (ev_recommended_backends () | EVBACKEND_KQUEUE);
568 568
569=item struct ev_loop *ev_loop_new (unsigned int flags) 569=item struct ev_loop *ev_loop_new (unsigned int flags)
570 570
571Similar 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
572always distinct from the default loop. Unlike the default loop, it cannot 572always distinct from the default loop.
573handle signal and child watchers, and attempts to do so will be greeted by
574undefined behaviour (or a failed assertion if assertions are enabled).
575 573
576Note 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
577libev 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
578default loop in the "main" or "initial" thread. 576default loop in the "main" or "initial" thread.
579 577
580Example: 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.
581 579
583 if (!epoller) 581 if (!epoller)
584 fatal ("no epoll found here, maybe it hides under your chair"); 582 fatal ("no epoll found here, maybe it hides under your chair");
585 583
586=item ev_default_destroy () 584=item ev_default_destroy ()
587 585
588Destroys the default loop again (frees all memory and kernel state 586Destroys the default loop (frees all memory and kernel state etc.). None
589etc.). 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
590sense, 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
591responsibility to either stop all watchers cleanly yourself I<before> 589either stop all watchers cleanly yourself I<before> calling this function,
592calling this function, or cope with the fact afterwards (which is usually 590or cope with the fact afterwards (which is usually the easiest thing, you
593the 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).
594for example).
595 592
596Note that certain global state, such as signal state (and installed signal 593Note that certain global state, such as signal state (and installed signal
597handlers), will not be freed by this function, and related watchers (such 594handlers), will not be freed by this function, and related watchers (such
598as signal and child watchers) would need to be stopped manually. 595as signal and child watchers) would need to be stopped manually.
599 596
1032=item C<EV_WRITE> 1029=item C<EV_WRITE>
1033 1030
1034The 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
1035writable. 1032writable.
1036 1033
1037=item C<EV_TIMEOUT> 1034=item C<EV_TIMER>
1038 1035
1039The C<ev_timer> watcher has timed out. 1036The C<ev_timer> watcher has timed out.
1040 1037
1041=item C<EV_PERIODIC> 1038=item C<EV_PERIODIC>
1042 1039
1538 1535
1539So when you encounter spurious, unexplained daemon exits, make sure you 1536So when you encounter spurious, unexplained daemon exits, make sure you
1540ignore 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
1541somewhere, as that would have given you a big clue). 1538somewhere, as that would have given you a big clue).
1542 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.
1543 1578
1544=head3 Watcher-Specific Functions 1579=head3 Watcher-Specific Functions
1545 1580
1546=over 4 1581=over 4
1547 1582
1726to 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
1727callback, which will "do the right thing" and start the timer: 1762callback, which will "do the right thing" and start the timer:
1728 1763
1729 ev_init (timer, callback); 1764 ev_init (timer, callback);
1730 last_activity = ev_now (loop); 1765 last_activity = ev_now (loop);
1731 callback (loop, timer, EV_TIMEOUT); 1766 callback (loop, timer, EV_TIMER);
1732 1767
1733And when there is some activity, simply store the current time in 1768And when there is some activity, simply store the current time in
1734C<last_activity>, no libev calls at all: 1769C<last_activity>, no libev calls at all:
1735 1770
1736 last_actiivty = ev_now (loop); 1771 last_actiivty = ev_now (loop);
3141 3176
3142If 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
3143started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and 3178started. Otherwise an C<ev_timer> watcher with after = C<timeout> (and
3144repeat = 0) will be started. C<0> is a valid timeout. 3179repeat = 0) will be started. C<0> is a valid timeout.
3145 3180
3146The 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
3147passed an C<revents> set like normal event callbacks (a combination of 3182passed an C<revents> set like normal event callbacks (a combination of
3148C<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>
3149value 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>
3150a 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
3151events precedence. 3186events precedence.
3152 3187
3153Example: 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.
3154 3189
3155 static void stdin_ready (int revents, void *arg) 3190 static void stdin_ready (int revents, void *arg)
3156 { 3191 {
3157 if (revents & EV_READ) 3192 if (revents & EV_READ)
3158 /* stdin might have data for us, joy! */; 3193 /* stdin might have data for us, joy! */;
3159 else if (revents & EV_TIMEOUT) 3194 else if (revents & EV_TIMER)
3160 /* doh, nothing entered */; 3195 /* doh, nothing entered */;
3161 } 3196 }
3162 3197
3163 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); 3198 ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3164 3199
3846 3881
3847If undefined or defined to be C<1> (and the platform supports it), then 3882If undefined or defined to be C<1> (and the platform supports it), then
3848the respective watcher type is supported. If defined to be C<0>, then it 3883the respective watcher type is supported. If defined to be C<0>, then it
3849is not. Disabling watcher types mainly saves codesize. 3884is not. Disabling watcher types mainly saves codesize.
3850 3885
3851=item EV_MINIMAL 3886=item EV_FEATURES
3852 3887
3853If 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
3854speed (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
3855is used to override some inlining decisions, saves roughly 30% code size 3890certain subsets of functionality. The default is to enable all features
3856on amd64. It also selects a much smaller 2-heap for timer management over 3891that can be enabled on the platform.
3857the default 4-heap.
3858 3892
3859You 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
3860and setting C<EV_MAXPRI> == C<EV_MINPRI>. Also, disabling C<assert> 3894with some broad features you want) and then selectively re-enable
3861(C<-DNDEBUG>) will usually reduce code size a lot. Disabling inotify, 3895additional parts you want, for example if you want everything minimal,
3862eventfd and signalfd will further help, and disabling backends one doesn't 3896but multiple event loop support, async and child watchers and the poll
3863need (e.g. poll, epoll, kqueue, ports) will help further. 3897backend, use this:
3864 3898
3865Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to 3899 #define EV_FEATURES 0
3866provide a bare-bones event library. See C<ev.h> for details on what parts
3867of the API are still available, and do not complain if this subset changes
3868over time.
3869
3870This example set of settings reduces the compiled size of libev from
387123.9Kb to 7.7Kb on my GNU/Linux amd64 system (and leaves little
3872in - there is also an effect on the amount of memory used). With
3873an intelligent-enough linker (gcc+binutils do this when you use
3874C<-Wl,--gc-sections -ffunction-sections>) further unused functions might
3875be left out as well automatically - a binary starting a timer and an I/O
3876watcher then might come out at only 5Kb.
3877
3878 // tuning and API changes
3879 #define EV_MINIMAL 2
3880 #define EV_MULTIPLICITY 0 3900 #define EV_MULTIPLICITY 1
3881 #define EV_MINPRI 0
3882 #define EV_MAXPRI 0
3883
3884 // OS-specific backends
3885 #define EV_USE_INOTIFY 0
3886 #define EV_USE_EVENTFD 0
3887 #define EV_USE_SIGNALFD 0
3888 #define EV_USE_REALTIME 0
3889 #define EV_USE_MONOTONIC 0
3890 #define EV_USE_CLOCK_SYSCALL 0
3891
3892 // disable all backends except select
3893 #define EV_USE_POLL 0 3901 #define EV_USE_POLL 1
3894 #define EV_USE_PORT 0
3895 #define EV_USE_KQUEUE 0
3896 #define EV_USE_EPOLL 0
3897
3898 // disable all watcher types that cna be disabled
3899 #define EV_STAT_ENABLE 0
3900 #define EV_PERIODIC_ENABLE 0
3901 #define EV_IDLE_ENABLE 0
3902 #define EV_CHECK_ENABLE 0
3903 #define EV_PREPARE_ENABLE 0
3904 #define EV_FORK_ENABLE 0
3905 #define EV_SIGNAL_ENABLE 0
3906 #define EV_CHILD_ENABLE 0 3902 #define EV_CHILD_ENABLE 1
3907 #define EV_ASYNC_ENABLE 0 3903 #define EV_ASYNC_ENABLE 1
3908 #define EV_EMBED_ENABLE 0 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.
3909 3967
3910=item EV_AVOID_STDIO 3968=item EV_AVOID_STDIO
3911 3969
3912If this is set to C<1> at compiletime, then libev will avoid using stdio 3970If this is set to C<1> at compiletime, then libev will avoid using stdio
3913functions (printf, scanf, perror etc.). This will increase the codesize 3971functions (printf, scanf, perror etc.). This will increase the codesize
3928statically allocates some 12-24 bytes per signal number. 3986statically allocates some 12-24 bytes per signal number.
3929 3987
3930=item EV_PID_HASHSIZE 3988=item EV_PID_HASHSIZE
3931 3989
3932C<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
3933pid. 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),
3934than 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
3935increase this value (I<must> be a power of two). 3993might want to increase this value (I<must> be a power of two).
3936 3994
3937=item EV_INOTIFY_HASHSIZE 3995=item EV_INOTIFY_HASHSIZE
3938 3996
3939C<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
3940inotify 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>
3941usually 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
3942watchers 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
3943two). 4001power of two).
3944 4002
3945=item EV_USE_4HEAP 4003=item EV_USE_4HEAP
3946 4004
3947Heaps 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
3948timer 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
3949to 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
3950faster performance with many (thousands) of watchers. 4008faster performance with many (thousands) of watchers.
3951 4009
3952The 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
3953(disabled). 4011will be C<0>.
3954 4012
3955=item EV_HEAP_CACHE_AT 4013=item EV_HEAP_CACHE_AT
3956 4014
3957Heaps 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
3958timer and periodics heaps, libev can cache the timestamp (I<at>) within 4016timer and periodics heaps, libev can cache the timestamp (I<at>) within
3959the 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>),
3960which 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,
3961but avoids random read accesses on heap changes. This improves performance 4019but avoids random read accesses on heap changes. This improves performance
3962noticeably with many (hundreds) of watchers. 4020noticeably with many (hundreds) of watchers.
3963 4021
3964The 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
3965(disabled). 4023will be C<0>.
3966 4024
3967=item EV_VERIFY 4025=item EV_VERIFY
3968 4026
3969Controls how much internal verification (see C<ev_loop_verify ()>) will 4027Controls how much internal verification (see C<ev_loop_verify ()>) will
3970be 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
3972called. 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
3973called 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
3974verification code will be called very frequently, which will slow down 4032verification code will be called very frequently, which will slow down
3975libev considerably. 4033libev considerably.
3976 4034
3977The 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
3978C<0>. 4036will be C<0>.
3979 4037
3980=item EV_COMMON 4038=item EV_COMMON
3981 4039
3982By default, all watchers have a C<void *data> member. By redefining 4040By default, all watchers have a C<void *data> member. By redefining
3983this 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
4041file. 4099file.
4042 4100
4043The 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
4044that everybody includes and which overrides some configure choices: 4102that everybody includes and which overrides some configure choices:
4045 4103
4046 #define EV_MINIMAL 1 4104 #define EV_FEATURES 8
4047 #define EV_USE_POLL 0 4105 #define EV_USE_SELECT 1
4048 #define EV_MULTIPLICITY 0
4049 #define EV_PERIODIC_ENABLE 0 4106 #define EV_PREPARE_ENABLE 1
4107 #define EV_IDLE_ENABLE 1
4050 #define EV_STAT_ENABLE 0 4108 #define EV_SIGNAL_ENABLE 1
4051 #define EV_FORK_ENABLE 0 4109 #define EV_CHILD_ENABLE 1
4110 #define EV_USE_STDEXCEPT 0
4052 #define EV_CONFIG_H <config.h> 4111 #define EV_CONFIG_H <config.h>
4053 #define EV_MINPRI 0
4054 #define EV_MAXPRI 0
4055 4112
4056 #include "ev++.h" 4113 #include "ev++.h"
4057 4114
4058And 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:
4059 4116
4561involves iterating over all running async watchers or all signal numbers. 4618involves iterating over all running async watchers or all signal numbers.
4562 4619
4563=back 4620=back
4564 4621
4565 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
4566=head1 GLOSSARY 4647=head1 GLOSSARY
4567 4648
4568=over 4 4649=over 4
4569 4650
4570=item active 4651=item active
4591A 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
4592for 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
4593any other events happening anymore. 4674any other events happening anymore.
4594 4675
4595In 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
4596C<EV_TIMEOUT>). 4677C<EV_TIMER>).
4597 4678
4598=item event library 4679=item event library
4599 4680
4600A software package implementing an event model and loop. 4681A software package implementing an event model and loop.
4601 4682

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines