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.84 by root, Fri Apr 25 13:48:42 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
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.
151 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.
153You must not close a file handle as long as any watcher is active on the 157You must not close a file handle as long as any watcher is active on the
154underlying 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
160Although the callback might get passed parameters, their value and
161presence is undefined and you cannot rely on them. Portable AnyEvent
162callbacks cannot use arguments passed to I/O watcher callbacks.
163 163
164Example: 164Example:
165 165
166 # wait for readability of STDIN, then read a line and disable the watcher 166 # wait for readability of STDIN, then read a line and disable the watcher
167 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 167 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
… …
174 174
175You can create a time watcher by calling the C<< AnyEvent->timer >> 175You can create a time watcher by calling the C<< AnyEvent->timer >>
176method with the following mandatory arguments: 176method with the following mandatory arguments:
177 177
178C<after> specifies after how many seconds (fractional values are 178C<after> specifies after how many seconds (fractional values are
179supported) 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
180case. 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.
181 185
182The 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
183timer 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
184and Glib). 188and Glib).
185
186Although the callback might get passed parameters, their value and
187presence is undefined and you cannot rely on them. Portable AnyEvent
188callbacks cannot use arguments passed to time watcher callbacks.
189 189
190Example: 190Example:
191 191
192 # fire an event after 7.7 seconds 192 # fire an event after 7.7 seconds
193 my $w = AnyEvent->timer (after => 7.7, cb => sub { 193 my $w = AnyEvent->timer (after => 7.7, cb => sub {
… …
234 234
235You 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
236I<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
237be invoked whenever a signal occurs. 237be invoked whenever a signal occurs.
238 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
239Multiple signal occurances can be clumped together into one callback 243Multiple signal occurances can be clumped together into one callback
240invocation, and callback invocation will be synchronous. synchronous means 244invocation, and callback invocation will be synchronous. synchronous means
241that 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,
242but it is guarenteed not to interrupt any other callbacks. 246but it is guarenteed not to interrupt any other callbacks.
243 247
… …
257 261
258The 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
259watches for any child process exit). The watcher will trigger as often 263watches for any child process exit). The watcher will trigger as often
260as 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
261signal 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
262and 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.
263 268
264There 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
265I<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
266have exited already (and no SIGCHLD will be sent anymore). 271have exited already (and no SIGCHLD will be sent anymore).
267 272

Diff Legend

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