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

Comparing libev/ev.pod (file contents):
Revision 1.137 by root, Sun Mar 16 16:42:56 2008 UTC vs.
Revision 1.143 by root, Sun Apr 6 14:34:52 2008 UTC

… …
275flags. If that is troubling you, check C<ev_backend ()> afterwards). 275flags. If that is troubling you, check C<ev_backend ()> afterwards).
276 276
277If you don't know what event loop to use, use the one returned from this 277If you don't know what event loop to use, use the one returned from this
278function. 278function.
279 279
280Note that this function is I<not> thread-safe, so if you want to use it
281from multiple threads, you have to lock (note also that this is unlikely,
282as loops cannot bes hared easily between threads anyway).
283
280The default loop is the only loop that can handle C<ev_signal> and 284The default loop is the only loop that can handle C<ev_signal> and
281C<ev_child> watchers, and to do this, it always registers a handler 285C<ev_child> watchers, and to do this, it always registers a handler
282for C<SIGCHLD>. If this is a problem for your app you can either 286for C<SIGCHLD>. If this is a problem for your app you can either
283create a dynamic loop with C<ev_loop_new> that doesn't do that, or you 287create a dynamic loop with C<ev_loop_new> that doesn't do that, or you
284can simply overwrite the C<SIGCHLD> signal handler I<after> calling 288can simply overwrite the C<SIGCHLD> signal handler I<after> calling
… …
354For few fds, this backend is a bit little slower than poll and select, 358For few fds, this backend is a bit little slower than poll and select,
355but it scales phenomenally better. While poll and select usually scale 359but it scales phenomenally better. While poll and select usually scale
356like O(total_fds) where n is the total number of fds (or the highest fd), 360like O(total_fds) where n is the total number of fds (or the highest fd),
357epoll scales either O(1) or O(active_fds). The epoll design has a number 361epoll scales either O(1) or O(active_fds). The epoll design has a number
358of shortcomings, such as silently dropping events in some hard-to-detect 362of shortcomings, such as silently dropping events in some hard-to-detect
359cases and rewiring a syscall per fd change, no fork support and bad 363cases and requiring a syscall per fd change, no fork support and bad
360support for dup. 364support for dup.
361 365
362While stopping, setting and starting an I/O watcher in the same iteration 366While stopping, setting and starting an I/O watcher in the same iteration
363will result in some caching, there is still a syscall per such incident 367will result in some caching, there is still a syscall per such incident
364(because the fd could point to a different file description now), so its 368(because the fd could point to a different file description now), so its
… …
465 469
466Similar to C<ev_default_loop>, but always creates a new event loop that is 470Similar to C<ev_default_loop>, but always creates a new event loop that is
467always distinct from the default loop. Unlike the default loop, it cannot 471always distinct from the default loop. Unlike the default loop, it cannot
468handle signal and child watchers, and attempts to do so will be greeted by 472handle signal and child watchers, and attempts to do so will be greeted by
469undefined behaviour (or a failed assertion if assertions are enabled). 473undefined behaviour (or a failed assertion if assertions are enabled).
474
475Note that this function I<is> thread-safe, and the recommended way to use
476libev with threads is indeed to create one loop per thread, and using the
477default loop in the "main" or "initial" thread.
470 478
471Example: Try to create a event loop that uses epoll and nothing else. 479Example: Try to create a event loop that uses epoll and nothing else.
472 480
473 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV); 481 struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL | EVFLAG_NOENV);
474 if (!epoller) 482 if (!epoller)
… …
1085To support fork in your programs, you either have to call 1093To support fork in your programs, you either have to call
1086C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child, 1094C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child,
1087enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or 1095enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or
1088C<EVBACKEND_POLL>. 1096C<EVBACKEND_POLL>.
1089 1097
1098=head3 The special problem of SIGPIPE
1099
1100While not really specific to libev, it is easy to forget about SIGPIPE:
1101when reading from a pipe whose other end has been closed, your program
1102gets send a SIGPIPE, which, by default, aborts your program. For most
1103programs this is sensible behaviour, for daemons, this is usually
1104undesirable.
1105
1106So when you encounter spurious, unexplained daemon exits, make sure you
1107ignore SIGPIPE (and maybe make sure you log the exit status of your daemon
1108somewhere, as that would have given you a big clue).
1109
1090 1110
1091=head3 Watcher-Specific Functions 1111=head3 Watcher-Specific Functions
1092 1112
1093=over 4 1113=over 4
1094 1114
… …
2268 2288
2269This call incurs the overhead of a syscall only once per loop iteration, 2289This call incurs the overhead of a syscall only once per loop iteration,
2270so while the overhead might be noticable, it doesn't apply to repeated 2290so while the overhead might be noticable, it doesn't apply to repeated
2271calls to C<ev_async_send>. 2291calls to C<ev_async_send>.
2272 2292
2293=item bool = ev_async_pending (ev_async *)
2294
2295Returns a non-zero value when C<ev_async_send> has been called on the
2296watcher but the event has not yet been processed (or even noted) by the
2297event loop.
2298
2299C<ev_async_send> sets a flag in the watcher and wakes up the loop. When
2300the loop iterates next and checks for the watcher to have become active,
2301it will reset the flag again. C<ev_async_pending> can be used to very
2302quickly check wether invoking the loop might be a good idea.
2303
2304Not that this does I<not> check wether the watcher itself is pending, only
2305wether it has been requested to make this watcher pending.
2306
2273=back 2307=back
2274 2308
2275 2309
2276=head1 OTHER FUNCTIONS 2310=head1 OTHER FUNCTIONS
2277 2311
… …
2599=item C<EV_DEFAULT>, C<EV_DEFAULT_> 2633=item C<EV_DEFAULT>, C<EV_DEFAULT_>
2600 2634
2601Similar to the other two macros, this gives you the value of the default 2635Similar to the other two macros, this gives you the value of the default
2602loop, if multiple loops are supported ("ev loop default"). 2636loop, if multiple loops are supported ("ev loop default").
2603 2637
2638=item C<EV_DEFAULT_UC>, C<EV_DEFAULT_UC_>
2639
2640Usage identical to C<EV_DEFAULT> and C<EV_DEFAULT_>, but requires that the
2641default loop has been initialised (C<UC> == unchecked). Their behaviour
2642is undefined when the default loop has not been initialised by a previous
2643execution of C<EV_DEFAULT>, C<EV_DEFAULT_> or C<ev_default_init (...)>.
2644
2645It is often prudent to use C<EV_DEFAULT> when initialising the first
2646watcher in a function but use C<EV_DEFAULT_UC> afterwards.
2647
2604=back 2648=back
2605 2649
2606Example: Declare and initialise a check watcher, utilising the above 2650Example: Declare and initialise a check watcher, utilising the above
2607macros so it will work regardless of whether multiple loops are supported 2651macros so it will work regardless of whether multiple loops are supported
2608or not. 2652or not.
… …
2703 2747
2704 libev.m4 2748 libev.m4
2705 2749
2706=head2 PREPROCESSOR SYMBOLS/MACROS 2750=head2 PREPROCESSOR SYMBOLS/MACROS
2707 2751
2708Libev can be configured via a variety of preprocessor symbols you have to define 2752Libev can be configured via a variety of preprocessor symbols you have to
2709before including any of its files. The default is not to build for multiplicity 2753define before including any of its files. The default in the absense of
2710and only include the select backend. 2754autoconf is noted for every option.
2711 2755
2712=over 4 2756=over 4
2713 2757
2714=item EV_STANDALONE 2758=item EV_STANDALONE
2715 2759
… …
2741=item EV_USE_NANOSLEEP 2785=item EV_USE_NANOSLEEP
2742 2786
2743If defined to be C<1>, libev will assume that C<nanosleep ()> is available 2787If defined to be C<1>, libev will assume that C<nanosleep ()> is available
2744and will use it for delays. Otherwise it will use C<select ()>. 2788and will use it for delays. Otherwise it will use C<select ()>.
2745 2789
2790=item EV_USE_EVENTFD
2791
2792If defined to be C<1>, then libev will assume that C<eventfd ()> is
2793available and will probe for kernel support at runtime. This will improve
2794C<ev_signal> and C<ev_async> performance and reduce resource consumption.
2795If undefined, it will be enabled if the headers indicate GNU/Linux + Glibc
27962.7 or newer, otherwise disabled.
2797
2746=item EV_USE_SELECT 2798=item EV_USE_SELECT
2747 2799
2748If undefined or defined to be C<1>, libev will compile in support for the 2800If undefined or defined to be C<1>, libev will compile in support for the
2749C<select>(2) backend. No attempt at autodetection will be done: if no 2801C<select>(2) backend. No attempt at autodetection will be done: if no
2750other method takes over, select will be it. Otherwise the select backend 2802other method takes over, select will be it. Otherwise the select backend
… …
2786 2838
2787=item EV_USE_EPOLL 2839=item EV_USE_EPOLL
2788 2840
2789If defined to be C<1>, libev will compile in support for the Linux 2841If defined to be C<1>, libev will compile in support for the Linux
2790C<epoll>(7) backend. Its availability will be detected at runtime, 2842C<epoll>(7) backend. Its availability will be detected at runtime,
2791otherwise another method will be used as fallback. This is the 2843otherwise another method will be used as fallback. This is the preferred
2792preferred backend for GNU/Linux systems. 2844backend for GNU/Linux systems. If undefined, it will be enabled if the
2845headers indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
2793 2846
2794=item EV_USE_KQUEUE 2847=item EV_USE_KQUEUE
2795 2848
2796If defined to be C<1>, libev will compile in support for the BSD style 2849If defined to be C<1>, libev will compile in support for the BSD style
2797C<kqueue>(2) backend. Its actual availability will be detected at runtime, 2850C<kqueue>(2) backend. Its actual availability will be detected at runtime,
… …
2816 2869
2817=item EV_USE_INOTIFY 2870=item EV_USE_INOTIFY
2818 2871
2819If defined to be C<1>, libev will compile in support for the Linux inotify 2872If defined to be C<1>, libev will compile in support for the Linux inotify
2820interface to speed up C<ev_stat> watchers. Its actual availability will 2873interface to speed up C<ev_stat> watchers. Its actual availability will
2821be detected at runtime. 2874be detected at runtime. If undefined, it will be enabled if the headers
2875indicate GNU/Linux + Glibc 2.4 or newer, otherwise disabled.
2822 2876
2823=item EV_ATOMIC_T 2877=item EV_ATOMIC_T
2824 2878
2825Libev requires an integer type (suitable for storing C<0> or C<1>) whose 2879Libev requires an integer type (suitable for storing C<0> or C<1>) whose
2826access is atomic with respect to other threads or signal contexts. No such 2880access is atomic with respect to other threads or signal contexts. No such

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines