ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.235 by root, Thu Apr 16 07:50:39 2009 UTC vs.
Revision 1.238 by root, Sat Apr 18 12:10:41 2009 UTC

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

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines