--- AnyEvent/lib/AnyEvent.pm 2008/04/25 13:05:17 1.81 +++ AnyEvent/lib/AnyEvent.pm 2008/04/25 13:51:32 1.85 @@ -143,17 +143,19 @@ You can create an I/O watcher by calling the C<< AnyEvent->io >> method with the following mandatory key-value pairs as arguments: -C the Perl I (I file descriptor) to watch for -events. C must be a string that is either C or C, which -creates a watcher waiting for "r"eadable or "w"ritable events, +C the Perl I (I file descriptor) to watch +for events. C must be a string that is either C or C, +which creates a watcher waiting for "r"eadable or "w"ritable events, respectively. C is the callback to invoke each time the file handle becomes ready. -As long as the I/O watcher exists it will keep the file descriptor or a -copy of it alive/open. - -It is not allowed to close a file handle as long as any watcher is active -on the underlying file descriptor. +Although the callback might get passed parameters, their value and +presence is undefined and you cannot rely on them. Portable AnyEvent +callbacks cannot use arguments passed to I/O watcher callbacks. + +The I/O watcher might use the underlying file descriptor or a copy of it. +You must not close a file handle as long as any watcher is active on the +underlying file descriptor. Some event loops issue spurious readyness notifications, so you should always use non-blocking calls when reading/writing from/to your file @@ -174,8 +176,12 @@ method with the following mandatory arguments: C specifies after how many seconds (fractional values are -supported) should the timer activate. C the callback to invoke in that -case. +supported) the callback should be invoked. C is the callback to invoke +in that case. + +Although the callback might get passed parameters, their value and +presence is undefined and you cannot rely on them. Portable AnyEvent +callbacks cannot use arguments passed to time watcher callbacks. The timer callback will be invoked at most once: if you want a repeating timer you have to create a new watcher (this is a limitation by both Tk @@ -230,6 +236,10 @@ I without any C prefix, C is the Perl callback to be invoked whenever a signal occurs. +Although the callback might get passed parameters, their value and +presence is undefined and you cannot rely on them. Portable AnyEvent +callbacks cannot use arguments passed to signal watcher callbacks. + Multiple signal occurances can be clumped together into one callback invocation, and callback invocation will be synchronous. synchronous means that it might take a while until the signal gets handled by the process, @@ -253,18 +263,41 @@ watches for any child process exit). The watcher will trigger as often as status change for the child are received. This works by installing a signal handler for C. The callback will be called with the pid -and exit status (as returned by waitpid). +and exit status (as returned by waitpid), so unlike other watcher types, +you I rely on child watcher callback arguments. + +There is a slight catch to child watchers, however: you usually start them +I the child process was created, and this means the process could +have exited already (and no SIGCHLD will be sent anymore). + +Not all event models handle this correctly (POE doesn't), but even for +event models that I handle this correctly, they usually need to be +loaded before the process exits (i.e. before you fork in the first place). -Example: wait for pid 1333 +This means you cannot create a child watcher as the very first thing in an +AnyEvent program, you I to create at least one watcher before you +C the child (alternatively, you can call C). + +Example: fork a process and wait for it + + my $done = AnyEvent->condvar; + + AnyEvent::detect; # force event module to be initialised + + my $pid = fork or exit 5; my $w = AnyEvent->child ( - pid => 1333, + pid => $pid, cb => sub { my ($pid, $status) = @_; warn "pid $pid exited with status $status"; + $done->broadcast; }, ); + # do something else, then wait for process exit + $done->wait; + =head2 CONDITION VARIABLES Condition variables can be created by calling the C<< AnyEvent->condvar >> @@ -908,15 +941,15 @@ name watchers bytes create invoke destroy comment EV/EV 400000 244 0.56 0.46 0.31 EV native interface - EV/Any 100000 610 3.52 0.91 0.75 EV + AnyEvent watchers - CoroEV/Any 100000 610 3.49 0.92 0.75 coroutines + Coro::Signal - Perl/Any 100000 513 4.91 0.92 1.15 pure perl implementation - Event/Event 16000 523 28.05 21.38 0.86 Event native interface - Event/Any 16000 943 34.43 20.48 1.39 Event + AnyEvent watchers - Glib/Any 16000 1357 96.99 12.55 55.51 quadratic behaviour - Tk/Any 2000 1855 27.01 66.61 14.03 SEGV with >> 2000 watchers - POE/Event 2000 6644 108.15 768.19 14.33 via POE::Loop::Event - POE/Select 2000 6343 94.69 807.65 562.69 via POE::Loop::Select + EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers + CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal + Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation + Event/Event 16000 516 31.88 31.30 0.85 Event native interface + Event/Any 16000 936 39.17 33.63 1.43 Event + AnyEvent watchers + Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour + Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers + POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event + POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select =head2 Discussion @@ -928,10 +961,9 @@ boost. C is the sole leader regarding speed and memory use, which are both -maximal/minimal, respectively. Even when going through AnyEvent, there are -only two event loops that use slightly less memory (the C module -natively and the pure perl backend), and no faster event models, not even -C natively. +maximal/minimal, respectively. Even when going through AnyEvent, it uses +far less memory than any other event loop and is still faster than Event +natively. The pure perl implementation is hit in a few sweet spots (both the zero timeout and the use of a single fd hit optimisations in the perl