… | |
… | |
62 | |
62 | |
63 | // unloop was called, so exit |
63 | // unloop was called, so exit |
64 | return 0; |
64 | return 0; |
65 | } |
65 | } |
66 | |
66 | |
67 | =head1 DESCRIPTION |
67 | =head1 ABOUT THIS DOCUMENT |
|
|
68 | |
|
|
69 | This document documents the libev software package. |
68 | |
70 | |
69 | The newest version of this document is also available as an html-formatted |
71 | The newest version of this document is also available as an html-formatted |
70 | web page you might find easier to navigate when reading it for the first |
72 | web page you might find easier to navigate when reading it for the first |
71 | time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>. |
73 | time: L<http://pod.tst.eu/http://cvs.schmorp.de/libev/ev.pod>. |
|
|
74 | |
|
|
75 | While this document tries to be as complete as possible in documenting |
|
|
76 | libev, its usage and the rationale behind its design, it is not a tutorial |
|
|
77 | on event-based programming, nor will it introduce event-based programming |
|
|
78 | with libev. |
|
|
79 | |
|
|
80 | Familarity with event based programming techniques in general is assumed |
|
|
81 | throughout this document. |
|
|
82 | |
|
|
83 | =head1 ABOUT LIBEV |
72 | |
84 | |
73 | Libev is an event loop: you register interest in certain events (such as a |
85 | Libev is an event loop: you register interest in certain events (such as a |
74 | file descriptor being readable or a timeout occurring), and it will manage |
86 | file descriptor being readable or a timeout occurring), and it will manage |
75 | these event sources and provide your program with events. |
87 | these event sources and provide your program with events. |
76 | |
88 | |
… | |
… | |
110 | name C<loop> (which is always of type C<ev_loop *>) will not have |
122 | name C<loop> (which is always of type C<ev_loop *>) will not have |
111 | this argument. |
123 | this argument. |
112 | |
124 | |
113 | =head2 TIME REPRESENTATION |
125 | =head2 TIME REPRESENTATION |
114 | |
126 | |
115 | Libev represents time as a single floating point number, representing the |
127 | Libev represents time as a single floating point number, representing |
116 | (fractional) number of seconds since the (POSIX) epoch (somewhere near |
128 | the (fractional) number of seconds since the (POSIX) epoch (somewhere |
117 | the beginning of 1970, details are complicated, don't ask). This type is |
129 | near the beginning of 1970, details are complicated, don't ask). This |
118 | called C<ev_tstamp>, which is what you should use too. It usually aliases |
130 | type is called C<ev_tstamp>, which is what you should use too. It usually |
119 | to the C<double> type in C, and when you need to do any calculations on |
131 | aliases to the C<double> type in C. When you need to do any calculations |
120 | it, you should treat it as some floating point value. Unlike the name |
132 | on it, you should treat it as some floating point value. Unlike the name |
121 | component C<stamp> might indicate, it is also used for time differences |
133 | component C<stamp> might indicate, it is also used for time differences |
122 | throughout libev. |
134 | throughout libev. |
123 | |
135 | |
124 | =head1 ERROR HANDLING |
136 | =head1 ERROR HANDLING |
125 | |
137 | |
… | |
… | |
632 | |
644 | |
633 | This function is rarely useful, but when some event callback runs for a |
645 | This function is rarely useful, but when some event callback runs for a |
634 | very long time without entering the event loop, updating libev's idea of |
646 | very long time without entering the event loop, updating libev's idea of |
635 | the current time is a good idea. |
647 | the current time is a good idea. |
636 | |
648 | |
637 | See also "The special problem of time updates" in the C<ev_timer> section. |
649 | See also L<The special problem of time updates> in the C<ev_timer> section. |
638 | |
650 | |
639 | =item ev_suspend (loop) |
651 | =item ev_suspend (loop) |
640 | |
652 | |
641 | =item ev_resume (loop) |
653 | =item ev_resume (loop) |
642 | |
654 | |
… | |
… | |
2696 | event loop blocks next and before C<ev_check> watchers are being called, |
2708 | event loop blocks next and before C<ev_check> watchers are being called, |
2697 | and only in the child after the fork. If whoever good citizen calling |
2709 | and only in the child after the fork. If whoever good citizen calling |
2698 | C<ev_default_fork> cheats and calls it in the wrong process, the fork |
2710 | C<ev_default_fork> cheats and calls it in the wrong process, the fork |
2699 | handlers will be invoked, too, of course. |
2711 | handlers will be invoked, too, of course. |
2700 | |
2712 | |
|
|
2713 | =head3 The special problem of life after fork - how is it possible? |
|
|
2714 | |
|
|
2715 | Most uses of C<fork()> consist of forking, then some simple calls to ste |
|
|
2716 | up/change the process environment, followed by a call to C<exec()>. This |
|
|
2717 | sequence should be handled by libev without any problems. |
|
|
2718 | |
|
|
2719 | This changes when the application actually wants to do event handling |
|
|
2720 | in the child, or both parent in child, in effect "continuing" after the |
|
|
2721 | fork. |
|
|
2722 | |
|
|
2723 | The default mode of operation (for libev, with application help to detect |
|
|
2724 | forks) is to duplicate all the state in the child, as would be expected |
|
|
2725 | when I<either> the parent I<or> the child process continues. |
|
|
2726 | |
|
|
2727 | When both processes want to continue using libev, then this is usually the |
|
|
2728 | wrong result. In that case, usually one process (typically the parent) is |
|
|
2729 | supposed to continue with all watchers in place as before, while the other |
|
|
2730 | process typically wants to start fresh, i.e. without any active watchers. |
|
|
2731 | |
|
|
2732 | The cleanest and most efficient way to achieve that with libev is to |
|
|
2733 | simply create a new event loop, which of course will be "empty", and |
|
|
2734 | use that for new watchers. This has the advantage of not touching more |
|
|
2735 | memory than necessary, and thus avoiding the copy-on-write, and the |
|
|
2736 | disadvantage of having to use multiple event loops (which do not support |
|
|
2737 | signal watchers). |
|
|
2738 | |
|
|
2739 | When this is not possible, or you want to use the default loop for |
|
|
2740 | other reasons, then in the process that wants to start "fresh", call |
|
|
2741 | C<ev_default_destroy ()> followed by C<ev_default_loop (...)>. Destroying |
|
|
2742 | the default loop will "orphan" (not stop) all registered watchers, so you |
|
|
2743 | have to be careful not to execute code that modifies those watchers. Note |
|
|
2744 | also that in that case, you have to re-register any signal watchers. |
|
|
2745 | |
2701 | =head3 Watcher-Specific Functions and Data Members |
2746 | =head3 Watcher-Specific Functions and Data Members |
2702 | |
2747 | |
2703 | =over 4 |
2748 | =over 4 |
2704 | |
2749 | |
2705 | =item ev_fork_init (ev_signal *, callback) |
2750 | =item ev_fork_init (ev_signal *, callback) |