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

Comparing libev/ev.pod (file contents):
Revision 1.348 by sf-exg, Sat Jan 8 17:52:39 2011 UTC vs.
Revision 1.349 by root, Mon Jan 10 01:58:55 2011 UTC

… …
299 } 299 }
300 300
301 ... 301 ...
302 ev_set_syserr_cb (fatal_error); 302 ev_set_syserr_cb (fatal_error);
303 303
304=item ev_feed_signal (int signum)
305
306This function can be used to "simulate" a signal receive. It is completely
307safe to call this function at any time, from any context, including signal
308handlers or random threads.
309
310It's main use is to customise signal handling in your process, especially
311in the presence of threads. For example, you could block signals
312by default in all threads (and specifying C<EVFLAG_NOSIGMASK> when
313creating any loops), and in one thread, use C<sigwait> or any other
314mechanism to wait for signals, then "deliver" them to libev by calling
315C<ev_feed_signal>.
316
304=back 317=back
305 318
306=head1 FUNCTIONS CONTROLLING EVENT LOOPS 319=head1 FUNCTIONS CONTROLLING EVENT LOOPS
307 320
308An event loop is described by a C<struct ev_loop *> (the C<struct> is 321An event loop is described by a C<struct ev_loop *> (the C<struct> is
… …
418threads that are not interested in handling them. 431threads that are not interested in handling them.
419 432
420Signalfd will not be used by default as this changes your signal mask, and 433Signalfd will not be used by default as this changes your signal mask, and
421there are a lot of shoddy libraries and programs (glib's threadpool for 434there are a lot of shoddy libraries and programs (glib's threadpool for
422example) that can't properly initialise their signal masks. 435example) that can't properly initialise their signal masks.
436
437=item C<EVFLAG_NOSIGMASK>
438
439When this flag is specified, then libev will avoid to modify the signal
440mask. Specifically, this means you ahve to make sure signals are unblocked
441when you want to receive them.
442
443This behaviour is useful when you want to do your own signal handling, or
444want to handle signals only in specific threads and want to avoid libev
445unblocking the signals.
446
447This flag's behaviour will become the default in future versions of libev.
423 448
424=item C<EVBACKEND_SELECT> (value 1, portable select backend) 449=item C<EVBACKEND_SELECT> (value 1, portable select backend)
425 450
426This is your standard select(2) backend. Not I<completely> standard, as 451This is your standard select(2) backend. Not I<completely> standard, as
427libev tries to roll its own fd_set with no limits on the number of fds, 452libev tries to roll its own fd_set with no limits on the number of fds,
… …
580 605
581Try all backends (even potentially broken ones that wouldn't be tried 606Try all backends (even potentially broken ones that wouldn't be tried
582with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as 607with C<EVFLAG_AUTO>). Since this is a mask, you can do stuff such as
583C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>. 608C<EVBACKEND_ALL & ~EVBACKEND_KQUEUE>.
584 609
585It is definitely not recommended to use this flag. 610It is definitely not recommended to use this flag, use whatever
611C<ev_recommended_backends ()> returns, or simply do not specify a backend
612at all.
613
614=item C<EVBACKEND_MASK>
615
616Not a backend at all, but a mask to select all backend bits from a
617C<flags> value, in case you want to mask out any backends from a flags
618value (e.g. when modifying the C<LIBEV_FLAGS> environment variable).
586 619
587=back 620=back
588 621
589If one or more of the backend flags are or'ed into the flags value, 622If one or more of the backend flags are or'ed into the flags value,
590then only these backends will be tried (in the reverse order as listed 623then only these backends will be tried (in the reverse order as listed
… …
2320 2353
2321So I can't stress this enough: I<If you do not reset your signal mask when 2354So I can't stress this enough: I<If you do not reset your signal mask when
2322you expect it to be empty, you have a race condition in your code>. This 2355you expect it to be empty, you have a race condition in your code>. This
2323is not a libev-specific thing, this is true for most event libraries. 2356is not a libev-specific thing, this is true for most event libraries.
2324 2357
2358=head3 The special problem of threads signal handling
2359
2360POSIX threads has problematic signal handling semantics, specifically,
2361a lot of functionality (sigfd, sigwait etc.) only really works if all
2362threads in a process block signals, which is hard to achieve.
2363
2364When you want to use sigwait (or mix libev signal handling with your own
2365for the same signals), you can tackle this problem by globally blocking
2366all signals before creating any threads (or creating them with a fully set
2367sigprocmask) and also specifying the C<EVFLAG_NOSIGMASK> when creating
2368loops. Then designate one thread as "signal receiver thread" which handles
2369these signals. You can pass on any signals that libev might be interested
2370in by calling C<ev_feed_signal>.
2371
2325=head3 Watcher-Specific Functions and Data Members 2372=head3 Watcher-Specific Functions and Data Members
2326 2373
2327=over 4 2374=over 4
2328 2375
2329=item ev_signal_init (ev_signal *, callback, int signum) 2376=item ev_signal_init (ev_signal *, callback, int signum)
… …
3175it by calling C<ev_async_send>, which is thread- and signal safe. 3222it by calling C<ev_async_send>, which is thread- and signal safe.
3176 3223
3177This functionality is very similar to C<ev_signal> watchers, as signals, 3224This functionality is very similar to C<ev_signal> watchers, as signals,
3178too, are asynchronous in nature, and signals, too, will be compressed 3225too, are asynchronous in nature, and signals, too, will be compressed
3179(i.e. the number of callback invocations may be less than the number of 3226(i.e. the number of callback invocations may be less than the number of
3180C<ev_async_sent> calls). 3227C<ev_async_sent> calls). In fact, you could use signal watchers as a kind
3228of "global async watchers" by using a watcher on an otherwise unused
3229signal, and C<ev_feed_signal> to signal this watcher from another thread,
3230even without knowing which loop owns the signal.
3181 3231
3182Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not 3232Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not
3183just the default loop. 3233just the default loop.
3184 3234
3185=head3 Queueing 3235=head3 Queueing
… …
3361Feed an event on the given fd, as if a file descriptor backend detected 3411Feed an event on the given fd, as if a file descriptor backend detected
3362the given events it. 3412the given events it.
3363 3413
3364=item ev_feed_signal_event (loop, int signum) 3414=item ev_feed_signal_event (loop, int signum)
3365 3415
3366Feed an event as if the given signal occurred (C<loop> must be the default 3416Feed an event as if the given signal occurred. See also C<ev_feed_signal>,
3367loop!). 3417which is async-safe.
3368 3418
3369=back 3419=back
3370 3420
3371 3421
3372=head1 COMMON OR USEFUL IDIOMS (OR BOTH) 3422=head1 COMMON OR USEFUL IDIOMS (OR BOTH)

Diff Legend

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