… | |
… | |
441 | when you want to receive them. |
441 | when you want to receive them. |
442 | |
442 | |
443 | This behaviour is useful when you want to do your own signal handling, or |
443 | This behaviour is useful when you want to do your own signal handling, or |
444 | want to handle signals only in specific threads and want to avoid libev |
444 | want to handle signals only in specific threads and want to avoid libev |
445 | unblocking the signals. |
445 | unblocking the signals. |
|
|
446 | |
|
|
447 | It's also required by POSIX in a threaded program, as libev calls |
|
|
448 | C<sigprocmask>, whose behaviour is officially unspecified. |
446 | |
449 | |
447 | This flag's behaviour will become the default in future versions of libev. |
450 | This flag's behaviour will become the default in future versions of libev. |
448 | |
451 | |
449 | =item C<EVBACKEND_SELECT> (value 1, portable select backend) |
452 | =item C<EVBACKEND_SELECT> (value 1, portable select backend) |
450 | |
453 | |
… | |
… | |
1375 | |
1378 | |
1376 | Before a watcher can be registered with the event looop it has to be |
1379 | Before a watcher can be registered with the event looop it has to be |
1377 | initialised. This can be done with a call to C<ev_TYPE_init>, or calls to |
1380 | initialised. This can be done with a call to C<ev_TYPE_init>, or calls to |
1378 | C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function. |
1381 | C<ev_init> followed by the watcher-specific C<ev_TYPE_set> function. |
1379 | |
1382 | |
1380 | In this state it is simply some block of memory that is suitable for use |
1383 | In this state it is simply some block of memory that is suitable for |
1381 | in an event loop. It can be moved around, freed, reused etc. at will. |
1384 | use in an event loop. It can be moved around, freed, reused etc. at |
|
|
1385 | will - as long as you either keep the memory contents intact, or call |
|
|
1386 | C<ev_TYPE_init> again. |
1382 | |
1387 | |
1383 | =item started/running/active |
1388 | =item started/running/active |
1384 | |
1389 | |
1385 | Once a watcher has been started with a call to C<ev_TYPE_start> it becomes |
1390 | Once a watcher has been started with a call to C<ev_TYPE_start> it becomes |
1386 | property of the event loop, and is actively waiting for events. While in |
1391 | property of the event loop, and is actively waiting for events. While in |
… | |
… | |
1414 | latter will clear any pending state the watcher might be in, regardless |
1419 | latter will clear any pending state the watcher might be in, regardless |
1415 | of whether it was active or not, so stopping a watcher explicitly before |
1420 | of whether it was active or not, so stopping a watcher explicitly before |
1416 | freeing it is often a good idea. |
1421 | freeing it is often a good idea. |
1417 | |
1422 | |
1418 | While stopped (and not pending) the watcher is essentially in the |
1423 | While stopped (and not pending) the watcher is essentially in the |
1419 | initialised state, that is it can be reused, moved, modified in any way |
1424 | initialised state, that is, it can be reused, moved, modified in any way |
1420 | you wish. |
1425 | you wish (but when you trash the memory block, you need to C<ev_TYPE_init> |
|
|
1426 | it again). |
1421 | |
1427 | |
1422 | =back |
1428 | =back |
1423 | |
1429 | |
1424 | =head2 WATCHER PRIORITY MODELS |
1430 | =head2 WATCHER PRIORITY MODELS |
1425 | |
1431 | |
… | |
… | |
1618 | always get a readiness notification instantly, and your read (or possibly |
1624 | always get a readiness notification instantly, and your read (or possibly |
1619 | write) will still block on the disk I/O. |
1625 | write) will still block on the disk I/O. |
1620 | |
1626 | |
1621 | Another way to view it is that in the case of sockets, pipes, character |
1627 | Another way to view it is that in the case of sockets, pipes, character |
1622 | devices and so on, there is another party (the sender) that delivers data |
1628 | devices and so on, there is another party (the sender) that delivers data |
1623 | on it's own, but in the case of files, there is no such thing: the disk |
1629 | on its own, but in the case of files, there is no such thing: the disk |
1624 | will not send data on it's own, simply because it doesn't know what you |
1630 | will not send data on its own, simply because it doesn't know what you |
1625 | wish to read - you would first have to request some data. |
1631 | wish to read - you would first have to request some data. |
1626 | |
1632 | |
1627 | Since files are typically not-so-well supported by advanced notification |
1633 | Since files are typically not-so-well supported by advanced notification |
1628 | mechanism, libev tries hard to emulate POSIX behaviour with respect |
1634 | mechanism, libev tries hard to emulate POSIX behaviour with respect |
1629 | to files, even though you should not use it. The reason for this is |
1635 | to files, even though you should not use it. The reason for this is |
… | |
… | |
2300 | =head3 The special problem of inheritance over fork/execve/pthread_create |
2306 | =head3 The special problem of inheritance over fork/execve/pthread_create |
2301 | |
2307 | |
2302 | Both the signal mask (C<sigprocmask>) and the signal disposition |
2308 | Both the signal mask (C<sigprocmask>) and the signal disposition |
2303 | (C<sigaction>) are unspecified after starting a signal watcher (and after |
2309 | (C<sigaction>) are unspecified after starting a signal watcher (and after |
2304 | stopping it again), that is, libev might or might not block the signal, |
2310 | stopping it again), that is, libev might or might not block the signal, |
2305 | and might or might not set or restore the installed signal handler. |
2311 | and might or might not set or restore the installed signal handler (but |
|
|
2312 | see C<EVFLAG_NOSIGMASK>). |
2306 | |
2313 | |
2307 | While this does not matter for the signal disposition (libev never |
2314 | While this does not matter for the signal disposition (libev never |
2308 | sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on |
2315 | sets signals to C<SIG_IGN>, so handlers will be reset to C<SIG_DFL> on |
2309 | C<execve>), this matters for the signal mask: many programs do not expect |
2316 | C<execve>), this matters for the signal mask: many programs do not expect |
2310 | certain signals to be blocked. |
2317 | certain signals to be blocked. |
… | |
… | |
3504 | exit_main_loop = exit_nested_loop = 1; |
3511 | exit_main_loop = exit_nested_loop = 1; |
3505 | |
3512 | |
3506 | =head2 THREAD LOCKING EXAMPLE |
3513 | =head2 THREAD LOCKING EXAMPLE |
3507 | |
3514 | |
3508 | Here is a fictitious example of how to run an event loop in a different |
3515 | Here is a fictitious example of how to run an event loop in a different |
3509 | thread than where callbacks are being invoked and watchers are |
3516 | thread from where callbacks are being invoked and watchers are |
3510 | created/added/removed. |
3517 | created/added/removed. |
3511 | |
3518 | |
3512 | For a real-world example, see the C<EV::Loop::Async> perl module, |
3519 | For a real-world example, see the C<EV::Loop::Async> perl module, |
3513 | which uses exactly this technique (which is suited for many high-level |
3520 | which uses exactly this technique (which is suited for many high-level |
3514 | languages). |
3521 | languages). |