1 | .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) |
1 | .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) |
2 | .\" |
2 | .\" |
3 | .\" Standard preamble: |
3 | .\" Standard preamble: |
4 | .\" ======================================================================== |
4 | .\" ======================================================================== |
5 | .de Sp \" Vertical space (when we can't use .PP) |
5 | .de Sp \" Vertical space (when we can't use .PP) |
6 | .if t .sp .5v |
6 | .if t .sp .5v |
… | |
… | |
131 | .\} |
131 | .\} |
132 | .rm #[ #] #H #V #F C |
132 | .rm #[ #] #H #V #F C |
133 | .\" ======================================================================== |
133 | .\" ======================================================================== |
134 | .\" |
134 | .\" |
135 | .IX Title "LIBEV 3" |
135 | .IX Title "LIBEV 3" |
136 | .TH LIBEV 3 "2014-09-05" "libev-4.15" "libev - high performance full featured event loop" |
136 | .TH LIBEV 3 "2017-11-14" "libev-4.24" "libev - high performance full featured event loop" |
137 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
137 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
138 | .\" way too many mistakes in technical documents. |
138 | .\" way too many mistakes in technical documents. |
139 | .if n .ad l |
139 | .if n .ad l |
140 | .nh |
140 | .nh |
141 | .SH "NAME" |
141 | .SH "NAME" |
… | |
… | |
536 | make libev check for a fork in each iteration by enabling this flag. |
536 | make libev check for a fork in each iteration by enabling this flag. |
537 | .Sp |
537 | .Sp |
538 | This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop, |
538 | This works by calling \f(CW\*(C`getpid ()\*(C'\fR on every iteration of the loop, |
539 | and thus this might slow down your event loop if you do a lot of loop |
539 | and thus this might slow down your event loop if you do a lot of loop |
540 | iterations and little real work, but is usually not noticeable (on my |
540 | iterations and little real work, but is usually not noticeable (on my |
541 | GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn sequence |
541 | GNU/Linux system for example, \f(CW\*(C`getpid\*(C'\fR is actually a simple 5\-insn |
542 | without a system call and thus \fIvery\fR fast, but my GNU/Linux system also has |
542 | sequence without a system call and thus \fIvery\fR fast, but my GNU/Linux |
543 | \&\f(CW\*(C`pthread_atfork\*(C'\fR which is even faster). |
543 | system also has \f(CW\*(C`pthread_atfork\*(C'\fR which is even faster). (Update: glibc |
|
|
544 | versions 2.25 apparently removed the \f(CW\*(C`getpid\*(C'\fR optimisation again). |
544 | .Sp |
545 | .Sp |
545 | The big advantage of this flag is that you can forget about fork (and |
546 | The big advantage of this flag is that you can forget about fork (and |
546 | forget about forgetting to tell libev about forking) when you use this |
547 | forget about forgetting to tell libev about forking, although you still |
547 | flag. |
548 | have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR) when you use this flag. |
548 | .Sp |
549 | .Sp |
549 | This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR |
550 | This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR |
550 | environment variable. |
551 | environment variable. |
551 | .ie n .IP """EVFLAG_NOINOTIFY""" 4 |
552 | .ie n .IP """EVFLAG_NOINOTIFY""" 4 |
552 | .el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 |
553 | .el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 |
… | |
… | |
816 | to reinitialise the kernel state for backends that have one. Despite |
817 | to reinitialise the kernel state for backends that have one. Despite |
817 | the name, you can call it anytime you are allowed to start or stop |
818 | the name, you can call it anytime you are allowed to start or stop |
818 | watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most |
819 | watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most |
819 | sense after forking, in the child process. You \fImust\fR call it (or use |
820 | sense after forking, in the child process. You \fImust\fR call it (or use |
820 | \&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR. |
821 | \&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR. |
|
|
822 | .Sp |
|
|
823 | In addition, if you want to reuse a loop (via this function or |
|
|
824 | \&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR), you \fIalso\fR have to ignore \f(CW\*(C`SIGPIPE\*(C'\fR. |
821 | .Sp |
825 | .Sp |
822 | Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after |
826 | Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after |
823 | a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is |
827 | a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is |
824 | because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things |
828 | because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things |
825 | during fork. |
829 | during fork. |
… | |
… | |
2343 | Periodic watchers are also timers of a kind, but they are very versatile |
2347 | Periodic watchers are also timers of a kind, but they are very versatile |
2344 | (and unfortunately a bit complex). |
2348 | (and unfortunately a bit complex). |
2345 | .PP |
2349 | .PP |
2346 | Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or |
2350 | Unlike \f(CW\*(C`ev_timer\*(C'\fR, periodic watchers are not based on real time (or |
2347 | relative time, the physical time that passes) but on wall clock time |
2351 | relative time, the physical time that passes) but on wall clock time |
2348 | (absolute time, the thing you can read on your calender or clock). The |
2352 | (absolute time, the thing you can read on your calendar or clock). The |
2349 | difference is that wall clock time can run faster or slower than real |
2353 | difference is that wall clock time can run faster or slower than real |
2350 | time, and time jumps are not uncommon (e.g. when you adjust your |
2354 | time, and time jumps are not uncommon (e.g. when you adjust your |
2351 | wrist-watch). |
2355 | wrist-watch). |
2352 | .PP |
2356 | .PP |
2353 | You can tell a periodic watcher to trigger after some specific point |
2357 | You can tell a periodic watcher to trigger after some specific point |
… | |
… | |
4052 | files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: |
4056 | files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: |
4053 | .PP |
4057 | .PP |
4054 | .Vb 4 |
4058 | .Vb 4 |
4055 | \& // my_ev.h |
4059 | \& // my_ev.h |
4056 | \& #define EV_CB_DECLARE(type) struct my_coro *cb; |
4060 | \& #define EV_CB_DECLARE(type) struct my_coro *cb; |
4057 | \& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb); |
4061 | \& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb) |
4058 | \& #include "../libev/ev.h" |
4062 | \& #include "../libev/ev.h" |
4059 | \& |
4063 | \& |
4060 | \& // my_ev.c |
4064 | \& // my_ev.c |
4061 | \& #define EV_H "my_ev.h" |
4065 | \& #define EV_H "my_ev.h" |
4062 | \& #include "../libev/ev.c" |
4066 | \& #include "../libev/ev.c" |
… | |
… | |
4518 | \& ev_vars.h |
4522 | \& ev_vars.h |
4519 | \& ev_wrap.h |
4523 | \& ev_wrap.h |
4520 | \& |
4524 | \& |
4521 | \& ev_win32.c required on win32 platforms only |
4525 | \& ev_win32.c required on win32 platforms only |
4522 | \& |
4526 | \& |
4523 | \& ev_select.c only when select backend is enabled (which is enabled by default) |
4527 | \& ev_select.c only when select backend is enabled |
4524 | \& ev_poll.c only when poll backend is enabled (disabled by default) |
4528 | \& ev_poll.c only when poll backend is enabled |
4525 | \& ev_epoll.c only when the epoll backend is enabled (disabled by default) |
4529 | \& ev_epoll.c only when the epoll backend is enabled |
4526 | \& ev_kqueue.c only when the kqueue backend is enabled (disabled by default) |
4530 | \& ev_kqueue.c only when the kqueue backend is enabled |
4527 | \& ev_port.c only when the solaris port backend is enabled (disabled by default) |
4531 | \& ev_port.c only when the solaris port backend is enabled |
4528 | .Ve |
4532 | .Ve |
4529 | .PP |
4533 | .PP |
4530 | \&\fIev.c\fR includes the backend files directly when enabled, so you only need |
4534 | \&\fIev.c\fR includes the backend files directly when enabled, so you only need |
4531 | to compile this single file. |
4535 | to compile this single file. |
4532 | .PP |
4536 | .PP |
… | |
… | |
5409 | Libev assumes not only that all watcher pointers have the same internal |
5413 | Libev assumes not only that all watcher pointers have the same internal |
5410 | structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also |
5414 | structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO C\s0 for example), but it also |
5411 | assumes that the same (machine) code can be used to call any watcher |
5415 | assumes that the same (machine) code can be used to call any watcher |
5412 | callback: The watcher callbacks have different type signatures, but libev |
5416 | callback: The watcher callbacks have different type signatures, but libev |
5413 | calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. |
5417 | calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. |
|
|
5418 | .IP "null pointers and integer zero are represented by 0 bytes" 4 |
|
|
5419 | .IX Item "null pointers and integer zero are represented by 0 bytes" |
|
|
5420 | Libev uses \f(CW\*(C`memset\*(C'\fR to initialise structs and arrays to \f(CW0\fR bytes, and |
|
|
5421 | relies on this setting pointers and integers to null. |
5414 | .IP "pointer accesses must be thread-atomic" 4 |
5422 | .IP "pointer accesses must be thread-atomic" 4 |
5415 | .IX Item "pointer accesses must be thread-atomic" |
5423 | .IX Item "pointer accesses must be thread-atomic" |
5416 | Accessing a pointer value must be atomic, it must both be readable and |
5424 | Accessing a pointer value must be atomic, it must both be readable and |
5417 | writable in one piece \- this is the case on all current architectures. |
5425 | writable in one piece \- this is the case on all current architectures. |
5418 | .ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 |
5426 | .ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 |