… | |
… | |
130 | .\} |
130 | .\} |
131 | .rm #[ #] #H #V #F C |
131 | .rm #[ #] #H #V #F C |
132 | .\" ======================================================================== |
132 | .\" ======================================================================== |
133 | .\" |
133 | .\" |
134 | .IX Title "LIBEV 3" |
134 | .IX Title "LIBEV 3" |
135 | .TH LIBEV 3 "2008-09-29" "libev-3.44" "libev - high performance full featured event loop" |
135 | .TH LIBEV 3 "2008-10-21" "libev-3.45" "libev - high performance full featured event loop" |
136 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
136 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
137 | .\" way too many mistakes in technical documents. |
137 | .\" way too many mistakes in technical documents. |
138 | .if n .ad l |
138 | .if n .ad l |
139 | .nh |
139 | .nh |
140 | .SH "NAME" |
140 | .SH "NAME" |
… | |
… | |
813 | has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either |
813 | has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either |
814 | \&\f(CW\*(C`EVUNLOOP_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_loop\*(C'\fR call return, or |
814 | \&\f(CW\*(C`EVUNLOOP_ONE\*(C'\fR, which will make the innermost \f(CW\*(C`ev_loop\*(C'\fR call return, or |
815 | \&\f(CW\*(C`EVUNLOOP_ALL\*(C'\fR, which will make all nested \f(CW\*(C`ev_loop\*(C'\fR calls return. |
815 | \&\f(CW\*(C`EVUNLOOP_ALL\*(C'\fR, which will make all nested \f(CW\*(C`ev_loop\*(C'\fR calls return. |
816 | .Sp |
816 | .Sp |
817 | This \*(L"unloop state\*(R" will be cleared when entering \f(CW\*(C`ev_loop\*(C'\fR again. |
817 | This \*(L"unloop state\*(R" will be cleared when entering \f(CW\*(C`ev_loop\*(C'\fR again. |
|
|
818 | .Sp |
|
|
819 | It is safe to call \f(CW\*(C`ev_unloop\*(C'\fR from otuside any \f(CW\*(C`ev_loop\*(C'\fR calls. |
818 | .IP "ev_ref (loop)" 4 |
820 | .IP "ev_ref (loop)" 4 |
819 | .IX Item "ev_ref (loop)" |
821 | .IX Item "ev_ref (loop)" |
820 | .PD 0 |
822 | .PD 0 |
821 | .IP "ev_unref (loop)" 4 |
823 | .IP "ev_unref (loop)" 4 |
822 | .IX Item "ev_unref (loop)" |
824 | .IX Item "ev_unref (loop)" |
… | |
… | |
1104 | \& ev_io_start (EV_DEFAULT_UC, &w); |
1106 | \& ev_io_start (EV_DEFAULT_UC, &w); |
1105 | .Ve |
1107 | .Ve |
1106 | .ie n .IP """ev_TYPE_stop"" (loop *, ev_TYPE *watcher)" 4 |
1108 | .ie n .IP """ev_TYPE_stop"" (loop *, ev_TYPE *watcher)" 4 |
1107 | .el .IP "\f(CWev_TYPE_stop\fR (loop *, ev_TYPE *watcher)" 4 |
1109 | .el .IP "\f(CWev_TYPE_stop\fR (loop *, ev_TYPE *watcher)" 4 |
1108 | .IX Item "ev_TYPE_stop (loop *, ev_TYPE *watcher)" |
1110 | .IX Item "ev_TYPE_stop (loop *, ev_TYPE *watcher)" |
1109 | Stops the given watcher again (if active) and clears the pending |
1111 | Stops the given watcher if active, and clears the pending status (whether |
|
|
1112 | the watcher was active or not). |
|
|
1113 | .Sp |
1110 | status. It is possible that stopped watchers are pending (for example, |
1114 | It is possible that stopped watchers are pending \- for example, |
1111 | non-repeating timers are being stopped when they become pending), but |
1115 | non-repeating timers are being stopped when they become pending \- but |
1112 | \&\f(CW\*(C`ev_TYPE_stop\*(C'\fR ensures that the watcher is neither active nor pending. If |
1116 | calling \f(CW\*(C`ev_TYPE_stop\*(C'\fR ensures that the watcher is neither active nor |
1113 | you want to free or reuse the memory used by the watcher it is therefore a |
1117 | pending. If you want to free or reuse the memory used by the watcher it is |
1114 | good idea to always call its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function. |
1118 | therefore a good idea to always call its \f(CW\*(C`ev_TYPE_stop\*(C'\fR function. |
1115 | .IP "bool ev_is_active (ev_TYPE *watcher)" 4 |
1119 | .IP "bool ev_is_active (ev_TYPE *watcher)" 4 |
1116 | .IX Item "bool ev_is_active (ev_TYPE *watcher)" |
1120 | .IX Item "bool ev_is_active (ev_TYPE *watcher)" |
1117 | Returns a true value iff the watcher is active (i.e. it has been started |
1121 | Returns a true value iff the watcher is active (i.e. it has been started |
1118 | and not yet been stopped). As long as a watcher is active you must not modify |
1122 | and not yet been stopped). As long as a watcher is active you must not modify |
1119 | it. |
1123 | it. |
… | |
… | |
1765 | The signal the watcher watches out for. |
1769 | The signal the watcher watches out for. |
1766 | .PP |
1770 | .PP |
1767 | \fIExamples\fR |
1771 | \fIExamples\fR |
1768 | .IX Subsection "Examples" |
1772 | .IX Subsection "Examples" |
1769 | .PP |
1773 | .PP |
1770 | Example: Try to exit cleanly on \s-1SIGINT\s0 and \s-1SIGTERM\s0. |
1774 | Example: Try to exit cleanly on \s-1SIGINT\s0. |
1771 | .PP |
1775 | .PP |
1772 | .Vb 5 |
1776 | .Vb 5 |
1773 | \& static void |
1777 | \& static void |
1774 | \& sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) |
1778 | \& sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) |
1775 | \& { |
1779 | \& { |
1776 | \& ev_unloop (loop, EVUNLOOP_ALL); |
1780 | \& ev_unloop (loop, EVUNLOOP_ALL); |
1777 | \& } |
1781 | \& } |
1778 | \& |
1782 | \& |
1779 | \& struct ev_signal signal_watcher; |
1783 | \& struct ev_signal signal_watcher; |
1780 | \& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
1784 | \& ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
1781 | \& ev_signal_start (loop, &sigint_cb); |
1785 | \& ev_signal_start (loop, &signal_watcher); |
1782 | .Ve |
1786 | .Ve |
1783 | .ie n .Sh """ev_child"" \- watch out for process status changes" |
1787 | .ie n .Sh """ev_child"" \- watch out for process status changes" |
1784 | .el .Sh "\f(CWev_child\fP \- watch out for process status changes" |
1788 | .el .Sh "\f(CWev_child\fP \- watch out for process status changes" |
1785 | .IX Subsection "ev_child - watch out for process status changes" |
1789 | .IX Subsection "ev_child - watch out for process status changes" |
1786 | Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to |
1790 | Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to |
… | |
… | |
1935 | default compilation environment. |
1939 | default compilation environment. |
1936 | .PP |
1940 | .PP |
1937 | \fIInotify and Kqueue\fR |
1941 | \fIInotify and Kqueue\fR |
1938 | .IX Subsection "Inotify and Kqueue" |
1942 | .IX Subsection "Inotify and Kqueue" |
1939 | .PP |
1943 | .PP |
1940 | When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally only |
1944 | When \f(CW\*(C`inotify (7)\*(C'\fR support has been compiled into libev (generally |
|
|
1945 | only available with Linux 2.6.25 or above due to bugs in earlier |
1941 | available with Linux) and present at runtime, it will be used to speed up |
1946 | implementations) and present at runtime, it will be used to speed up |
1942 | change detection where possible. The inotify descriptor will be created lazily |
1947 | change detection where possible. The inotify descriptor will be created |
1943 | when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started. |
1948 | lazily when the first \f(CW\*(C`ev_stat\*(C'\fR watcher is being started. |
1944 | .PP |
1949 | .PP |
1945 | Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers |
1950 | Inotify presence does not change the semantics of \f(CW\*(C`ev_stat\*(C'\fR watchers |
1946 | except that changes might be detected earlier, and in some cases, to avoid |
1951 | except that changes might be detected earlier, and in some cases, to avoid |
1947 | making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support |
1952 | making regular \f(CW\*(C`stat\*(C'\fR calls. Even in the presence of inotify support |
1948 | there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling, |
1953 | there are many cases where libev has to resort to regular \f(CW\*(C`stat\*(C'\fR polling, |
… | |
… | |
2521 | queue. But at least I can tell you how to implement locking around your |
2526 | queue. But at least I can tell you how to implement locking around your |
2522 | queue: |
2527 | queue: |
2523 | .IP "queueing from a signal handler context" 4 |
2528 | .IP "queueing from a signal handler context" 4 |
2524 | .IX Item "queueing from a signal handler context" |
2529 | .IX Item "queueing from a signal handler context" |
2525 | To implement race-free queueing, you simply add to the queue in the signal |
2530 | To implement race-free queueing, you simply add to the queue in the signal |
2526 | handler but you block the signal handler in the watcher callback. Here is an example that does that for |
2531 | handler but you block the signal handler in the watcher callback. Here is |
2527 | some fictitious \s-1SIGUSR1\s0 handler: |
2532 | an example that does that for some fictitious \s-1SIGUSR1\s0 handler: |
2528 | .Sp |
2533 | .Sp |
2529 | .Vb 1 |
2534 | .Vb 1 |
2530 | \& static ev_async mysig; |
2535 | \& static ev_async mysig; |
2531 | \& |
2536 | \& |
2532 | \& static void |
2537 | \& static void |
… | |
… | |
2628 | .IX Header "OTHER FUNCTIONS" |
2633 | .IX Header "OTHER FUNCTIONS" |
2629 | There are some other functions of possible interest. Described. Here. Now. |
2634 | There are some other functions of possible interest. Described. Here. Now. |
2630 | .IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 |
2635 | .IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4 |
2631 | .IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" |
2636 | .IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" |
2632 | This function combines a simple timer and an I/O watcher, calls your |
2637 | This function combines a simple timer and an I/O watcher, calls your |
2633 | callback on whichever event happens first and automatically stop both |
2638 | callback on whichever event happens first and automatically stops both |
2634 | watchers. This is useful if you want to wait for a single event on an fd |
2639 | watchers. This is useful if you want to wait for a single event on an fd |
2635 | or timeout without having to allocate/configure/start/stop/free one or |
2640 | or timeout without having to allocate/configure/start/stop/free one or |
2636 | more watchers yourself. |
2641 | more watchers yourself. |
2637 | .Sp |
2642 | .Sp |
2638 | If \f(CW\*(C`fd\*(C'\fR is less than 0, then no I/O watcher will be started and events |
2643 | If \f(CW\*(C`fd\*(C'\fR is less than 0, then no I/O watcher will be started and the |
2639 | is being ignored. Otherwise, an \f(CW\*(C`ev_io\*(C'\fR watcher for the given \f(CW\*(C`fd\*(C'\fR and |
2644 | \&\f(CW\*(C`events\*(C'\fR argument is being ignored. Otherwise, an \f(CW\*(C`ev_io\*(C'\fR watcher for |
2640 | \&\f(CW\*(C`events\*(C'\fR set will be created and started. |
2645 | the given \f(CW\*(C`fd\*(C'\fR and \f(CW\*(C`events\*(C'\fR set will be created and started. |
2641 | .Sp |
2646 | .Sp |
2642 | If \f(CW\*(C`timeout\*(C'\fR is less than 0, then no timeout watcher will be |
2647 | If \f(CW\*(C`timeout\*(C'\fR is less than 0, then no timeout watcher will be |
2643 | started. Otherwise an \f(CW\*(C`ev_timer\*(C'\fR watcher with after = \f(CW\*(C`timeout\*(C'\fR (and |
2648 | started. Otherwise an \f(CW\*(C`ev_timer\*(C'\fR watcher with after = \f(CW\*(C`timeout\*(C'\fR (and |
2644 | repeat = 0) will be started. While \f(CW0\fR is a valid timeout, it is of |
2649 | repeat = 0) will be started. \f(CW0\fR is a valid timeout. |
2645 | dubious value. |
|
|
2646 | .Sp |
2650 | .Sp |
2647 | The callback has the type \f(CW\*(C`void (*cb)(int revents, void *arg)\*(C'\fR and gets |
2651 | The callback has the type \f(CW\*(C`void (*cb)(int revents, void *arg)\*(C'\fR and gets |
2648 | passed an \f(CW\*(C`revents\*(C'\fR set like normal event callbacks (a combination of |
2652 | passed an \f(CW\*(C`revents\*(C'\fR set like normal event callbacks (a combination of |
2649 | \&\f(CW\*(C`EV_ERROR\*(C'\fR, \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_TIMEOUT\*(C'\fR) and the \f(CW\*(C`arg\*(C'\fR |
2653 | \&\f(CW\*(C`EV_ERROR\*(C'\fR, \f(CW\*(C`EV_READ\*(C'\fR, \f(CW\*(C`EV_WRITE\*(C'\fR or \f(CW\*(C`EV_TIMEOUT\*(C'\fR) and the \f(CW\*(C`arg\*(C'\fR |
2650 | value passed to \f(CW\*(C`ev_once\*(C'\fR: |
2654 | value passed to \f(CW\*(C`ev_once\*(C'\fR. Note that it is possible to receive \fIboth\fR |
|
|
2655 | a timeout and an io event at the same time \- you probably should give io |
|
|
2656 | events precedence. |
|
|
2657 | .Sp |
|
|
2658 | Example: wait up to ten seconds for data to appear on \s-1STDIN_FILENO\s0. |
2651 | .Sp |
2659 | .Sp |
2652 | .Vb 7 |
2660 | .Vb 7 |
2653 | \& static void stdin_ready (int revents, void *arg) |
2661 | \& static void stdin_ready (int revents, void *arg) |
2654 | \& { |
2662 | \& { |
|
|
2663 | \& if (revents & EV_READ) |
|
|
2664 | \& /* stdin might have data for us, joy! */; |
2655 | \& if (revents & EV_TIMEOUT) |
2665 | \& else if (revents & EV_TIMEOUT) |
2656 | \& /* doh, nothing entered */; |
2666 | \& /* doh, nothing entered */; |
2657 | \& else if (revents & EV_READ) |
|
|
2658 | \& /* stdin might have data for us, joy! */; |
|
|
2659 | \& } |
2667 | \& } |
2660 | \& |
2668 | \& |
2661 | \& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
2669 | \& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
2662 | .Ve |
2670 | .Ve |
2663 | .IP "ev_feed_event (ev_loop *, watcher *, int revents)" 4 |
2671 | .IP "ev_feed_event (ev_loop *, watcher *, int revents)" 4 |
… | |
… | |
3398 | .PP |
3406 | .PP |
3399 | .Vb 2 |
3407 | .Vb 2 |
3400 | \& #include "ev_cpp.h" |
3408 | \& #include "ev_cpp.h" |
3401 | \& #include "ev.c" |
3409 | \& #include "ev.c" |
3402 | .Ve |
3410 | .Ve |
3403 | .SH "THREADS AND COROUTINES" |
3411 | .SH "INTERACTION WITH OTHER PROGRAMS OR LIBRARIES" |
|
|
3412 | .IX Header "INTERACTION WITH OTHER PROGRAMS OR LIBRARIES" |
|
|
3413 | .Sh "\s-1THREADS\s0 \s-1AND\s0 \s-1COROUTINES\s0" |
3404 | .IX Header "THREADS AND COROUTINES" |
3414 | .IX Subsection "THREADS AND COROUTINES" |
3405 | .Sh "\s-1THREADS\s0" |
3415 | \fI\s-1THREADS\s0\fR |
3406 | .IX Subsection "THREADS" |
3416 | .IX Subsection "THREADS" |
|
|
3417 | .PP |
3407 | All libev functions are reentrant and thread-safe unless explicitly |
3418 | All libev functions are reentrant and thread-safe unless explicitly |
3408 | documented otherwise, but it uses no locking itself. This means that you |
3419 | documented otherwise, but libev implements no locking itself. This means |
3409 | can use as many loops as you want in parallel, as long as there are no |
3420 | that you can use as many loops as you want in parallel, as long as there |
3410 | concurrent calls into any libev function with the same loop parameter |
3421 | are no concurrent calls into any libev function with the same loop |
3411 | (\f(CW\*(C`ev_default_*\*(C'\fR calls have an implicit default loop parameter, of |
3422 | parameter (\f(CW\*(C`ev_default_*\*(C'\fR calls have an implicit default loop parameter, |
3412 | course): libev guarantees that different event loops share no data |
3423 | of course): libev guarantees that different event loops share no data |
3413 | structures that need any locking. |
3424 | structures that need any locking. |
3414 | .PP |
3425 | .PP |
3415 | Or to put it differently: calls with different loop parameters can be done |
3426 | Or to put it differently: calls with different loop parameters can be done |
3416 | concurrently from multiple threads, calls with the same loop parameter |
3427 | concurrently from multiple threads, calls with the same loop parameter |
3417 | must be done serially (but can be done from different threads, as long as |
3428 | must be done serially (but can be done from different threads, as long as |
… | |
… | |
3452 | .Sp |
3463 | .Sp |
3453 | An example use would be to communicate signals or other events that only |
3464 | An example use would be to communicate signals or other events that only |
3454 | work in the default loop by registering the signal watcher with the |
3465 | work in the default loop by registering the signal watcher with the |
3455 | default loop and triggering an \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop |
3466 | default loop and triggering an \f(CW\*(C`ev_async\*(C'\fR watcher from the default loop |
3456 | watcher callback into the event loop interested in the signal. |
3467 | watcher callback into the event loop interested in the signal. |
3457 | .Sh "\s-1COROUTINES\s0" |
3468 | .PP |
|
|
3469 | \fI\s-1COROUTINES\s0\fR |
3458 | .IX Subsection "COROUTINES" |
3470 | .IX Subsection "COROUTINES" |
|
|
3471 | .PP |
3459 | Libev is much more accommodating to coroutines (\*(L"cooperative threads\*(R"): |
3472 | Libev is very accommodating to coroutines (\*(L"cooperative threads\*(R"): |
3460 | libev fully supports nesting calls to it's functions from different |
3473 | libev fully supports nesting calls to its functions from different |
3461 | coroutines (e.g. you can call \f(CW\*(C`ev_loop\*(C'\fR on the same loop from two |
3474 | coroutines (e.g. you can call \f(CW\*(C`ev_loop\*(C'\fR on the same loop from two |
3462 | different coroutines and switch freely between both coroutines running the |
3475 | different coroutines, and switch freely between both coroutines running the |
3463 | loop, as long as you don't confuse yourself). The only exception is that |
3476 | loop, as long as you don't confuse yourself). The only exception is that |
3464 | you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks. |
3477 | you must not do this from \f(CW\*(C`ev_periodic\*(C'\fR reschedule callbacks. |
3465 | .PP |
3478 | .PP |
3466 | Care has been taken to ensure that libev does not keep local state inside |
3479 | Care has been taken to ensure that libev does not keep local state inside |
3467 | \&\f(CW\*(C`ev_loop\*(C'\fR, and other calls do not usually allow coroutine switches. |
3480 | \&\f(CW\*(C`ev_loop\*(C'\fR, and other calls do not usually allow for coroutine switches as |
|
|
3481 | they do not clal any callbacks. |
|
|
3482 | .Sh "\s-1COMPILER\s0 \s-1WARNINGS\s0" |
|
|
3483 | .IX Subsection "COMPILER WARNINGS" |
|
|
3484 | Depending on your compiler and compiler settings, you might get no or a |
|
|
3485 | lot of warnings when compiling libev code. Some people are apparently |
|
|
3486 | scared by this. |
|
|
3487 | .PP |
|
|
3488 | However, these are unavoidable for many reasons. For one, each compiler |
|
|
3489 | has different warnings, and each user has different tastes regarding |
|
|
3490 | warning options. \*(L"Warn-free\*(R" code therefore cannot be a goal except when |
|
|
3491 | targeting a specific compiler and compiler-version. |
|
|
3492 | .PP |
|
|
3493 | Another reason is that some compiler warnings require elaborate |
|
|
3494 | workarounds, or other changes to the code that make it less clear and less |
|
|
3495 | maintainable. |
|
|
3496 | .PP |
|
|
3497 | And of course, some compiler warnings are just plain stupid, or simply |
|
|
3498 | wrong (because they don't actually warn about the condition their message |
|
|
3499 | seems to warn about). For example, certain older gcc versions had some |
|
|
3500 | warnings that resulted an extreme number of false positives. These have |
|
|
3501 | been fixed, but some people still insist on making code warn-free with |
|
|
3502 | such buggy versions. |
|
|
3503 | .PP |
|
|
3504 | While libev is written to generate as few warnings as possible, |
|
|
3505 | \&\*(L"warn-free\*(R" code is not a goal, and it is recommended not to build libev |
|
|
3506 | with any compiler warnings enabled unless you are prepared to cope with |
|
|
3507 | them (e.g. by ignoring them). Remember that warnings are just that: |
|
|
3508 | warnings, not errors, or proof of bugs. |
|
|
3509 | .Sh "\s-1VALGRIND\s0" |
|
|
3510 | .IX Subsection "VALGRIND" |
|
|
3511 | Valgrind has a special section here because it is a popular tool that is |
|
|
3512 | highly useful. Unfortunately, valgrind reports are very hard to interpret. |
|
|
3513 | .PP |
|
|
3514 | If you think you found a bug (memory leak, uninitialised data access etc.) |
|
|
3515 | in libev, then check twice: If valgrind reports something like: |
|
|
3516 | .PP |
|
|
3517 | .Vb 3 |
|
|
3518 | \& ==2274== definitely lost: 0 bytes in 0 blocks. |
|
|
3519 | \& ==2274== possibly lost: 0 bytes in 0 blocks. |
|
|
3520 | \& ==2274== still reachable: 256 bytes in 1 blocks. |
|
|
3521 | .Ve |
|
|
3522 | .PP |
|
|
3523 | Then there is no memory leak, just as memory accounted to global variables |
|
|
3524 | is not a memleak \- the memory is still being refernced, and didn't leak. |
|
|
3525 | .PP |
|
|
3526 | Similarly, under some circumstances, valgrind might report kernel bugs |
|
|
3527 | as if it were a bug in libev (e.g. in realloc or in the poll backend, |
|
|
3528 | although an acceptable workaround has been found here), or it might be |
|
|
3529 | confused. |
|
|
3530 | .PP |
|
|
3531 | Keep in mind that valgrind is a very good tool, but only a tool. Don't |
|
|
3532 | make it into some kind of religion. |
|
|
3533 | .PP |
|
|
3534 | If you are unsure about something, feel free to contact the mailing list |
|
|
3535 | with the full valgrind report and an explanation on why you think this |
|
|
3536 | is a bug in libev (best check the archives, too :). However, don't be |
|
|
3537 | annoyed when you get a brisk \*(L"this is no bug\*(R" answer and take the chance |
|
|
3538 | of learning how to interpret valgrind properly. |
|
|
3539 | .PP |
|
|
3540 | If you need, for some reason, empty reports from valgrind for your project |
|
|
3541 | I suggest using suppression lists. |
|
|
3542 | .SH "PORTABILITY NOTES" |
|
|
3543 | .IX Header "PORTABILITY NOTES" |
|
|
3544 | .Sh "\s-1WIN32\s0 \s-1PLATFORM\s0 \s-1LIMITATIONS\s0 \s-1AND\s0 \s-1WORKAROUNDS\s0" |
|
|
3545 | .IX Subsection "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS" |
|
|
3546 | Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev |
|
|
3547 | requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0 |
|
|
3548 | model. Libev still offers limited functionality on this platform in |
|
|
3549 | the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket |
|
|
3550 | descriptors. This only applies when using Win32 natively, not when using |
|
|
3551 | e.g. cygwin. |
|
|
3552 | .PP |
|
|
3553 | Lifting these limitations would basically require the full |
|
|
3554 | re-implementation of the I/O system. If you are into these kinds of |
|
|
3555 | things, then note that glib does exactly that for you in a very portable |
|
|
3556 | way (note also that glib is the slowest event library known to man). |
|
|
3557 | .PP |
|
|
3558 | There is no supported compilation method available on windows except |
|
|
3559 | embedding it into other applications. |
|
|
3560 | .PP |
|
|
3561 | Not a libev limitation but worth mentioning: windows apparently doesn't |
|
|
3562 | accept large writes: instead of resulting in a partial write, windows will |
|
|
3563 | either accept everything or return \f(CW\*(C`ENOBUFS\*(C'\fR if the buffer is too large, |
|
|
3564 | so make sure you only write small amounts into your sockets (less than a |
|
|
3565 | megabyte seems safe, but this apparently depends on the amount of memory |
|
|
3566 | available). |
|
|
3567 | .PP |
|
|
3568 | Due to the many, low, and arbitrary limits on the win32 platform and |
|
|
3569 | the abysmal performance of winsockets, using a large number of sockets |
|
|
3570 | is not recommended (and not reasonable). If your program needs to use |
|
|
3571 | more than a hundred or so sockets, then likely it needs to use a totally |
|
|
3572 | different implementation for windows, as libev offers the \s-1POSIX\s0 readiness |
|
|
3573 | notification model, which cannot be implemented efficiently on windows |
|
|
3574 | (Microsoft monopoly games). |
|
|
3575 | .PP |
|
|
3576 | A typical way to use libev under windows is to embed it (see the embedding |
|
|
3577 | section for details) and use the following \fIevwrap.h\fR header file instead |
|
|
3578 | of \fIev.h\fR: |
|
|
3579 | .PP |
|
|
3580 | .Vb 2 |
|
|
3581 | \& #define EV_STANDALONE /* keeps ev from requiring config.h */ |
|
|
3582 | \& #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ |
|
|
3583 | \& |
|
|
3584 | \& #include "ev.h" |
|
|
3585 | .Ve |
|
|
3586 | .PP |
|
|
3587 | And compile the following \fIevwrap.c\fR file into your project (make sure |
|
|
3588 | you do \fInot\fR compile the \fIev.c\fR or any other embedded source files!): |
|
|
3589 | .PP |
|
|
3590 | .Vb 2 |
|
|
3591 | \& #include "evwrap.h" |
|
|
3592 | \& #include "ev.c" |
|
|
3593 | .Ve |
|
|
3594 | .IP "The winsocket select function" 4 |
|
|
3595 | .IX Item "The winsocket select function" |
|
|
3596 | The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it |
|
|
3597 | requires socket \fIhandles\fR and not socket \fIfile descriptors\fR (it is |
|
|
3598 | also extremely buggy). This makes select very inefficient, and also |
|
|
3599 | requires a mapping from file descriptors to socket handles (the Microsoft |
|
|
3600 | C runtime provides the function \f(CW\*(C`_open_osfhandle\*(C'\fR for this). See the |
|
|
3601 | discussion of the \f(CW\*(C`EV_SELECT_USE_FD_SET\*(C'\fR, \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR and |
|
|
3602 | \&\f(CW\*(C`EV_FD_TO_WIN32_HANDLE\*(C'\fR preprocessor symbols for more info. |
|
|
3603 | .Sp |
|
|
3604 | The configuration for a \*(L"naked\*(R" win32 using the Microsoft runtime |
|
|
3605 | libraries and raw winsocket select is: |
|
|
3606 | .Sp |
|
|
3607 | .Vb 2 |
|
|
3608 | \& #define EV_USE_SELECT 1 |
|
|
3609 | \& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ |
|
|
3610 | .Ve |
|
|
3611 | .Sp |
|
|
3612 | Note that winsockets handling of fd sets is O(n), so you can easily get a |
|
|
3613 | complexity in the O(nA\*^X) range when using win32. |
|
|
3614 | .IP "Limited number of file descriptors" 4 |
|
|
3615 | .IX Item "Limited number of file descriptors" |
|
|
3616 | Windows has numerous arbitrary (and low) limits on things. |
|
|
3617 | .Sp |
|
|
3618 | Early versions of winsocket's select only supported waiting for a maximum |
|
|
3619 | of \f(CW64\fR handles (probably owning to the fact that all windows kernels |
|
|
3620 | can only wait for \f(CW64\fR things at the same time internally; Microsoft |
|
|
3621 | recommends spawning a chain of threads and wait for 63 handles and the |
|
|
3622 | previous thread in each. Great). |
|
|
3623 | .Sp |
|
|
3624 | Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR |
|
|
3625 | to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select |
|
|
3626 | call (which might be in libev or elsewhere, for example, perl does its own |
|
|
3627 | select emulation on windows). |
|
|
3628 | .Sp |
|
|
3629 | Another limit is the number of file descriptors in the Microsoft runtime |
|
|
3630 | libraries, which by default is \f(CW64\fR (there must be a hidden \fI64\fR fetish |
|
|
3631 | or something like this inside Microsoft). You can increase this by calling |
|
|
3632 | \&\f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR (another |
|
|
3633 | arbitrary limit), but is broken in many versions of the Microsoft runtime |
|
|
3634 | libraries. |
|
|
3635 | .Sp |
|
|
3636 | This might get you to about \f(CW512\fR or \f(CW2048\fR sockets (depending on |
|
|
3637 | windows version and/or the phase of the moon). To get more, you need to |
|
|
3638 | wrap all I/O functions and provide your own fd management, but the cost of |
|
|
3639 | calling select (O(nA\*^X)) will likely make this unworkable. |
|
|
3640 | .Sh "\s-1PORTABILITY\s0 \s-1REQUIREMENTS\s0" |
|
|
3641 | .IX Subsection "PORTABILITY REQUIREMENTS" |
|
|
3642 | In addition to a working ISO-C implementation and of course the |
|
|
3643 | backend-specific APIs, libev relies on a few additional extensions: |
|
|
3644 | .ie n .IP """void (*)(ev_watcher_type *, int revents)""\fR must have compatible calling conventions regardless of \f(CW""ev_watcher_type *""." 4 |
|
|
3645 | .el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4 |
|
|
3646 | .IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *." |
|
|
3647 | Libev assumes not only that all watcher pointers have the same internal |
|
|
3648 | structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO\s0 C for example), but it also |
|
|
3649 | assumes that the same (machine) code can be used to call any watcher |
|
|
3650 | callback: The watcher callbacks have different type signatures, but libev |
|
|
3651 | calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. |
|
|
3652 | .ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 |
|
|
3653 | .el .IP "\f(CWsig_atomic_t volatile\fR must be thread-atomic as well" 4 |
|
|
3654 | .IX Item "sig_atomic_t volatile must be thread-atomic as well" |
|
|
3655 | The type \f(CW\*(C`sig_atomic_t volatile\*(C'\fR (or whatever is defined as |
|
|
3656 | \&\f(CW\*(C`EV_ATOMIC_T\*(C'\fR) must be atomic with respect to accesses from different |
|
|
3657 | threads. This is not part of the specification for \f(CW\*(C`sig_atomic_t\*(C'\fR, but is |
|
|
3658 | believed to be sufficiently portable. |
|
|
3659 | .ie n .IP """sigprocmask"" must work in a threaded environment" 4 |
|
|
3660 | .el .IP "\f(CWsigprocmask\fR must work in a threaded environment" 4 |
|
|
3661 | .IX Item "sigprocmask must work in a threaded environment" |
|
|
3662 | Libev uses \f(CW\*(C`sigprocmask\*(C'\fR to temporarily block signals. This is not |
|
|
3663 | allowed in a threaded program (\f(CW\*(C`pthread_sigmask\*(C'\fR has to be used). Typical |
|
|
3664 | pthread implementations will either allow \f(CW\*(C`sigprocmask\*(C'\fR in the \*(L"main |
|
|
3665 | thread\*(R" or will block signals process-wide, both behaviours would |
|
|
3666 | be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and |
|
|
3667 | \&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. |
|
|
3668 | .Sp |
|
|
3669 | The most portable way to handle signals is to block signals in all threads |
|
|
3670 | except the initial one, and run the default loop in the initial thread as |
|
|
3671 | well. |
|
|
3672 | .ie n .IP """long"" must be large enough for common memory allocation sizes" 4 |
|
|
3673 | .el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 |
|
|
3674 | .IX Item "long must be large enough for common memory allocation sizes" |
|
|
3675 | To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally |
|
|
3676 | instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX |
|
|
3677 | systems (Microsoft...) this might be unexpectedly low, but is still at |
|
|
3678 | least 31 bits everywhere, which is enough for hundreds of millions of |
|
|
3679 | watchers. |
|
|
3680 | .ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4 |
|
|
3681 | .el .IP "\f(CWdouble\fR must hold a time value in seconds with enough accuracy" 4 |
|
|
3682 | .IX Item "double must hold a time value in seconds with enough accuracy" |
|
|
3683 | The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to |
|
|
3684 | have at least 51 bits of mantissa (and 9 bits of exponent), which is good |
|
|
3685 | enough for at least into the year 4000. This requirement is fulfilled by |
|
|
3686 | implementations implementing \s-1IEEE\s0 754 (basically all existing ones). |
|
|
3687 | .PP |
|
|
3688 | If you know of other additional requirements drop me a note. |
3468 | .SH "COMPLEXITIES" |
3689 | .SH "ALGORITHMIC COMPLEXITIES" |
3469 | .IX Header "COMPLEXITIES" |
3690 | .IX Header "ALGORITHMIC COMPLEXITIES" |
3470 | In this section the complexities of (many of) the algorithms used inside |
3691 | In this section the complexities of (many of) the algorithms used inside |
3471 | libev will be explained. For complexity discussions about backends see the |
3692 | libev will be documented. For complexity discussions about backends see |
3472 | documentation for \f(CW\*(C`ev_default_init\*(C'\fR. |
3693 | the documentation for \f(CW\*(C`ev_default_init\*(C'\fR. |
3473 | .PP |
3694 | .PP |
3474 | All of the following are about amortised time: If an array needs to be |
3695 | All of the following are about amortised time: If an array needs to be |
3475 | extended, libev needs to realloc and move the whole array, but this |
3696 | extended, libev needs to realloc and move the whole array, but this |
3476 | happens asymptotically never with higher number of elements, so O(1) might |
3697 | happens asymptotically rarer with higher number of elements, so O(1) might |
3477 | mean it might do a lengthy realloc operation in rare cases, but on average |
3698 | mean that libev does a lengthy realloc operation in rare cases, but on |
3478 | it is much faster and asymptotically approaches constant time. |
3699 | average it is much faster and asymptotically approaches constant time. |
3479 | .IP "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 4 |
3700 | .IP "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 4 |
3480 | .IX Item "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" |
3701 | .IX Item "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" |
3481 | This means that, when you have a watcher that triggers in one hour and |
3702 | This means that, when you have a watcher that triggers in one hour and |
3482 | there are 100 watchers that would trigger before that then inserting will |
3703 | there are 100 watchers that would trigger before that, then inserting will |
3483 | have to skip roughly seven (\f(CW\*(C`ld 100\*(C'\fR) of these watchers. |
3704 | have to skip roughly seven (\f(CW\*(C`ld 100\*(C'\fR) of these watchers. |
3484 | .IP "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" 4 |
3705 | .IP "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" 4 |
3485 | .IX Item "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" |
3706 | .IX Item "Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers)" |
3486 | That means that changing a timer costs less than removing/adding them |
3707 | That means that changing a timer costs less than removing/adding them, |
3487 | as only the relative motion in the event queue has to be paid for. |
3708 | as only the relative motion in the event queue has to be paid for. |
3488 | .IP "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)" 4 |
3709 | .IP "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)" 4 |
3489 | .IX Item "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)" |
3710 | .IX Item "Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1)" |
3490 | These just add the watcher into an array or at the head of a list. |
3711 | These just add the watcher into an array or at the head of a list. |
3491 | .IP "Stopping check/prepare/idle/fork/async watchers: O(1)" 4 |
3712 | .IP "Stopping check/prepare/idle/fork/async watchers: O(1)" 4 |
3492 | .IX Item "Stopping check/prepare/idle/fork/async watchers: O(1)" |
3713 | .IX Item "Stopping check/prepare/idle/fork/async watchers: O(1)" |
3493 | .PD 0 |
3714 | .PD 0 |
3494 | .IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % \s-1EV_PID_HASHSIZE\s0))" 4 |
3715 | .IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % \s-1EV_PID_HASHSIZE\s0))" 4 |
3495 | .IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))" |
3716 | .IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE))" |
3496 | .PD |
3717 | .PD |
3497 | These watchers are stored in lists then need to be walked to find the |
3718 | These watchers are stored in lists, so they need to be walked to find the |
3498 | correct watcher to remove. The lists are usually short (you don't usually |
3719 | correct watcher to remove. The lists are usually short (you don't usually |
3499 | have many watchers waiting for the same fd or signal). |
3720 | have many watchers waiting for the same fd or signal: one is typical, two |
|
|
3721 | is rare). |
3500 | .IP "Finding the next timer in each loop iteration: O(1)" 4 |
3722 | .IP "Finding the next timer in each loop iteration: O(1)" 4 |
3501 | .IX Item "Finding the next timer in each loop iteration: O(1)" |
3723 | .IX Item "Finding the next timer in each loop iteration: O(1)" |
3502 | By virtue of using a binary or 4\-heap, the next timer is always found at a |
3724 | By virtue of using a binary or 4\-heap, the next timer is always found at a |
3503 | fixed position in the storage array. |
3725 | fixed position in the storage array. |
3504 | .IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4 |
3726 | .IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4 |
… | |
… | |
3525 | .IX Item "Processing signals: O(max_signal_number)" |
3747 | .IX Item "Processing signals: O(max_signal_number)" |
3526 | .PD |
3748 | .PD |
3527 | Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR |
3749 | Sending involves a system call \fIiff\fR there were no other \f(CW\*(C`ev_async_send\*(C'\fR |
3528 | calls in the current loop iteration. Checking for async and signal events |
3750 | calls in the current loop iteration. Checking for async and signal events |
3529 | involves iterating over all running async watchers or all signal numbers. |
3751 | involves iterating over all running async watchers or all signal numbers. |
3530 | .SH "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS" |
|
|
3531 | .IX Header "WIN32 PLATFORM LIMITATIONS AND WORKAROUNDS" |
|
|
3532 | Win32 doesn't support any of the standards (e.g. \s-1POSIX\s0) that libev |
|
|
3533 | requires, and its I/O model is fundamentally incompatible with the \s-1POSIX\s0 |
|
|
3534 | model. Libev still offers limited functionality on this platform in |
|
|
3535 | the form of the \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR backend, and only supports socket |
|
|
3536 | descriptors. This only applies when using Win32 natively, not when using |
|
|
3537 | e.g. cygwin. |
|
|
3538 | .PP |
|
|
3539 | Lifting these limitations would basically require the full |
|
|
3540 | re-implementation of the I/O system. If you are into these kinds of |
|
|
3541 | things, then note that glib does exactly that for you in a very portable |
|
|
3542 | way (note also that glib is the slowest event library known to man). |
|
|
3543 | .PP |
|
|
3544 | There is no supported compilation method available on windows except |
|
|
3545 | embedding it into other applications. |
|
|
3546 | .PP |
|
|
3547 | Not a libev limitation but worth mentioning: windows apparently doesn't |
|
|
3548 | accept large writes: instead of resulting in a partial write, windows will |
|
|
3549 | either accept everything or return \f(CW\*(C`ENOBUFS\*(C'\fR if the buffer is too large, |
|
|
3550 | so make sure you only write small amounts into your sockets (less than a |
|
|
3551 | megabyte seems safe, but this apparently depends on the amount of memory |
|
|
3552 | available). |
|
|
3553 | .PP |
|
|
3554 | Due to the many, low, and arbitrary limits on the win32 platform and |
|
|
3555 | the abysmal performance of winsockets, using a large number of sockets |
|
|
3556 | is not recommended (and not reasonable). If your program needs to use |
|
|
3557 | more than a hundred or so sockets, then likely it needs to use a totally |
|
|
3558 | different implementation for windows, as libev offers the \s-1POSIX\s0 readiness |
|
|
3559 | notification model, which cannot be implemented efficiently on windows |
|
|
3560 | (Microsoft monopoly games). |
|
|
3561 | .PP |
|
|
3562 | A typical way to use libev under windows is to embed it (see the embedding |
|
|
3563 | section for details) and use the following \fIevwrap.h\fR header file instead |
|
|
3564 | of \fIev.h\fR: |
|
|
3565 | .PP |
|
|
3566 | .Vb 2 |
|
|
3567 | \& #define EV_STANDALONE /* keeps ev from requiring config.h */ |
|
|
3568 | \& #define EV_SELECT_IS_WINSOCKET 1 /* configure libev for windows select */ |
|
|
3569 | \& |
|
|
3570 | \& #include "ev.h" |
|
|
3571 | .Ve |
|
|
3572 | .PP |
|
|
3573 | And compile the following \fIevwrap.c\fR file into your project (make sure |
|
|
3574 | you do \fInot\fR compile the \fIev.c\fR or any other embedded source files!): |
|
|
3575 | .PP |
|
|
3576 | .Vb 2 |
|
|
3577 | \& #include "evwrap.h" |
|
|
3578 | \& #include "ev.c" |
|
|
3579 | .Ve |
|
|
3580 | .IP "The winsocket select function" 4 |
|
|
3581 | .IX Item "The winsocket select function" |
|
|
3582 | The winsocket \f(CW\*(C`select\*(C'\fR function doesn't follow \s-1POSIX\s0 in that it |
|
|
3583 | requires socket \fIhandles\fR and not socket \fIfile descriptors\fR (it is |
|
|
3584 | also extremely buggy). This makes select very inefficient, and also |
|
|
3585 | requires a mapping from file descriptors to socket handles (the Microsoft |
|
|
3586 | C runtime provides the function \f(CW\*(C`_open_osfhandle\*(C'\fR for this). See the |
|
|
3587 | discussion of the \f(CW\*(C`EV_SELECT_USE_FD_SET\*(C'\fR, \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR and |
|
|
3588 | \&\f(CW\*(C`EV_FD_TO_WIN32_HANDLE\*(C'\fR preprocessor symbols for more info. |
|
|
3589 | .Sp |
|
|
3590 | The configuration for a \*(L"naked\*(R" win32 using the Microsoft runtime |
|
|
3591 | libraries and raw winsocket select is: |
|
|
3592 | .Sp |
|
|
3593 | .Vb 2 |
|
|
3594 | \& #define EV_USE_SELECT 1 |
|
|
3595 | \& #define EV_SELECT_IS_WINSOCKET 1 /* forces EV_SELECT_USE_FD_SET, too */ |
|
|
3596 | .Ve |
|
|
3597 | .Sp |
|
|
3598 | Note that winsockets handling of fd sets is O(n), so you can easily get a |
|
|
3599 | complexity in the O(nA\*^X) range when using win32. |
|
|
3600 | .IP "Limited number of file descriptors" 4 |
|
|
3601 | .IX Item "Limited number of file descriptors" |
|
|
3602 | Windows has numerous arbitrary (and low) limits on things. |
|
|
3603 | .Sp |
|
|
3604 | Early versions of winsocket's select only supported waiting for a maximum |
|
|
3605 | of \f(CW64\fR handles (probably owning to the fact that all windows kernels |
|
|
3606 | can only wait for \f(CW64\fR things at the same time internally; Microsoft |
|
|
3607 | recommends spawning a chain of threads and wait for 63 handles and the |
|
|
3608 | previous thread in each. Great). |
|
|
3609 | .Sp |
|
|
3610 | Newer versions support more handles, but you need to define \f(CW\*(C`FD_SETSIZE\*(C'\fR |
|
|
3611 | to some high number (e.g. \f(CW2048\fR) before compiling the winsocket select |
|
|
3612 | call (which might be in libev or elsewhere, for example, perl does its own |
|
|
3613 | select emulation on windows). |
|
|
3614 | .Sp |
|
|
3615 | Another limit is the number of file descriptors in the Microsoft runtime |
|
|
3616 | libraries, which by default is \f(CW64\fR (there must be a hidden \fI64\fR fetish |
|
|
3617 | or something like this inside Microsoft). You can increase this by calling |
|
|
3618 | \&\f(CW\*(C`_setmaxstdio\*(C'\fR, which can increase this limit to \f(CW2048\fR (another |
|
|
3619 | arbitrary limit), but is broken in many versions of the Microsoft runtime |
|
|
3620 | libraries. |
|
|
3621 | .Sp |
|
|
3622 | This might get you to about \f(CW512\fR or \f(CW2048\fR sockets (depending on |
|
|
3623 | windows version and/or the phase of the moon). To get more, you need to |
|
|
3624 | wrap all I/O functions and provide your own fd management, but the cost of |
|
|
3625 | calling select (O(nA\*^X)) will likely make this unworkable. |
|
|
3626 | .SH "PORTABILITY REQUIREMENTS" |
|
|
3627 | .IX Header "PORTABILITY REQUIREMENTS" |
|
|
3628 | In addition to a working ISO-C implementation, libev relies on a few |
|
|
3629 | additional extensions: |
|
|
3630 | .ie n .IP """void (*)(ev_watcher_type *, int revents)""\fR must have compatible calling conventions regardless of \f(CW""ev_watcher_type *""." 4 |
|
|
3631 | .el .IP "\f(CWvoid (*)(ev_watcher_type *, int revents)\fR must have compatible calling conventions regardless of \f(CWev_watcher_type *\fR." 4 |
|
|
3632 | .IX Item "void (*)(ev_watcher_type *, int revents) must have compatible calling conventions regardless of ev_watcher_type *." |
|
|
3633 | Libev assumes not only that all watcher pointers have the same internal |
|
|
3634 | structure (guaranteed by \s-1POSIX\s0 but not by \s-1ISO\s0 C for example), but it also |
|
|
3635 | assumes that the same (machine) code can be used to call any watcher |
|
|
3636 | callback: The watcher callbacks have different type signatures, but libev |
|
|
3637 | calls them using an \f(CW\*(C`ev_watcher *\*(C'\fR internally. |
|
|
3638 | .ie n .IP """sig_atomic_t volatile"" must be thread-atomic as well" 4 |
|
|
3639 | .el .IP "\f(CWsig_atomic_t volatile\fR must be thread-atomic as well" 4 |
|
|
3640 | .IX Item "sig_atomic_t volatile must be thread-atomic as well" |
|
|
3641 | The type \f(CW\*(C`sig_atomic_t volatile\*(C'\fR (or whatever is defined as |
|
|
3642 | \&\f(CW\*(C`EV_ATOMIC_T\*(C'\fR) must be atomic with respect to accesses from different |
|
|
3643 | threads. This is not part of the specification for \f(CW\*(C`sig_atomic_t\*(C'\fR, but is |
|
|
3644 | believed to be sufficiently portable. |
|
|
3645 | .ie n .IP """sigprocmask"" must work in a threaded environment" 4 |
|
|
3646 | .el .IP "\f(CWsigprocmask\fR must work in a threaded environment" 4 |
|
|
3647 | .IX Item "sigprocmask must work in a threaded environment" |
|
|
3648 | Libev uses \f(CW\*(C`sigprocmask\*(C'\fR to temporarily block signals. This is not |
|
|
3649 | allowed in a threaded program (\f(CW\*(C`pthread_sigmask\*(C'\fR has to be used). Typical |
|
|
3650 | pthread implementations will either allow \f(CW\*(C`sigprocmask\*(C'\fR in the \*(L"main |
|
|
3651 | thread\*(R" or will block signals process-wide, both behaviours would |
|
|
3652 | be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and |
|
|
3653 | \&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. |
|
|
3654 | .Sp |
|
|
3655 | The most portable way to handle signals is to block signals in all threads |
|
|
3656 | except the initial one, and run the default loop in the initial thread as |
|
|
3657 | well. |
|
|
3658 | .ie n .IP """long"" must be large enough for common memory allocation sizes" 4 |
|
|
3659 | .el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 |
|
|
3660 | .IX Item "long must be large enough for common memory allocation sizes" |
|
|
3661 | To improve portability and simplify using libev, libev uses \f(CW\*(C`long\*(C'\fR |
|
|
3662 | internally instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On |
|
|
3663 | non-POSIX systems (Microsoft...) this might be unexpectedly low, but |
|
|
3664 | is still at least 31 bits everywhere, which is enough for hundreds of |
|
|
3665 | millions of watchers. |
|
|
3666 | .ie n .IP """double"" must hold a time value in seconds with enough accuracy" 4 |
|
|
3667 | .el .IP "\f(CWdouble\fR must hold a time value in seconds with enough accuracy" 4 |
|
|
3668 | .IX Item "double must hold a time value in seconds with enough accuracy" |
|
|
3669 | The type \f(CW\*(C`double\*(C'\fR is used to represent timestamps. It is required to |
|
|
3670 | have at least 51 bits of mantissa (and 9 bits of exponent), which is good |
|
|
3671 | enough for at least into the year 4000. This requirement is fulfilled by |
|
|
3672 | implementations implementing \s-1IEEE\s0 754 (basically all existing ones). |
|
|
3673 | .PP |
|
|
3674 | If you know of other additional requirements drop me a note. |
|
|
3675 | .SH "COMPILER WARNINGS" |
|
|
3676 | .IX Header "COMPILER WARNINGS" |
|
|
3677 | Depending on your compiler and compiler settings, you might get no or a |
|
|
3678 | lot of warnings when compiling libev code. Some people are apparently |
|
|
3679 | scared by this. |
|
|
3680 | .PP |
|
|
3681 | However, these are unavoidable for many reasons. For one, each compiler |
|
|
3682 | has different warnings, and each user has different tastes regarding |
|
|
3683 | warning options. \*(L"Warn-free\*(R" code therefore cannot be a goal except when |
|
|
3684 | targeting a specific compiler and compiler-version. |
|
|
3685 | .PP |
|
|
3686 | Another reason is that some compiler warnings require elaborate |
|
|
3687 | workarounds, or other changes to the code that make it less clear and less |
|
|
3688 | maintainable. |
|
|
3689 | .PP |
|
|
3690 | And of course, some compiler warnings are just plain stupid, or simply |
|
|
3691 | wrong (because they don't actually warn about the condition their message |
|
|
3692 | seems to warn about). |
|
|
3693 | .PP |
|
|
3694 | While libev is written to generate as few warnings as possible, |
|
|
3695 | \&\*(L"warn-free\*(R" code is not a goal, and it is recommended not to build libev |
|
|
3696 | with any compiler warnings enabled unless you are prepared to cope with |
|
|
3697 | them (e.g. by ignoring them). Remember that warnings are just that: |
|
|
3698 | warnings, not errors, or proof of bugs. |
|
|
3699 | .SH "VALGRIND" |
|
|
3700 | .IX Header "VALGRIND" |
|
|
3701 | Valgrind has a special section here because it is a popular tool that is |
|
|
3702 | highly useful, but valgrind reports are very hard to interpret. |
|
|
3703 | .PP |
|
|
3704 | If you think you found a bug (memory leak, uninitialised data access etc.) |
|
|
3705 | in libev, then check twice: If valgrind reports something like: |
|
|
3706 | .PP |
|
|
3707 | .Vb 3 |
|
|
3708 | \& ==2274== definitely lost: 0 bytes in 0 blocks. |
|
|
3709 | \& ==2274== possibly lost: 0 bytes in 0 blocks. |
|
|
3710 | \& ==2274== still reachable: 256 bytes in 1 blocks. |
|
|
3711 | .Ve |
|
|
3712 | .PP |
|
|
3713 | Then there is no memory leak. Similarly, under some circumstances, |
|
|
3714 | valgrind might report kernel bugs as if it were a bug in libev, or it |
|
|
3715 | might be confused (it is a very good tool, but only a tool). |
|
|
3716 | .PP |
|
|
3717 | If you are unsure about something, feel free to contact the mailing list |
|
|
3718 | with the full valgrind report and an explanation on why you think this is |
|
|
3719 | a bug in libev. However, don't be annoyed when you get a brisk \*(L"this is |
|
|
3720 | no bug\*(R" answer and take the chance of learning how to interpret valgrind |
|
|
3721 | properly. |
|
|
3722 | .PP |
|
|
3723 | If you need, for some reason, empty reports from valgrind for your project |
|
|
3724 | I suggest using suppression lists. |
|
|
3725 | .SH "AUTHOR" |
3752 | .SH "AUTHOR" |
3726 | .IX Header "AUTHOR" |
3753 | .IX Header "AUTHOR" |
3727 | Marc Lehmann <libev@schmorp.de>. |
3754 | Marc Lehmann <libev@schmorp.de>. |