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

Comparing libev/ev.pod (file contents):
Revision 1.258 by root, Wed Jul 15 16:58:53 2009 UTC vs.
Revision 1.260 by root, Sun Jul 19 21:18:03 2009 UTC

… …
362flag. 362flag.
363 363
364This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS> 364This flag setting cannot be overridden or specified in the C<LIBEV_FLAGS>
365environment variable. 365environment variable.
366 366
367=item C<EVFLAG_NOINOTIFY>
368
369When this flag is specified, then libev will not attempt to use the
370I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
371testing, this flag can be useful to conserve inotify file descriptors, as
372otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
373
374=item C<EVFLAG_NOSIGNALFD>
375
376When this flag is specified, then libev will not attempt to use the
377I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is
378probably only useful to work around any bugs in libev. Consequently, this
379flag might go away once the signalfd functionality is considered stable,
380so it's useful mostly in environment variables and not in program code.
381
367=item C<EVBACKEND_SELECT> (value 1, portable select backend) 382=item C<EVBACKEND_SELECT> (value 1, portable select backend)
368 383
369This is your standard select(2) backend. Not I<completely> standard, as 384This is your standard select(2) backend. Not I<completely> standard, as
370libev tries to roll its own fd_set with no limits on the number of fds, 385libev tries to roll its own fd_set with no limits on the number of fds,
371but if that fails, expect a fairly low limit on the number of fds when 386but if that fails, expect a fairly low limit on the number of fds when
… …
518 533
519It is definitely not recommended to use this flag. 534It is definitely not recommended to use this flag.
520 535
521=back 536=back
522 537
523If one or more of these are or'ed into the flags value, then only these 538If one or more of the backend flags are or'ed into the flags value,
524backends will be tried (in the reverse order as listed here). If none are 539then only these backends will be tried (in the reverse order as listed
525specified, all backends in C<ev_recommended_backends ()> will be tried. 540here). If none are specified, all backends in C<ev_recommended_backends
541()> will be tried.
526 542
527Example: This is the most typical usage. 543Example: This is the most typical usage.
528 544
529 if (!ev_default_loop (0)) 545 if (!ev_default_loop (0))
530 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?"); 546 fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
… …
2076Signal watchers will trigger an event when the process receives a specific 2092Signal watchers will trigger an event when the process receives a specific
2077signal one or more times. Even though signals are very asynchronous, libev 2093signal one or more times. Even though signals are very asynchronous, libev
2078will try it's best to deliver signals synchronously, i.e. as part of the 2094will try it's best to deliver signals synchronously, i.e. as part of the
2079normal event processing, like any other event. 2095normal event processing, like any other event.
2080 2096
2081If you want signals asynchronously, just use C<sigaction> as you would 2097If you want signals to be delivered truly asynchronously, just use
2082do without libev and forget about sharing the signal. You can even use 2098C<sigaction> as you would do without libev and forget about sharing
2083C<ev_async> from a signal handler to synchronously wake up an event loop. 2099the signal. You can even use C<ev_async> from a signal handler to
2100synchronously wake up an event loop.
2084 2101
2085You can configure as many watchers as you like per signal. Only when the 2102You can configure as many watchers as you like for the same signal, but
2103only within the same loop, i.e. you can watch for C<SIGINT> in your
2104default loop and for C<SIGIO> in another loop, but you cannot watch for
2105C<SIGINT> in both the default loop and another loop at the same time. At
2106the moment, C<SIGCHLD> is permanently tied to the default loop.
2107
2086first watcher gets started will libev actually register a signal handler 2108When the first watcher gets started will libev actually register something
2087with the kernel (thus it coexists with your own signal handlers as long as 2109with the kernel (thus it coexists with your own signal handlers as long as
2088you don't register any with libev for the same signal). Similarly, when 2110you don't register any with libev for the same signal).
2089the last signal watcher for a signal is stopped, libev will reset the 2111
2090signal handler to SIG_DFL (regardless of what it was set to before). 2112Both the signal mask state (C<sigprocmask>) and the signal handler state
2113(C<sigaction>) are unspecified after starting a signal watcher (and after
2114sotpping it again), that is, libev might or might not block the signal,
2115and might or might not set or restore the installed signal handler.
2091 2116
2092If possible and supported, libev will install its handlers with 2117If possible and supported, libev will install its handlers with
2093C<SA_RESTART> behaviour enabled, so system calls should not be unduly 2118C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2094interrupted. If you have a problem with system calls getting interrupted by 2119not be unduly interrupted. If you have a problem with system calls getting
2095signals you can block all signals in an C<ev_check> watcher and unblock 2120interrupted by signals you can block all signals in an C<ev_check> watcher
2096them in an C<ev_prepare> watcher. 2121and unblock them in an C<ev_prepare> watcher.
2097 2122
2098=head3 Watcher-Specific Functions and Data Members 2123=head3 Watcher-Specific Functions and Data Members
2099 2124
2100=over 4 2125=over 4
2101 2126
… …
2146libev) 2171libev)
2147 2172
2148=head3 Process Interaction 2173=head3 Process Interaction
2149 2174
2150Libev grabs C<SIGCHLD> as soon as the default event loop is 2175Libev grabs C<SIGCHLD> as soon as the default event loop is
2151initialised. This is necessary to guarantee proper behaviour even if 2176initialised. This is necessary to guarantee proper behaviour even if the
2152the first child watcher is started after the child exits. The occurrence 2177first child watcher is started after the child exits. The occurrence
2153of C<SIGCHLD> is recorded asynchronously, but child reaping is done 2178of C<SIGCHLD> is recorded asynchronously, but child reaping is done
2154synchronously as part of the event loop processing. Libev always reaps all 2179synchronously as part of the event loop processing. Libev always reaps all
2155children, even ones not watched. 2180children, even ones not watched.
2156 2181
2157=head3 Overriding the Built-In Processing 2182=head3 Overriding the Built-In Processing
… …
2167=head3 Stopping the Child Watcher 2192=head3 Stopping the Child Watcher
2168 2193
2169Currently, the child watcher never gets stopped, even when the 2194Currently, the child watcher never gets stopped, even when the
2170child terminates, so normally one needs to stop the watcher in the 2195child terminates, so normally one needs to stop the watcher in the
2171callback. Future versions of libev might stop the watcher automatically 2196callback. Future versions of libev might stop the watcher automatically
2172when a child exit is detected. 2197when a child exit is detected (calling C<ev_child_stop> twice is not a
2198problem).
2173 2199
2174=head3 Watcher-Specific Functions and Data Members 2200=head3 Watcher-Specific Functions and Data Members
2175 2201
2176=over 4 2202=over 4
2177 2203
… …
3792Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to 3818Defining C<EV_MINIMAL> to C<2> will additionally reduce the core API to
3793provide a bare-bones event library. See C<ev.h> for details on what parts 3819provide a bare-bones event library. See C<ev.h> for details on what parts
3794of the API are still available, and do not complain if this subset changes 3820of the API are still available, and do not complain if this subset changes
3795over time. 3821over time.
3796 3822
3823=item EV_NSIG
3824
3825The highest supported signal number, +1 (or, the number of
3826signals): Normally, libev tries to deduce the maximum number of signals
3827automatically, but sometimes this fails, in which case it can be
3828specified. Also, using a lower number than detected (C<32> should be
3829good for about any system in existance) can save some memory, as libev
3830statically allocates some 12-24 bytes per signal number.
3831
3797=item EV_PID_HASHSIZE 3832=item EV_PID_HASHSIZE
3798 3833
3799C<ev_child> watchers use a small hash table to distribute workload by 3834C<ev_child> watchers use a small hash table to distribute workload by
3800pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more 3835pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
3801than enough. If you need to manage thousands of children you might want to 3836than enough. If you need to manage thousands of children you might want to

Diff Legend

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