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

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.87 by root, Thu Aug 21 20:52:39 2008 UTC vs.
Revision 1.88 by root, Thu Aug 21 23:48:35 2008 UTC

… …
14 14
15AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent 15AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent
16 16
17=cut 17=cut
18 18
19our $VERSION = 4.232; 19our $VERSION = 4.233;
20 20
21=head1 SYNOPSIS 21=head1 SYNOPSIS
22 22
23 use AnyEvent; 23 use AnyEvent;
24 use AnyEvent::Handle; 24 use AnyEvent::Handle;
… …
103occured, such as not being able to resolve the hostname, failure to 103occured, such as not being able to resolve the hostname, failure to
104connect or a read error. 104connect or a read error.
105 105
106Some errors are fatal (which is indicated by C<$fatal> being true). On 106Some errors are fatal (which is indicated by C<$fatal> being true). On
107fatal errors the handle object will be shut down and will not be usable 107fatal errors the handle object will be shut down and will not be usable
108(but you are free to look at the current C< ->rbuf >). Examples of fatal 108(but you are free to look at the current C<< ->rbuf >>). Examples of fatal
109errors are an EOF condition with active (but unsatisifable) read watchers 109errors are an EOF condition with active (but unsatisifable) read watchers
110(C<EPIPE>) or I/O errors. 110(C<EPIPE>) or I/O errors.
111 111
112Non-fatal errors can be retried by simply returning, but it is recommended 112Non-fatal errors can be retried by simply returning, but it is recommended
113to simply ignore this parameter and instead abondon the handle object 113to simply ignore this parameter and instead abondon the handle object
… …
152=item timeout => $fractional_seconds 152=item timeout => $fractional_seconds
153 153
154If non-zero, then this enables an "inactivity" timeout: whenever this many 154If non-zero, then this enables an "inactivity" timeout: whenever this many
155seconds pass without a successful read or write on the underlying file 155seconds pass without a successful read or write on the underlying file
156handle, the C<on_timeout> callback will be invoked (and if that one is 156handle, the C<on_timeout> callback will be invoked (and if that one is
157missing, an C<ETIMEDOUT> error will be raised). 157missing, a non-fatal C<ETIMEDOUT> error will be raised).
158 158
159Note that timeout processing is also active when you currently do not have 159Note that timeout processing is also active when you currently do not have
160any outstanding read or write requests: If you plan to keep the connection 160any outstanding read or write requests: If you plan to keep the connection
161idle then you should disable the timout temporarily or ignore the timeout 161idle then you should disable the timout temporarily or ignore the timeout
162in the C<on_timeout> callback. 162in the C<on_timeout> callback, in which case AnyEvent::Handle will simply
163restart the timeout.
163 164
164Zero (the default) disables this timeout. 165Zero (the default) disables this timeout.
165 166
166=item on_timeout => $cb->($handle) 167=item on_timeout => $cb->($handle)
167 168
… …
171 172
172=item rbuf_max => <bytes> 173=item rbuf_max => <bytes>
173 174
174If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>) 175If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>)
175when the read buffer ever (strictly) exceeds this size. This is useful to 176when the read buffer ever (strictly) exceeds this size. This is useful to
176avoid denial-of-service attacks. 177avoid some forms of denial-of-service attacks.
177 178
178For example, a server accepting connections from untrusted sources should 179For example, a server accepting connections from untrusted sources should
179be configured to accept only so-and-so much data that it cannot act on 180be configured to accept only so-and-so much data that it cannot act on
180(for example, when expecting a line, an attacker could send an unlimited 181(for example, when expecting a line, an attacker could send an unlimited
181amount of data without a callback ever being called as long as the line 182amount of data without a callback ever being called as long as the line
182isn't finished). 183isn't finished).
183 184
184=item autocork => <boolean> 185=item autocork => <boolean>
185 186
186When disabled (the default), then C<push_write> will try to immediately 187When disabled (the default), then C<push_write> will try to immediately
187write the data to the handle if possible. This avoids having to register 188write the data to the handle, if possible. This avoids having to register
188a write watcher and wait for the next event loop iteration, but can be 189a write watcher and wait for the next event loop iteration, but can
189inefficient if you write multiple small chunks (this disadvantage is 190be inefficient if you write multiple small chunks (on the wire, this
190usually avoided by your kernel's nagle algorithm, see C<low_delay>). 191disadvantage is usually avoided by your kernel's nagle algorithm, see
192C<no_delay>, but this option can save costly syscalls).
191 193
192When enabled, then writes will always be queued till the next event loop 194When enabled, then writes will always be queued till the next event loop
193iteration. This is efficient when you do many small writes per iteration, 195iteration. This is efficient when you do many small writes per iteration,
194but less efficient when you do a single write only. 196but less efficient when you do a single write only per iteration (or when
197the write buffer often is full). It also increases write latency.
195 198
196=item no_delay => <boolean> 199=item no_delay => <boolean>
197 200
198When doing small writes on sockets, your operating system kernel might 201When doing small writes on sockets, your operating system kernel might
199wait a bit for more data before actually sending it out. This is called 202wait a bit for more data before actually sending it out. This is called
200the Nagle algorithm, and usually it is beneficial. 203the Nagle algorithm, and usually it is beneficial.
201 204
202In some situations you want as low a delay as possible, which cna be 205In some situations you want as low a delay as possible, which can be
203accomplishd by setting this option to true. 206accomplishd by setting this option to a true value.
204 207
205The default is your opertaing system's default behaviour, this option 208The default is your opertaing system's default behaviour (most likely
206explicitly enables or disables it, if possible. 209enabled), this option explicitly enables or disables it, if possible.
207 210
208=item read_size => <bytes> 211=item read_size => <bytes>
209 212
210The default read block size (the amount of bytes this module will try to read 213The default read block size (the amount of bytes this module will
211during each (loop iteration). Default: C<8192>. 214try to read during each loop iteration, which affects memory
215requirements). Default: C<8192>.
212 216
213=item low_water_mark => <bytes> 217=item low_water_mark => <bytes>
214 218
215Sets the amount of bytes (default: C<0>) that make up an "empty" write 219Sets the amount of bytes (default: C<0>) that make up an "empty" write
216buffer: If the write reaches this size or gets even samller it is 220buffer: If the write reaches this size or gets even samller it is
217considered empty. 221considered empty.
218 222
223Sometimes it can be beneficial (for performance reasons) to add data to
224the write buffer before it is fully drained, but this is a rare case, as
225the operating system kernel usually buffers data as well, so the default
226is good in almost all cases.
227
219=item linger => <seconds> 228=item linger => <seconds>
220 229
221If non-zero (default: C<3600>), then the destructor of the 230If non-zero (default: C<3600>), then the destructor of the
222AnyEvent::Handle object will check wether there is still outstanding write 231AnyEvent::Handle object will check whether there is still outstanding
223data and will install a watcher that will write out this data. No errors 232write data and will install a watcher that will write this data to the
224will be reported (this mostly matches how the operating system treats 233socket. No errors will be reported (this mostly matches how the operating
225outstanding data at socket close time). 234system treats outstanding data at socket close time).
226 235
227This will not work for partial TLS data that could not yet been 236This will not work for partial TLS data that could not be encoded
228encoded. This data will be lost. 237yet. This data will be lost.
229 238
230=item tls => "accept" | "connect" | Net::SSLeay::SSL object 239=item tls => "accept" | "connect" | Net::SSLeay::SSL object
231 240
232When this parameter is given, it enables TLS (SSL) mode, that means 241When this parameter is given, it enables TLS (SSL) mode, that means
233AnyEvent will start a TLS handshake and will transparently encrypt/decrypt 242AnyEvent will start a TLS handshake as soon as the conenction has been
234data. 243established and will transparently encrypt/decrypt data afterwards.
235 244
236TLS mode requires Net::SSLeay to be installed (it will be loaded 245TLS mode requires Net::SSLeay to be installed (it will be loaded
237automatically when you try to create a TLS handle). 246automatically when you try to create a TLS handle): this module doesn't
247have a dependency on that module, so if your module requires it, you have
248to add the dependency yourself.
238 249
239Unlike TCP, TLS has a server and client side: for the TLS server side, use 250Unlike TCP, TLS has a server and client side: for the TLS server side, use
240C<accept>, and for the TLS client side of a connection, use C<connect> 251C<accept>, and for the TLS client side of a connection, use C<connect>
241mode. 252mode.
242 253
243You can also provide your own TLS connection object, but you have 254You can also provide your own TLS connection object, but you have
244to make sure that you call either C<Net::SSLeay::set_connect_state> 255to make sure that you call either C<Net::SSLeay::set_connect_state>
245or C<Net::SSLeay::set_accept_state> on it before you pass it to 256or C<Net::SSLeay::set_accept_state> on it before you pass it to
246AnyEvent::Handle. 257AnyEvent::Handle.
247 258
248See the C<starttls> method for when need to start TLS negotiation later. 259See the C<< ->starttls >> method for when need to start TLS negotiation later.
249 260
250=item tls_ctx => $ssl_ctx 261=item tls_ctx => $ssl_ctx
251 262
252Use the given Net::SSLeay::CTX object to create the new TLS connection 263Use the given C<Net::SSLeay::CTX> object to create the new TLS connection
253(unless a connection object was specified directly). If this parameter is 264(unless a connection object was specified directly). If this parameter is
254missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>. 265missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>.
255 266
256=item json => JSON or JSON::XS object 267=item json => JSON or JSON::XS object
257 268
… …
330 } 341 }
331} 342}
332 343
333=item $fh = $handle->fh 344=item $fh = $handle->fh
334 345
335This method returns the file handle of the L<AnyEvent::Handle> object. 346This method returns the file handle used to create the L<AnyEvent::Handle> object.
336 347
337=cut 348=cut
338 349
339sub fh { $_[0]{fh} } 350sub fh { $_[0]{fh} }
340 351
… …
358 $_[0]{on_eof} = $_[1]; 369 $_[0]{on_eof} = $_[1];
359} 370}
360 371
361=item $handle->on_timeout ($cb) 372=item $handle->on_timeout ($cb)
362 373
363Replace the current C<on_timeout> callback, or disables the callback 374Replace the current C<on_timeout> callback, or disables the callback (but
364(but not the timeout) if C<$cb> = C<undef>. See C<timeout> constructor 375not the timeout) if C<$cb> = C<undef>. See the C<timeout> constructor
365argument. 376argument and method.
366 377
367=cut 378=cut
368 379
369sub on_timeout { 380sub on_timeout {
370 $_[0]{on_timeout} = $_[1]; 381 $_[0]{on_timeout} = $_[1];

Diff Legend

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