ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.83 by root, Fri Apr 25 13:39:08 2008 UTC vs.
Revision 1.85 by root, Fri Apr 25 13:51:32 2008 UTC

… …
141=head2 I/O WATCHERS 141=head2 I/O WATCHERS
142 142
143You can create an I/O watcher by calling the C<< AnyEvent->io >> method 143You can create an I/O watcher by calling the C<< AnyEvent->io >> method
144with the following mandatory key-value pairs as arguments: 144with the following mandatory key-value pairs as arguments:
145 145
146C<fh> the Perl I<file handle> (I<not> file descriptor) to watch for 146C<fh> the Perl I<file handle> (I<not> file descriptor) to watch
147events. C<poll> must be a string that is either C<r> or C<w>, which 147for events. C<poll> must be a string that is either C<r> or C<w>,
148creates a watcher waiting for "r"eadable or "w"ritable events, 148which creates a watcher waiting for "r"eadable or "w"ritable events,
149respectively. C<cb> is the callback to invoke each time the file handle 149respectively. C<cb> is the callback to invoke each time the file handle
150becomes ready. 150becomes ready.
151 151
152Although the callback might get passed parameters, their value and
153presence is undefined and you cannot rely on them. Portable AnyEvent
154callbacks cannot use arguments passed to I/O watcher callbacks.
155
152The I/O watcher might use the underlying file descriptor or a copy of it. 156The I/O watcher might use the underlying file descriptor or a copy of it.
153It is not allowed to close a file handle as long as any watcher is active 157You must not close a file handle as long as any watcher is active on the
154on the underlying file descriptor. 158underlying file descriptor.
155 159
156Some event loops issue spurious readyness notifications, so you should 160Some event loops issue spurious readyness notifications, so you should
157always use non-blocking calls when reading/writing from/to your file 161always use non-blocking calls when reading/writing from/to your file
158handles. 162handles.
159 163
… …
170 174
171You can create a time watcher by calling the C<< AnyEvent->timer >> 175You can create a time watcher by calling the C<< AnyEvent->timer >>
172method with the following mandatory arguments: 176method with the following mandatory arguments:
173 177
174C<after> specifies after how many seconds (fractional values are 178C<after> specifies after how many seconds (fractional values are
175supported) should the timer activate. C<cb> the callback to invoke in that 179supported) the callback should be invoked. C<cb> is the callback to invoke
176case. 180in that case.
181
182Although the callback might get passed parameters, their value and
183presence is undefined and you cannot rely on them. Portable AnyEvent
184callbacks cannot use arguments passed to time watcher callbacks.
177 185
178The timer callback will be invoked at most once: if you want a repeating 186The timer callback will be invoked at most once: if you want a repeating
179timer you have to create a new watcher (this is a limitation by both Tk 187timer you have to create a new watcher (this is a limitation by both Tk
180and Glib). 188and Glib).
181 189
… …
226 234
227You can watch for signals using a signal watcher, C<signal> is the signal 235You can watch for signals using a signal watcher, C<signal> is the signal
228I<name> without any C<SIG> prefix, C<cb> is the Perl callback to 236I<name> without any C<SIG> prefix, C<cb> is the Perl callback to
229be invoked whenever a signal occurs. 237be invoked whenever a signal occurs.
230 238
239Although the callback might get passed parameters, their value and
240presence is undefined and you cannot rely on them. Portable AnyEvent
241callbacks cannot use arguments passed to signal watcher callbacks.
242
231Multiple signal occurances can be clumped together into one callback 243Multiple signal occurances can be clumped together into one callback
232invocation, and callback invocation will be synchronous. synchronous means 244invocation, and callback invocation will be synchronous. synchronous means
233that it might take a while until the signal gets handled by the process, 245that it might take a while until the signal gets handled by the process,
234but it is guarenteed not to interrupt any other callbacks. 246but it is guarenteed not to interrupt any other callbacks.
235 247
… …
249 261
250The child process is specified by the C<pid> argument (if set to C<0>, it 262The child process is specified by the C<pid> argument (if set to C<0>, it
251watches for any child process exit). The watcher will trigger as often 263watches for any child process exit). The watcher will trigger as often
252as status change for the child are received. This works by installing a 264as status change for the child are received. This works by installing a
253signal handler for C<SIGCHLD>. The callback will be called with the pid 265signal handler for C<SIGCHLD>. The callback will be called with the pid
254and exit status (as returned by waitpid). 266and exit status (as returned by waitpid), so unlike other watcher types,
267you I<can> rely on child watcher callback arguments.
255 268
256There is a slight catch to child watchers, however: you usually start them 269There is a slight catch to child watchers, however: you usually start them
257I<after> the child process was created, and this means the process could 270I<after> the child process was created, and this means the process could
258have exited already (and no SIGCHLD will be sent anymore). 271have exited already (and no SIGCHLD will be sent anymore).
259 272
… …
946file descriptors grows high. In this benchmark, all events become ready at 959file descriptors grows high. In this benchmark, all events become ready at
947the same time, so select/poll-based implementations get an unnatural speed 960the same time, so select/poll-based implementations get an unnatural speed
948boost. 961boost.
949 962
950C<EV> is the sole leader regarding speed and memory use, which are both 963C<EV> is the sole leader regarding speed and memory use, which are both
951maximal/minimal, respectively. Even when going through AnyEvent, there are 964maximal/minimal, respectively. Even when going through AnyEvent, it uses
952only two event loops that use slightly less memory (the C<Event> module 965far less memory than any other event loop and is still faster than Event
953natively and the pure perl backend), and no faster event models, not even 966natively.
954C<Event> natively.
955 967
956The pure perl implementation is hit in a few sweet spots (both the 968The pure perl implementation is hit in a few sweet spots (both the
957zero timeout and the use of a single fd hit optimisations in the perl 969zero timeout and the use of a single fd hit optimisations in the perl
958interpreter and the backend itself, and all watchers become ready at the 970interpreter and the backend itself, and all watchers become ready at the
959same time). Nevertheless this shows that it adds very little overhead in 971same time). Nevertheless this shows that it adds very little overhead in

Diff Legend

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