… | |
… | |
122 | .\} |
122 | .\} |
123 | .rm #[ #] #H #V #F C |
123 | .rm #[ #] #H #V #F C |
124 | .\" ======================================================================== |
124 | .\" ======================================================================== |
125 | .\" |
125 | .\" |
126 | .IX Title "LIBEV 3" |
126 | .IX Title "LIBEV 3" |
127 | .TH LIBEV 3 "2011-01-11" "libev-4.03" "libev - high performance full featured event loop" |
127 | .TH LIBEV 3 "2011-01-31" "libev-4.04" "libev - high performance full featured event loop" |
128 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
128 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
129 | .\" way too many mistakes in technical documents. |
129 | .\" way too many mistakes in technical documents. |
130 | .if n .ad l |
130 | .if n .ad l |
131 | .nh |
131 | .nh |
132 | .SH "NAME" |
132 | .SH "NAME" |
… | |
… | |
189 | \& ev_timer_start (loop, &timeout_watcher); |
189 | \& ev_timer_start (loop, &timeout_watcher); |
190 | \& |
190 | \& |
191 | \& // now wait for events to arrive |
191 | \& // now wait for events to arrive |
192 | \& ev_run (loop, 0); |
192 | \& ev_run (loop, 0); |
193 | \& |
193 | \& |
194 | \& // unloop was called, so exit |
194 | \& // break was called, so exit |
195 | \& return 0; |
195 | \& return 0; |
196 | \& } |
196 | \& } |
197 | .Ve |
197 | .Ve |
198 | .SH "ABOUT THIS DOCUMENT" |
198 | .SH "ABOUT THIS DOCUMENT" |
199 | .IX Header "ABOUT THIS DOCUMENT" |
199 | .IX Header "ABOUT THIS DOCUMENT" |
… | |
… | |
559 | when you want to receive them. |
559 | when you want to receive them. |
560 | .Sp |
560 | .Sp |
561 | This behaviour is useful when you want to do your own signal handling, or |
561 | This behaviour is useful when you want to do your own signal handling, or |
562 | want to handle signals only in specific threads and want to avoid libev |
562 | want to handle signals only in specific threads and want to avoid libev |
563 | unblocking the signals. |
563 | unblocking the signals. |
|
|
564 | .Sp |
|
|
565 | It's also required by \s-1POSIX\s0 in a threaded program, as libev calls |
|
|
566 | \&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified. |
564 | .Sp |
567 | .Sp |
565 | This flag's behaviour will become the default in future versions of libev. |
568 | This flag's behaviour will become the default in future versions of libev. |
566 | .ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 |
569 | .ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 |
567 | .el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 |
570 | .el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 |
568 | .IX Item "EVBACKEND_SELECT (value 1, portable select backend)" |
571 | .IX Item "EVBACKEND_SELECT (value 1, portable select backend)" |
… | |
… | |
985 | .Sp |
988 | .Sp |
986 | .Vb 4 |
989 | .Vb 4 |
987 | \& ... queue jobs here, make sure they register event watchers as long |
990 | \& ... queue jobs here, make sure they register event watchers as long |
988 | \& ... as they still have work to do (even an idle watcher will do..) |
991 | \& ... as they still have work to do (even an idle watcher will do..) |
989 | \& ev_run (my_loop, 0); |
992 | \& ev_run (my_loop, 0); |
990 | \& ... jobs done or somebody called unloop. yeah! |
993 | \& ... jobs done or somebody called break. yeah! |
991 | .Ve |
994 | .Ve |
992 | .IP "ev_break (loop, how)" 4 |
995 | .IP "ev_break (loop, how)" 4 |
993 | .IX Item "ev_break (loop, how)" |
996 | .IX Item "ev_break (loop, how)" |
994 | Can be used to make a call to \f(CW\*(C`ev_run\*(C'\fR return early (but only after it |
997 | Can be used to make a call to \f(CW\*(C`ev_run\*(C'\fR return early (but only after it |
995 | has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either |
998 | has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either |
… | |
… | |
1490 | .IX Item "initialiased" |
1493 | .IX Item "initialiased" |
1491 | Before a watcher can be registered with the event looop it has to be |
1494 | Before a watcher can be registered with the event looop it has to be |
1492 | initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to |
1495 | initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to |
1493 | \&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function. |
1496 | \&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function. |
1494 | .Sp |
1497 | .Sp |
1495 | In this state it is simply some block of memory that is suitable for use |
1498 | In this state it is simply some block of memory that is suitable for |
1496 | in an event loop. It can be moved around, freed, reused etc. at will. |
1499 | use in an event loop. It can be moved around, freed, reused etc. at |
|
|
1500 | will \- as long as you either keep the memory contents intact, or call |
|
|
1501 | \&\f(CW\*(C`ev_TYPE_init\*(C'\fR again. |
1497 | .IP "started/running/active" 4 |
1502 | .IP "started/running/active" 4 |
1498 | .IX Item "started/running/active" |
1503 | .IX Item "started/running/active" |
1499 | Once a watcher has been started with a call to \f(CW\*(C`ev_TYPE_start\*(C'\fR it becomes |
1504 | Once a watcher has been started with a call to \f(CW\*(C`ev_TYPE_start\*(C'\fR it becomes |
1500 | property of the event loop, and is actively waiting for events. While in |
1505 | property of the event loop, and is actively waiting for events. While in |
1501 | this state it cannot be accessed (except in a few documented ways), moved, |
1506 | this state it cannot be accessed (except in a few documented ways), moved, |
… | |
… | |
1526 | latter will clear any pending state the watcher might be in, regardless |
1531 | latter will clear any pending state the watcher might be in, regardless |
1527 | of whether it was active or not, so stopping a watcher explicitly before |
1532 | of whether it was active or not, so stopping a watcher explicitly before |
1528 | freeing it is often a good idea. |
1533 | freeing it is often a good idea. |
1529 | .Sp |
1534 | .Sp |
1530 | While stopped (and not pending) the watcher is essentially in the |
1535 | While stopped (and not pending) the watcher is essentially in the |
1531 | initialised state, that is it can be reused, moved, modified in any way |
1536 | initialised state, that is, it can be reused, moved, modified in any way |
1532 | you wish. |
1537 | you wish (but when you trash the memory block, you need to \f(CW\*(C`ev_TYPE_init\*(C'\fR |
|
|
1538 | it again). |
1533 | .SS "\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0" |
1539 | .SS "\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0" |
1534 | .IX Subsection "WATCHER PRIORITY MODELS" |
1540 | .IX Subsection "WATCHER PRIORITY MODELS" |
1535 | Many event loops support \fIwatcher priorities\fR, which are usually small |
1541 | Many event loops support \fIwatcher priorities\fR, which are usually small |
1536 | integers that influence the ordering of event callback invocation |
1542 | integers that influence the ordering of event callback invocation |
1537 | between watchers in some way, all else being equal. |
1543 | between watchers in some way, all else being equal. |
… | |
… | |
2429 | .IX Subsection "The special problem of inheritance over fork/execve/pthread_create" |
2435 | .IX Subsection "The special problem of inheritance over fork/execve/pthread_create" |
2430 | .PP |
2436 | .PP |
2431 | Both the signal mask (\f(CW\*(C`sigprocmask\*(C'\fR) and the signal disposition |
2437 | Both the signal mask (\f(CW\*(C`sigprocmask\*(C'\fR) and the signal disposition |
2432 | (\f(CW\*(C`sigaction\*(C'\fR) are unspecified after starting a signal watcher (and after |
2438 | (\f(CW\*(C`sigaction\*(C'\fR) are unspecified after starting a signal watcher (and after |
2433 | stopping it again), that is, libev might or might not block the signal, |
2439 | stopping it again), that is, libev might or might not block the signal, |
2434 | and might or might not set or restore the installed signal handler. |
2440 | and might or might not set or restore the installed signal handler (but |
|
|
2441 | see \f(CW\*(C`EVFLAG_NOSIGMASK\*(C'\fR). |
2435 | .PP |
2442 | .PP |
2436 | While this does not matter for the signal disposition (libev never |
2443 | While this does not matter for the signal disposition (libev never |
2437 | sets signals to \f(CW\*(C`SIG_IGN\*(C'\fR, so handlers will be reset to \f(CW\*(C`SIG_DFL\*(C'\fR on |
2444 | sets signals to \f(CW\*(C`SIG_IGN\*(C'\fR, so handlers will be reset to \f(CW\*(C`SIG_DFL\*(C'\fR on |
2438 | \&\f(CW\*(C`execve\*(C'\fR), this matters for the signal mask: many programs do not expect |
2445 | \&\f(CW\*(C`execve\*(C'\fR), this matters for the signal mask: many programs do not expect |
2439 | certain signals to be blocked. |
2446 | certain signals to be blocked. |
… | |
… | |
3307 | \& atexit (program_exits); |
3314 | \& atexit (program_exits); |
3308 | .Ve |
3315 | .Ve |
3309 | .ie n .SS """ev_async"" \- how to wake up an event loop" |
3316 | .ie n .SS """ev_async"" \- how to wake up an event loop" |
3310 | .el .SS "\f(CWev_async\fP \- how to wake up an event loop" |
3317 | .el .SS "\f(CWev_async\fP \- how to wake up an event loop" |
3311 | .IX Subsection "ev_async - how to wake up an event loop" |
3318 | .IX Subsection "ev_async - how to wake up an event loop" |
3312 | In general, you cannot use an \f(CW\*(C`ev_run\*(C'\fR from multiple threads or other |
3319 | In general, you cannot use an \f(CW\*(C`ev_loop\*(C'\fR from multiple threads or other |
3313 | asynchronous sources such as signal handlers (as opposed to multiple event |
3320 | asynchronous sources such as signal handlers (as opposed to multiple event |
3314 | loops \- those are of course safe to use in different threads). |
3321 | loops \- those are of course safe to use in different threads). |
3315 | .PP |
3322 | .PP |
3316 | Sometimes, however, you need to wake up an event loop you do not control, |
3323 | Sometimes, however, you need to wake up an event loop you do not control, |
3317 | for example because it belongs to another thread. This is what \f(CW\*(C`ev_async\*(C'\fR |
3324 | for example because it belongs to another thread. This is what \f(CW\*(C`ev_async\*(C'\fR |
… | |
… | |
3422 | kind. There is a \f(CW\*(C`ev_async_set\*(C'\fR macro, but using it is utterly pointless, |
3429 | kind. There is a \f(CW\*(C`ev_async_set\*(C'\fR macro, but using it is utterly pointless, |
3423 | trust me. |
3430 | trust me. |
3424 | .IP "ev_async_send (loop, ev_async *)" 4 |
3431 | .IP "ev_async_send (loop, ev_async *)" 4 |
3425 | .IX Item "ev_async_send (loop, ev_async *)" |
3432 | .IX Item "ev_async_send (loop, ev_async *)" |
3426 | Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds |
3433 | Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds |
3427 | an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop. Unlike |
3434 | an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop, and instantly |
|
|
3435 | returns. |
|
|
3436 | .Sp |
3428 | \&\f(CW\*(C`ev_feed_event\*(C'\fR, this call is safe to do from other threads, signal or |
3437 | Unlike \f(CW\*(C`ev_feed_event\*(C'\fR, this call is safe to do from other threads, |
3429 | similar contexts (see the discussion of \f(CW\*(C`EV_ATOMIC_T\*(C'\fR in the embedding |
3438 | signal or similar contexts (see the discussion of \f(CW\*(C`EV_ATOMIC_T\*(C'\fR in the |
3430 | section below on what exactly this means). |
3439 | embedding section below on what exactly this means). |
3431 | .Sp |
3440 | .Sp |
3432 | Note that, as with other watchers in libev, multiple events might get |
3441 | Note that, as with other watchers in libev, multiple events might get |
3433 | compressed into a single callback invocation (another way to look at this |
3442 | compressed into a single callback invocation (another way to look at this |
3434 | is that \f(CW\*(C`ev_async\*(C'\fR watchers are level-triggered, set on \f(CW\*(C`ev_async_send\*(C'\fR, |
3443 | is that \f(CW\*(C`ev_async\*(C'\fR watchers are level-triggered, set on \f(CW\*(C`ev_async_send\*(C'\fR, |
3435 | reset when the event loop detects that). |
3444 | reset when the event loop detects that). |
… | |
… | |
3658 | \& // now associate this with the loop |
3667 | \& // now associate this with the loop |
3659 | \& ev_set_userdata (EV_A_ u); |
3668 | \& ev_set_userdata (EV_A_ u); |
3660 | \& ev_set_invoke_pending_cb (EV_A_ l_invoke); |
3669 | \& ev_set_invoke_pending_cb (EV_A_ l_invoke); |
3661 | \& ev_set_loop_release_cb (EV_A_ l_release, l_acquire); |
3670 | \& ev_set_loop_release_cb (EV_A_ l_release, l_acquire); |
3662 | \& |
3671 | \& |
3663 | \& // then create the thread running ev_loop |
3672 | \& // then create the thread running ev_run |
3664 | \& pthread_create (&u\->tid, 0, l_run, EV_A); |
3673 | \& pthread_create (&u\->tid, 0, l_run, EV_A); |
3665 | \& } |
3674 | \& } |
3666 | .Ve |
3675 | .Ve |
3667 | .PP |
3676 | .PP |
3668 | The callback for the \f(CW\*(C`ev_async\*(C'\fR watcher does nothing: the watcher is used |
3677 | The callback for the \f(CW\*(C`ev_async\*(C'\fR watcher does nothing: the watcher is used |
… | |
… | |
5297 | A data structure that describes interest in certain events. Watchers need |
5306 | A data structure that describes interest in certain events. Watchers need |
5298 | to be started (attached to an event loop) before they can receive events. |
5307 | to be started (attached to an event loop) before they can receive events. |
5299 | .SH "AUTHOR" |
5308 | .SH "AUTHOR" |
5300 | .IX Header "AUTHOR" |
5309 | .IX Header "AUTHOR" |
5301 | Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael |
5310 | Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael |
5302 | Magnusson and Emanuele Giaquinta. |
5311 | Magnusson and Emanuele Giaquinta, and minor corrections by many others. |