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.197 by root, Tue Aug 31 00:59:55 2010 UTC vs.
Revision 1.236 by root, Sat May 12 23:14:29 2012 UTC

… …
11 11
12 my $hdl; $hdl = new AnyEvent::Handle 12 my $hdl; $hdl = new AnyEvent::Handle
13 fh => \*STDIN, 13 fh => \*STDIN,
14 on_error => sub { 14 on_error => sub {
15 my ($hdl, $fatal, $msg) = @_; 15 my ($hdl, $fatal, $msg) = @_;
16 warn "got error $msg\n"; 16 AE::log error => $msg;
17 $hdl->destroy; 17 $hdl->destroy;
18 $cv->send; 18 $cv->send;
19 }; 19 };
20 20
21 # send some request line 21 # send some request line
22 $hdl->push_write ("getinfo\015\012"); 22 $hdl->push_write ("getinfo\015\012");
23 23
24 # read the response line 24 # read the response line
25 $hdl->push_read (line => sub { 25 $hdl->push_read (line => sub {
26 my ($hdl, $line) = @_; 26 my ($hdl, $line) = @_;
27 warn "got line <$line>\n"; 27 say "got line <$line>";
28 $cv->send; 28 $cv->send;
29 }); 29 });
30 30
31 $cv->recv; 31 $cv->recv;
32 32
33=head1 DESCRIPTION 33=head1 DESCRIPTION
34 34
35This module is a helper module to make it easier to do event-based I/O on 35This is a helper module to make it easier to do event-based I/O on
36stream-based filehandles (sockets, pipes or other stream things). 36stream-based filehandles (sockets, pipes, and other stream things).
37 37
38The L<AnyEvent::Intro> tutorial contains some well-documented 38The L<AnyEvent::Intro> tutorial contains some well-documented
39AnyEvent::Handle examples. 39AnyEvent::Handle examples.
40 40
41In the following, when the documentation refers to of "bytes" then this 41In the following, where the documentation refers to "bytes", it means
42means characters. As sysread and syswrite are used for all I/O, their 42characters. As sysread and syswrite are used for all I/O, their
43treatment of characters applies to this module as well. 43treatment of characters applies to this module as well.
44 44
45At the very minimum, you should specify C<fh> or C<connect>, and the 45At the very minimum, you should specify C<fh> or C<connect>, and the
46C<on_error> callback. 46C<on_error> callback.
47 47
… …
75 } 75 }
76 76
77 \&$func 77 \&$func
78} 78}
79 79
80sub MAX_READ_SIZE() { 131072 }
81
80=head1 METHODS 82=head1 METHODS
81 83
82=over 4 84=over 4
83 85
84=item $handle = B<new> AnyEvent::Handle fh => $filehandle, key => value... 86=item $handle = B<new> AnyEvent::Handle fh => $filehandle, key => value...
… …
112=over 4 114=over 4
113 115
114=item on_prepare => $cb->($handle) 116=item on_prepare => $cb->($handle)
115 117
116This (rarely used) callback is called before a new connection is 118This (rarely used) callback is called before a new connection is
117attempted, but after the file handle has been created. It could be used to 119attempted, but after the file handle has been created (you can access that
120file handle via C<< $handle->{fh} >>). It could be used to prepare the
118prepare the file handle with parameters required for the actual connect 121file handle with parameters required for the actual connect (as opposed to
119(as opposed to settings that can be changed when the connection is already 122settings that can be changed when the connection is already established).
120established).
121 123
122The return value of this callback should be the connect timeout value in 124The return value of this callback should be the connect timeout value in
123seconds (or C<0>, or C<undef>, or the empty list, to indicate the default 125seconds (or C<0>, or C<undef>, or the empty list, to indicate that the
124timeout is to be used). 126default timeout is to be used).
125 127
126=item on_connect => $cb->($handle, $host, $port, $retry->()) 128=item on_connect => $cb->($handle, $host, $port, $retry->())
127 129
128This callback is called when a connection has been successfully established. 130This callback is called when a connection has been successfully established.
129 131
130The actual numeric host and port (the socket peername) are passed as 132The peer's numeric host and port (the socket peername) are passed as
131parameters, together with a retry callback. 133parameters, together with a retry callback. At the time it is called the
134read and write queues, EOF status, TLS status and similar properties of
135the handle will have been reset.
132 136
137It is not allowed to use the read or write queues while the handle object
138is connecting.
139
133When, for some reason, the handle is not acceptable, then calling 140If, for some reason, the handle is not acceptable, calling C<$retry> will
134C<$retry> will continue with the next connection target (in case of 141continue with the next connection target (in case of multi-homed hosts or
135multi-homed hosts or SRV records there can be multiple connection 142SRV records there can be multiple connection endpoints). The C<$retry>
136endpoints). At the time it is called the read and write queues, eof 143callback can be invoked after the connect callback returns, i.e. one can
137status, tls status and similar properties of the handle will have been 144start a handshake and then decide to retry with the next host if the
138reset. 145handshake fails.
139 146
140In most cases, ignoring the C<$retry> parameter is the way to go. 147In most cases, you should ignore the C<$retry> parameter.
141 148
142=item on_connect_error => $cb->($handle, $message) 149=item on_connect_error => $cb->($handle, $message)
143 150
144This callback is called when the connection could not be 151This callback is called when the connection could not be
145established. C<$!> will contain the relevant error code, and C<$message> a 152established. C<$!> will contain the relevant error code, and C<$message> a
… …
152 159
153=item on_error => $cb->($handle, $fatal, $message) 160=item on_error => $cb->($handle, $fatal, $message)
154 161
155This is the error callback, which is called when, well, some error 162This is the error callback, which is called when, well, some error
156occured, such as not being able to resolve the hostname, failure to 163occured, such as not being able to resolve the hostname, failure to
157connect or a read error. 164connect, or a read error.
158 165
159Some errors are fatal (which is indicated by C<$fatal> being true). On 166Some errors are fatal (which is indicated by C<$fatal> being true). On
160fatal errors the handle object will be destroyed (by a call to C<< -> 167fatal errors the handle object will be destroyed (by a call to C<< ->
161destroy >>) after invoking the error callback (which means you are free to 168destroy >>) after invoking the error callback (which means you are free to
162examine the handle object). Examples of fatal errors are an EOF condition 169examine the handle object). Examples of fatal errors are an EOF condition
163with active (but unsatisifable) read watchers (C<EPIPE>) or I/O errors. In 170with active (but unsatisfiable) read watchers (C<EPIPE>) or I/O errors. In
164cases where the other side can close the connection at their will it is 171cases where the other side can close the connection at will, it is
165often easiest to not report C<EPIPE> errors in this callback. 172often easiest to not report C<EPIPE> errors in this callback.
166 173
167AnyEvent::Handle tries to find an appropriate error code for you to check 174AnyEvent::Handle tries to find an appropriate error code for you to check
168against, but in some cases (TLS errors), this does not work well. It is 175against, but in some cases (TLS errors), this does not work well.
169recommended to always output the C<$message> argument in human-readable
170error messages (it's usually the same as C<"$!">).
171 176
177If you report the error to the user, it is recommended to always output
178the C<$message> argument in human-readable error messages (you don't need
179to report C<"$!"> if you report C<$message>).
180
181If you want to react programmatically to the error, then looking at C<$!>
182and comparing it against some of the documented C<Errno> values is usually
183better than looking at the C<$message>.
184
172Non-fatal errors can be retried by simply returning, but it is recommended 185Non-fatal errors can be retried by returning, but it is recommended
173to simply ignore this parameter and instead abondon the handle object 186to simply ignore this parameter and instead abondon the handle object
174when this callback is invoked. Examples of non-fatal errors are timeouts 187when this callback is invoked. Examples of non-fatal errors are timeouts
175C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>). 188C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>).
176 189
177On callback entrance, the value of C<$!> contains the operating system 190On entry to the callback, the value of C<$!> contains the operating
178error code (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT>, C<EBADMSG> or 191system error code (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT>, C<EBADMSG> or
179C<EPROTO>). 192C<EPROTO>).
180 193
181While not mandatory, it is I<highly> recommended to set this callback, as 194While not mandatory, it is I<highly> recommended to set this callback, as
182you will not be notified of errors otherwise. The default simply calls 195you will not be notified of errors otherwise. The default just calls
183C<croak>. 196C<croak>.
184 197
185=item on_read => $cb->($handle) 198=item on_read => $cb->($handle)
186 199
187This sets the default read callback, which is called when data arrives 200This sets the default read callback, which is called when data arrives
… …
195the beginning from it. 208the beginning from it.
196 209
197You can also call C<< ->push_read (...) >> or any other function that 210You can also call C<< ->push_read (...) >> or any other function that
198modifies the read queue. Or do both. Or ... 211modifies the read queue. Or do both. Or ...
199 212
200When an EOF condition is detected then AnyEvent::Handle will first try to 213When an EOF condition is detected, AnyEvent::Handle will first try to
201feed all the remaining data to the queued callbacks and C<on_read> before 214feed all the remaining data to the queued callbacks and C<on_read> before
202calling the C<on_eof> callback. If no progress can be made, then a fatal 215calling the C<on_eof> callback. If no progress can be made, then a fatal
203error will be raised (with C<$!> set to C<EPIPE>). 216error will be raised (with C<$!> set to C<EPIPE>).
204 217
205Note that, unlike requests in the read queue, an C<on_read> callback 218Note that, unlike requests in the read queue, an C<on_read> callback
… …
223If an EOF condition has been detected but no C<on_eof> callback has been 236If an EOF condition has been detected but no C<on_eof> callback has been
224set, then a fatal error will be raised with C<$!> set to <0>. 237set, then a fatal error will be raised with C<$!> set to <0>.
225 238
226=item on_drain => $cb->($handle) 239=item on_drain => $cb->($handle)
227 240
228This sets the callback that is called when the write buffer becomes empty 241This sets the callback that is called once when the write buffer becomes
229(or when the callback is set and the buffer is empty already). 242empty (and immediately when the handle object is created).
230 243
231To append to the write buffer, use the C<< ->push_write >> method. 244To append to the write buffer, use the C<< ->push_write >> method.
232 245
233This callback is useful when you don't want to put all of your write data 246This callback is useful when you don't want to put all of your write data
234into the queue at once, for example, when you want to write the contents 247into the queue at once, for example, when you want to write the contents
… …
246many seconds pass without a successful read or write on the underlying 259many seconds pass without a successful read or write on the underlying
247file handle (or a call to C<timeout_reset>), the C<on_timeout> callback 260file handle (or a call to C<timeout_reset>), the C<on_timeout> callback
248will be invoked (and if that one is missing, a non-fatal C<ETIMEDOUT> 261will be invoked (and if that one is missing, a non-fatal C<ETIMEDOUT>
249error will be raised). 262error will be raised).
250 263
251There are three variants of the timeouts that work fully independent 264There are three variants of the timeouts that work independently of each
252of each other, for both read and write, just read, and just write: 265other, for both read and write (triggered when nothing was read I<OR>
266written), just read (triggered when nothing was read), and just write:
253C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks 267C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks
254C<on_timeout>, C<on_rtimeout> and C<on_wtimeout>, and reset functions 268C<on_timeout>, C<on_rtimeout> and C<on_wtimeout>, and reset functions
255C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>. 269C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>.
256 270
257Note that timeout processing is also active when you currently do not have 271Note that timeout processing is active even when you do not have any
258any outstanding read or write requests: If you plan to keep the connection 272outstanding read or write requests: If you plan to keep the connection
259idle then you should disable the timout temporarily or ignore the timeout 273idle then you should disable the timeout temporarily or ignore the
260in the C<on_timeout> callback, in which case AnyEvent::Handle will simply 274timeout in the corresponding C<on_timeout> callback, in which case
261restart the timeout. 275AnyEvent::Handle will simply restart the timeout.
262 276
263Zero (the default) disables this timeout. 277Zero (the default) disables the corresponding timeout.
264 278
265=item on_timeout => $cb->($handle) 279=item on_timeout => $cb->($handle)
280
281=item on_rtimeout => $cb->($handle)
282
283=item on_wtimeout => $cb->($handle)
266 284
267Called whenever the inactivity timeout passes. If you return from this 285Called whenever the inactivity timeout passes. If you return from this
268callback, then the timeout will be reset as if some activity had happened, 286callback, then the timeout will be reset as if some activity had happened,
269so this condition is not fatal in any way. 287so this condition is not fatal in any way.
270 288
… …
278be configured to accept only so-and-so much data that it cannot act on 296be configured to accept only so-and-so much data that it cannot act on
279(for example, when expecting a line, an attacker could send an unlimited 297(for example, when expecting a line, an attacker could send an unlimited
280amount of data without a callback ever being called as long as the line 298amount of data without a callback ever being called as long as the line
281isn't finished). 299isn't finished).
282 300
301=item wbuf_max => <bytes>
302
303If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>)
304when the write buffer ever (strictly) exceeds this size. This is useful to
305avoid some forms of denial-of-service attacks.
306
307Although the units of this parameter is bytes, this is the I<raw> number
308of bytes not yet accepted by the kernel. This can make a difference when
309you e.g. use TLS, as TLS typically makes your write data larger (but it
310can also make it smaller due to compression).
311
312As an example of when this limit is useful, take a chat server that sends
313chat messages to a client. If the client does not read those in a timely
314manner then the send buffer in the server would grow unbounded.
315
283=item autocork => <boolean> 316=item autocork => <boolean>
284 317
285When disabled (the default), then C<push_write> will try to immediately 318When disabled (the default), C<push_write> will try to immediately
286write the data to the handle, if possible. This avoids having to register 319write the data to the handle if possible. This avoids having to register
287a write watcher and wait for the next event loop iteration, but can 320a write watcher and wait for the next event loop iteration, but can
288be inefficient if you write multiple small chunks (on the wire, this 321be inefficient if you write multiple small chunks (on the wire, this
289disadvantage is usually avoided by your kernel's nagle algorithm, see 322disadvantage is usually avoided by your kernel's nagle algorithm, see
290C<no_delay>, but this option can save costly syscalls). 323C<no_delay>, but this option can save costly syscalls).
291 324
292When enabled, then writes will always be queued till the next event loop 325When enabled, writes will always be queued till the next event loop
293iteration. This is efficient when you do many small writes per iteration, 326iteration. This is efficient when you do many small writes per iteration,
294but less efficient when you do a single write only per iteration (or when 327but less efficient when you do a single write only per iteration (or when
295the write buffer often is full). It also increases write latency. 328the write buffer often is full). It also increases write latency.
296 329
297=item no_delay => <boolean> 330=item no_delay => <boolean>
… …
301the Nagle algorithm, and usually it is beneficial. 334the Nagle algorithm, and usually it is beneficial.
302 335
303In some situations you want as low a delay as possible, which can be 336In some situations you want as low a delay as possible, which can be
304accomplishd by setting this option to a true value. 337accomplishd by setting this option to a true value.
305 338
306The default is your opertaing system's default behaviour (most likely 339The default is your operating system's default behaviour (most likely
307enabled), this option explicitly enables or disables it, if possible. 340enabled). This option explicitly enables or disables it, if possible.
308 341
309=item keepalive => <boolean> 342=item keepalive => <boolean>
310 343
311Enables (default disable) the SO_KEEPALIVE option on the stream socket: 344Enables (default disable) the SO_KEEPALIVE option on the stream socket:
312normally, TCP connections have no time-out once established, so TCP 345normally, TCP connections have no time-out once established, so TCP
313connections, once established, can stay alive forever even when the other 346connections, once established, can stay alive forever even when the other
314side has long gone. TCP keepalives are a cheap way to take down long-lived 347side has long gone. TCP keepalives are a cheap way to take down long-lived
315TCP connections whent he other side becomes unreachable. While the default 348TCP connections when the other side becomes unreachable. While the default
316is OS-dependent, TCP keepalives usually kick in after around two hours, 349is OS-dependent, TCP keepalives usually kick in after around two hours,
317and, if the other side doesn't reply, take down the TCP connection some 10 350and, if the other side doesn't reply, take down the TCP connection some 10
318to 15 minutes later. 351to 15 minutes later.
319 352
320It is harmless to specify this option for file handles that do not support 353It is harmless to specify this option for file handles that do not support
… …
338already have occured on BSD systems), but at least it will protect you 371already have occured on BSD systems), but at least it will protect you
339from most attacks. 372from most attacks.
340 373
341=item read_size => <bytes> 374=item read_size => <bytes>
342 375
343The default read block size (the amount of bytes this module will 376The initial read block size, the number of bytes this module will try
344try to read during each loop iteration, which affects memory 377to read during each loop iteration. Each handle object will consume
345requirements). Default: C<8192>. 378at least this amount of memory for the read buffer as well, so when
379handling many connections watch out for memory requirements). See also
380C<max_read_size>. Default: C<2048>.
381
382=item max_read_size => <bytes>
383
384The maximum read buffer size used by the dynamic adjustment
385algorithm: Each time AnyEvent::Handle can read C<read_size> bytes in
386one go it will double C<read_size> up to the maximum given by this
387option. Default: C<131072> or C<read_size>, whichever is higher.
346 388
347=item low_water_mark => <bytes> 389=item low_water_mark => <bytes>
348 390
349Sets the amount of bytes (default: C<0>) that make up an "empty" write 391Sets the number of bytes (default: C<0>) that make up an "empty" write
350buffer: If the write reaches this size or gets even samller it is 392buffer: If the buffer reaches this size or gets even samller it is
351considered empty. 393considered empty.
352 394
353Sometimes it can be beneficial (for performance reasons) to add data to 395Sometimes it can be beneficial (for performance reasons) to add data to
354the write buffer before it is fully drained, but this is a rare case, as 396the write buffer before it is fully drained, but this is a rare case, as
355the operating system kernel usually buffers data as well, so the default 397the operating system kernel usually buffers data as well, so the default
356is good in almost all cases. 398is good in almost all cases.
357 399
358=item linger => <seconds> 400=item linger => <seconds>
359 401
360If non-zero (default: C<3600>), then the destructor of the 402If this is non-zero (default: C<3600>), the destructor of the
361AnyEvent::Handle object will check whether there is still outstanding 403AnyEvent::Handle object will check whether there is still outstanding
362write data and will install a watcher that will write this data to the 404write data and will install a watcher that will write this data to the
363socket. No errors will be reported (this mostly matches how the operating 405socket. No errors will be reported (this mostly matches how the operating
364system treats outstanding data at socket close time). 406system treats outstanding data at socket close time).
365 407
… …
372A string used to identify the remote site - usually the DNS hostname 414A string used to identify the remote site - usually the DNS hostname
373(I<not> IDN!) used to create the connection, rarely the IP address. 415(I<not> IDN!) used to create the connection, rarely the IP address.
374 416
375Apart from being useful in error messages, this string is also used in TLS 417Apart from being useful in error messages, this string is also used in TLS
376peername verification (see C<verify_peername> in L<AnyEvent::TLS>). This 418peername verification (see C<verify_peername> in L<AnyEvent::TLS>). This
377verification will be skipped when C<peername> is not specified or 419verification will be skipped when C<peername> is not specified or is
378C<undef>. 420C<undef>.
379 421
380=item tls => "accept" | "connect" | Net::SSLeay::SSL object 422=item tls => "accept" | "connect" | Net::SSLeay::SSL object
381 423
382When this parameter is given, it enables TLS (SSL) mode, that means 424When this parameter is given, it enables TLS (SSL) mode, that means
… …
387appropriate error message. 429appropriate error message.
388 430
389TLS mode requires Net::SSLeay to be installed (it will be loaded 431TLS mode requires Net::SSLeay to be installed (it will be loaded
390automatically when you try to create a TLS handle): this module doesn't 432automatically when you try to create a TLS handle): this module doesn't
391have a dependency on that module, so if your module requires it, you have 433have a dependency on that module, so if your module requires it, you have
392to add the dependency yourself. 434to add the dependency yourself. If Net::SSLeay cannot be loaded or is too
435old, you get an C<EPROTO> error.
393 436
394Unlike TCP, TLS has a server and client side: for the TLS server side, use 437Unlike TCP, TLS has a server and client side: for the TLS server side, use
395C<accept>, and for the TLS client side of a connection, use C<connect> 438C<accept>, and for the TLS client side of a connection, use C<connect>
396mode. 439mode.
397 440
… …
408B<IMPORTANT:> since Net::SSLeay "objects" are really only integers, 451B<IMPORTANT:> since Net::SSLeay "objects" are really only integers,
409passing in the wrong integer will lead to certain crash. This most often 452passing in the wrong integer will lead to certain crash. This most often
410happens when one uses a stylish C<< tls => 1 >> and is surprised about the 453happens when one uses a stylish C<< tls => 1 >> and is surprised about the
411segmentation fault. 454segmentation fault.
412 455
413See the C<< ->starttls >> method for when need to start TLS negotiation later. 456Use the C<< ->starttls >> method if you need to start TLS negotiation later.
414 457
415=item tls_ctx => $anyevent_tls 458=item tls_ctx => $anyevent_tls
416 459
417Use the given C<AnyEvent::TLS> object to create the new TLS connection 460Use the given C<AnyEvent::TLS> object to create the new TLS connection
418(unless a connection object was specified directly). If this parameter is 461(unless a connection object was specified directly). If this
419missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>. 462parameter is missing (or C<undef>), then AnyEvent::Handle will use
463C<AnyEvent::Handle::TLS_CTX>.
420 464
421Instead of an object, you can also specify a hash reference with C<< key 465Instead of an object, you can also specify a hash reference with C<< key
422=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a 466=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a
423new TLS context object. 467new TLS context object.
424 468
… …
433 477
434TLS handshake failures will not cause C<on_error> to be invoked when this 478TLS handshake failures will not cause C<on_error> to be invoked when this
435callback is in effect, instead, the error message will be passed to C<on_starttls>. 479callback is in effect, instead, the error message will be passed to C<on_starttls>.
436 480
437Without this callback, handshake failures lead to C<on_error> being 481Without this callback, handshake failures lead to C<on_error> being
438called, as normal. 482called as usual.
439 483
440Note that you cannot call C<starttls> right again in this callback. If you 484Note that you cannot just call C<starttls> again in this callback. If you
441need to do that, start an zero-second timer instead whose callback can 485need to do that, start an zero-second timer instead whose callback can
442then call C<< ->starttls >> again. 486then call C<< ->starttls >> again.
443 487
444=item on_stoptls => $cb->($handle) 488=item on_stoptls => $cb->($handle)
445 489
… …
493 $self->{connect}[0], 537 $self->{connect}[0],
494 $self->{connect}[1], 538 $self->{connect}[1],
495 sub { 539 sub {
496 my ($fh, $host, $port, $retry) = @_; 540 my ($fh, $host, $port, $retry) = @_;
497 541
542 delete $self->{_connect}; # no longer needed
543
498 if ($fh) { 544 if ($fh) {
499 $self->{fh} = $fh; 545 $self->{fh} = $fh;
500 546
501 delete $self->{_skip_drain_rbuf}; 547 delete $self->{_skip_drain_rbuf};
502 $self->_start; 548 $self->_start;
… …
509 }); 555 });
510 556
511 } else { 557 } else {
512 if ($self->{on_connect_error}) { 558 if ($self->{on_connect_error}) {
513 $self->{on_connect_error}($self, "$!"); 559 $self->{on_connect_error}($self, "$!");
514 $self->destroy; 560 $self->destroy if $self;
515 } else { 561 } else {
516 $self->_error ($!, 1); 562 $self->_error ($!, 1);
517 } 563 }
518 } 564 }
519 }, 565 },
520 sub { 566 sub {
521 local $self->{fh} = $_[0]; 567 local $self->{fh} = $_[0];
522 568
523 $self->{on_prepare} 569 $self->{on_prepare}
524 ? $self->{on_prepare}->($self) 570 ? $self->{on_prepare}->($self)
525 : () 571 : ()
526 } 572 }
527 ); 573 );
528 } 574 }
529 575
… …
547 593
548 $self->{_activity} = 594 $self->{_activity} =
549 $self->{_ractivity} = 595 $self->{_ractivity} =
550 $self->{_wactivity} = AE::now; 596 $self->{_wactivity} = AE::now;
551 597
598 $self->{read_size} ||= 2048;
599 $self->{max_read_size} = $self->{read_size}
600 if $self->{read_size} > ($self->{max_read_size} || MAX_READ_SIZE);
601
552 $self->timeout (delete $self->{timeout} ) if $self->{timeout}; 602 $self->timeout (delete $self->{timeout} ) if $self->{timeout};
553 $self->rtimeout (delete $self->{rtimeout} ) if $self->{rtimeout}; 603 $self->rtimeout (delete $self->{rtimeout} ) if $self->{rtimeout};
554 $self->wtimeout (delete $self->{wtimeout} ) if $self->{wtimeout}; 604 $self->wtimeout (delete $self->{wtimeout} ) if $self->{wtimeout};
555 605
556 $self->no_delay (delete $self->{no_delay} ) if exists $self->{no_delay} && $self->{no_delay}; 606 $self->no_delay (delete $self->{no_delay} ) if exists $self->{no_delay} && $self->{no_delay};
… …
559 $self->oobinline (exists $self->{oobinline} ? delete $self->{oobinline} : 1); 609 $self->oobinline (exists $self->{oobinline} ? delete $self->{oobinline} : 1);
560 610
561 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx}) 611 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
562 if $self->{tls}; 612 if $self->{tls};
563 613
564 $self->on_drain (delete $self->{on_drain}) if $self->{on_drain}; 614 $self->on_drain (delete $self->{on_drain} ) if $self->{on_drain};
565 615
566 $self->start_read 616 $self->start_read
567 if $self->{on_read} || @{ $self->{_queue} }; 617 if $self->{on_read} || @{ $self->{_queue} };
568 618
569 $self->_drain_wbuf; 619 $self->_drain_wbuf;
… …
645=cut 695=cut
646 696
647sub no_delay { 697sub no_delay {
648 $_[0]{no_delay} = $_[1]; 698 $_[0]{no_delay} = $_[1];
649 699
650 eval {
651 local $SIG{__DIE__};
652 setsockopt $_[0]{fh}, Socket::IPPROTO_TCP (), Socket::TCP_NODELAY (), int $_[1] 700 setsockopt $_[0]{fh}, Socket::IPPROTO_TCP (), Socket::TCP_NODELAY (), int $_[1]
653 if $_[0]{fh}; 701 if $_[0]{fh};
654 };
655} 702}
656 703
657=item $handle->keepalive ($boolean) 704=item $handle->keepalive ($boolean)
658 705
659Enables or disables the C<keepalive> setting (see constructor argument of 706Enables or disables the C<keepalive> setting (see constructor argument of
… …
727 774
728=item $handle->rbuf_max ($max_octets) 775=item $handle->rbuf_max ($max_octets)
729 776
730Configures the C<rbuf_max> setting (C<undef> disables it). 777Configures the C<rbuf_max> setting (C<undef> disables it).
731 778
779=item $handle->wbuf_max ($max_octets)
780
781Configures the C<wbuf_max> setting (C<undef> disables it).
782
732=cut 783=cut
733 784
734sub rbuf_max { 785sub rbuf_max {
735 $_[0]{rbuf_max} = $_[1]; 786 $_[0]{rbuf_max} = $_[1];
736} 787}
737 788
789sub wbuf_max {
790 $_[0]{wbuf_max} = $_[1];
791}
792
738############################################################################# 793#############################################################################
739 794
740=item $handle->timeout ($seconds) 795=item $handle->timeout ($seconds)
741 796
742=item $handle->rtimeout ($seconds) 797=item $handle->rtimeout ($seconds)
743 798
744=item $handle->wtimeout ($seconds) 799=item $handle->wtimeout ($seconds)
745 800
746Configures (or disables) the inactivity timeout. 801Configures (or disables) the inactivity timeout.
802
803The timeout will be checked instantly, so this method might destroy the
804handle before it returns.
747 805
748=item $handle->timeout_reset 806=item $handle->timeout_reset
749 807
750=item $handle->rtimeout_reset 808=item $handle->rtimeout_reset
751 809
… …
768 $_[0]{$on_timeout} = $_[1]; 826 $_[0]{$on_timeout} = $_[1];
769 }; 827 };
770 828
771 *$timeout = sub { 829 *$timeout = sub {
772 my ($self, $new_value) = @_; 830 my ($self, $new_value) = @_;
831
832 $new_value >= 0
833 or Carp::croak "AnyEvent::Handle->$timeout called with negative timeout ($new_value), caught";
773 834
774 $self->{$timeout} = $new_value; 835 $self->{$timeout} = $new_value;
775 delete $self->{$tw}; &$cb; 836 delete $self->{$tw}; &$cb;
776 }; 837 };
777 838
… …
832 893
833The write queue is very simple: you can add data to its end, and 894The write queue is very simple: you can add data to its end, and
834AnyEvent::Handle will automatically try to get rid of it for you. 895AnyEvent::Handle will automatically try to get rid of it for you.
835 896
836When data could be written and the write buffer is shorter then the low 897When data could be written and the write buffer is shorter then the low
837water mark, the C<on_drain> callback will be invoked. 898water mark, the C<on_drain> callback will be invoked once.
838 899
839=over 4 900=over 4
840 901
841=item $handle->on_drain ($cb) 902=item $handle->on_drain ($cb)
842 903
… …
857 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf}); 918 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf});
858} 919}
859 920
860=item $handle->push_write ($data) 921=item $handle->push_write ($data)
861 922
862Queues the given scalar to be written. You can push as much data as you 923Queues the given scalar to be written. You can push as much data as
863want (only limited by the available memory), as C<AnyEvent::Handle> 924you want (only limited by the available memory and C<wbuf_max>), as
864buffers it independently of the kernel. 925C<AnyEvent::Handle> buffers it independently of the kernel.
865 926
866This method may invoke callbacks (and therefore the handle might be 927This method may invoke callbacks (and therefore the handle might be
867destroyed after it returns). 928destroyed after it returns).
868 929
869=cut 930=cut
… …
897 $cb->() unless $self->{autocork}; 958 $cb->() unless $self->{autocork};
898 959
899 # if still data left in wbuf, we need to poll 960 # if still data left in wbuf, we need to poll
900 $self->{_ww} = AE::io $self->{fh}, 1, $cb 961 $self->{_ww} = AE::io $self->{fh}, 1, $cb
901 if length $self->{wbuf}; 962 if length $self->{wbuf};
963
964 if (
965 defined $self->{wbuf_max}
966 && $self->{wbuf_max} < length $self->{wbuf}
967 ) {
968 $self->_error (Errno::ENOSPC, 1), return;
969 }
902 }; 970 };
903} 971}
904 972
905our %WH; 973our %WH;
906 974
… …
1026=cut 1094=cut
1027 1095
1028register_write_type storable => sub { 1096register_write_type storable => sub {
1029 my ($self, $ref) = @_; 1097 my ($self, $ref) = @_;
1030 1098
1031 require Storable; 1099 require Storable unless $Storable::VERSION;
1032 1100
1033 pack "w/a*", Storable::nfreeze ($ref) 1101 pack "w/a*", Storable::nfreeze ($ref)
1034}; 1102};
1035 1103
1036=back 1104=back
… …
1041before it was actually written. One way to do that is to replace your 1109before it was actually written. One way to do that is to replace your
1042C<on_drain> handler by a callback that shuts down the socket (and set 1110C<on_drain> handler by a callback that shuts down the socket (and set
1043C<low_water_mark> to C<0>). This method is a shorthand for just that, and 1111C<low_water_mark> to C<0>). This method is a shorthand for just that, and
1044replaces the C<on_drain> callback with: 1112replaces the C<on_drain> callback with:
1045 1113
1046 sub { shutdown $_[0]{fh}, 1 } # for push_shutdown 1114 sub { shutdown $_[0]{fh}, 1 }
1047 1115
1048This simply shuts down the write side and signals an EOF condition to the 1116This simply shuts down the write side and signals an EOF condition to the
1049the peer. 1117the peer.
1050 1118
1051You can rely on the normal read queue and C<on_eof> handling 1119You can rely on the normal read queue and C<on_eof> handling
… …
1073 1141
1074Whenever the given C<type> is used, C<push_write> will the function with 1142Whenever the given C<type> is used, C<push_write> will the function with
1075the handle object and the remaining arguments. 1143the handle object and the remaining arguments.
1076 1144
1077The function is supposed to return a single octet string that will be 1145The function is supposed to return a single octet string that will be
1078appended to the write buffer, so you cna mentally treat this function as a 1146appended to the write buffer, so you can mentally treat this function as a
1079"arguments to on-the-wire-format" converter. 1147"arguments to on-the-wire-format" converter.
1080 1148
1081Example: implement a custom write type C<join> that joins the remaining 1149Example: implement a custom write type C<join> that joins the remaining
1082arguments using the first one. 1150arguments using the first one.
1083 1151
… …
1117partial message has been received so far), or change the read queue with 1185partial message has been received so far), or change the read queue with
1118e.g. C<push_read>. 1186e.g. C<push_read>.
1119 1187
1120In the more complex case, you want to queue multiple callbacks. In this 1188In the more complex case, you want to queue multiple callbacks. In this
1121case, AnyEvent::Handle will call the first queued callback each time new 1189case, AnyEvent::Handle will call the first queued callback each time new
1122data arrives (also the first time it is queued) and removes it when it has 1190data arrives (also the first time it is queued) and remove it when it has
1123done its job (see C<push_read>, below). 1191done its job (see C<push_read>, below).
1124 1192
1125This way you can, for example, push three line-reads, followed by reading 1193This way you can, for example, push three line-reads, followed by reading
1126a chunk of data, and AnyEvent::Handle will execute them in order. 1194a chunk of data, and AnyEvent::Handle will execute them in order.
1127 1195
… …
1272 $self->_drain_rbuf if $cb; 1340 $self->_drain_rbuf if $cb;
1273} 1341}
1274 1342
1275=item $handle->rbuf 1343=item $handle->rbuf
1276 1344
1277Returns the read buffer (as a modifiable lvalue). 1345Returns the read buffer (as a modifiable lvalue). You can also access the
1346read buffer directly as the C<< ->{rbuf} >> member, if you want (this is
1347much faster, and no less clean).
1278 1348
1279You can access the read buffer directly as the C<< ->{rbuf} >> 1349The only operation allowed on the read buffer (apart from looking at it)
1280member, if you want. However, the only operation allowed on the 1350is removing data from its beginning. Otherwise modifying or appending to
1281read buffer (apart from looking at it) is removing data from its 1351it is not allowed and will lead to hard-to-track-down bugs.
1282beginning. Otherwise modifying or appending to it is not allowed and will
1283lead to hard-to-track-down bugs.
1284 1352
1285NOTE: The read buffer should only be used or modified if the C<on_read>, 1353NOTE: The read buffer should only be used or modified in the C<on_read>
1286C<push_read> or C<unshift_read> methods are used. The other read methods 1354callback or when C<push_read> or C<unshift_read> are used with a single
1287automatically manage the read buffer. 1355callback (i.e. untyped). Typed C<push_read> and C<unshift_read> methods
1356will manage the read buffer on their own.
1288 1357
1289=cut 1358=cut
1290 1359
1291sub rbuf : lvalue { 1360sub rbuf : lvalue {
1292 $_[0]{rbuf} 1361 $_[0]{rbuf}
… …
1343 my $cb = pop; 1412 my $cb = pop;
1344 1413
1345 if (@_) { 1414 if (@_) {
1346 my $type = shift; 1415 my $type = shift;
1347 1416
1417 $cb = ($RH{$type} ||= _load_func "$type\::anyevent_read_type"
1348 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::unshift_read") 1418 or Carp::croak "unsupported/unloadable type '$type' passed to AnyEvent::Handle::unshift_read")
1349 ->($self, $cb, @_); 1419 ->($self, $cb, @_);
1350 } 1420 }
1351 1421
1352 unshift @{ $self->{_queue} }, $cb; 1422 unshift @{ $self->{_queue} }, $cb;
1353 $self->_drain_rbuf; 1423 $self->_drain_rbuf;
… …
1375data. 1445data.
1376 1446
1377Example: read 2 bytes. 1447Example: read 2 bytes.
1378 1448
1379 $handle->push_read (chunk => 2, sub { 1449 $handle->push_read (chunk => 2, sub {
1380 warn "yay ", unpack "H*", $_[1]; 1450 say "yay " . unpack "H*", $_[1];
1381 }); 1451 });
1382 1452
1383=cut 1453=cut
1384 1454
1385register_read_type chunk => sub { 1455register_read_type chunk => sub {
… …
1419 if (@_ < 3) { 1489 if (@_ < 3) {
1420 # this is more than twice as fast as the generic code below 1490 # this is more than twice as fast as the generic code below
1421 sub { 1491 sub {
1422 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return; 1492 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return;
1423 1493
1424 $cb->($_[0], $1, $2); 1494 $cb->($_[0], "$1", "$2");
1425 1 1495 1
1426 } 1496 }
1427 } else { 1497 } else {
1428 $eol = quotemeta $eol unless ref $eol; 1498 $eol = quotemeta $eol unless ref $eol;
1429 $eol = qr|^(.*?)($eol)|s; 1499 $eol = qr|^(.*?)($eol)|s;
1430 1500
1431 sub { 1501 sub {
1432 $_[0]{rbuf} =~ s/$eol// or return; 1502 $_[0]{rbuf} =~ s/$eol// or return;
1433 1503
1434 $cb->($_[0], $1, $2); 1504 $cb->($_[0], "$1", "$2");
1435 1 1505 1
1436 } 1506 }
1437 } 1507 }
1438}; 1508};
1439 1509
… …
1461the receive buffer when neither C<$accept> nor C<$reject> match, 1531the receive buffer when neither C<$accept> nor C<$reject> match,
1462and everything preceding and including the match will be accepted 1532and everything preceding and including the match will be accepted
1463unconditionally. This is useful to skip large amounts of data that you 1533unconditionally. This is useful to skip large amounts of data that you
1464know cannot be matched, so that the C<$accept> or C<$reject> regex do not 1534know cannot be matched, so that the C<$accept> or C<$reject> regex do not
1465have to start matching from the beginning. This is purely an optimisation 1535have to start matching from the beginning. This is purely an optimisation
1466and is usually worth only when you expect more than a few kilobytes. 1536and is usually worth it only when you expect more than a few kilobytes.
1467 1537
1468Example: expect a http header, which ends at C<\015\012\015\012>. Since we 1538Example: expect a http header, which ends at C<\015\012\015\012>. Since we
1469expect the header to be very large (it isn't in practise, but...), we use 1539expect the header to be very large (it isn't in practice, but...), we use
1470a skip regex to skip initial portions. The skip regex is tricky in that 1540a skip regex to skip initial portions. The skip regex is tricky in that
1471it only accepts something not ending in either \015 or \012, as these are 1541it only accepts something not ending in either \015 or \012, as these are
1472required for the accept regex. 1542required for the accept regex.
1473 1543
1474 $handle->push_read (regex => 1544 $handle->push_read (regex =>
… …
1487 1557
1488 sub { 1558 sub {
1489 # accept 1559 # accept
1490 if ($$rbuf =~ $accept) { 1560 if ($$rbuf =~ $accept) {
1491 $data .= substr $$rbuf, 0, $+[0], ""; 1561 $data .= substr $$rbuf, 0, $+[0], "";
1492 $cb->($self, $data); 1562 $cb->($_[0], $data);
1493 return 1; 1563 return 1;
1494 } 1564 }
1495 1565
1496 # reject 1566 # reject
1497 if ($reject && $$rbuf =~ $reject) { 1567 if ($reject && $$rbuf =~ $reject) {
1498 $self->_error (Errno::EBADMSG); 1568 $_[0]->_error (Errno::EBADMSG);
1499 } 1569 }
1500 1570
1501 # skip 1571 # skip
1502 if ($skip && $$rbuf =~ $skip) { 1572 if ($skip && $$rbuf =~ $skip) {
1503 $data .= substr $$rbuf, 0, $+[0], ""; 1573 $data .= substr $$rbuf, 0, $+[0], "";
… …
1519 my ($self, $cb) = @_; 1589 my ($self, $cb) = @_;
1520 1590
1521 sub { 1591 sub {
1522 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) { 1592 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) {
1523 if ($_[0]{rbuf} =~ /[^0-9]/) { 1593 if ($_[0]{rbuf} =~ /[^0-9]/) {
1524 $self->_error (Errno::EBADMSG); 1594 $_[0]->_error (Errno::EBADMSG);
1525 } 1595 }
1526 return; 1596 return;
1527 } 1597 }
1528 1598
1529 my $len = $1; 1599 my $len = $1;
1530 1600
1531 $self->unshift_read (chunk => $len, sub { 1601 $_[0]->unshift_read (chunk => $len, sub {
1532 my $string = $_[1]; 1602 my $string = $_[1];
1533 $_[0]->unshift_read (chunk => 1, sub { 1603 $_[0]->unshift_read (chunk => 1, sub {
1534 if ($_[1] eq ",") { 1604 if ($_[1] eq ",") {
1535 $cb->($_[0], $string); 1605 $cb->($_[0], $string);
1536 } else { 1606 } else {
1537 $self->_error (Errno::EBADMSG); 1607 $_[0]->_error (Errno::EBADMSG);
1538 } 1608 }
1539 }); 1609 });
1540 }); 1610 });
1541 1611
1542 1 1612 1
… …
1615 1685
1616 my $data; 1686 my $data;
1617 my $rbuf = \$self->{rbuf}; 1687 my $rbuf = \$self->{rbuf};
1618 1688
1619 sub { 1689 sub {
1620 my $ref = eval { $json->incr_parse ($self->{rbuf}) }; 1690 my $ref = eval { $json->incr_parse ($_[0]{rbuf}) };
1621 1691
1622 if ($ref) { 1692 if ($ref) {
1623 $self->{rbuf} = $json->incr_text; 1693 $_[0]{rbuf} = $json->incr_text;
1624 $json->incr_text = ""; 1694 $json->incr_text = "";
1625 $cb->($self, $ref); 1695 $cb->($_[0], $ref);
1626 1696
1627 1 1697 1
1628 } elsif ($@) { 1698 } elsif ($@) {
1629 # error case 1699 # error case
1630 $json->incr_skip; 1700 $json->incr_skip;
1631 1701
1632 $self->{rbuf} = $json->incr_text; 1702 $_[0]{rbuf} = $json->incr_text;
1633 $json->incr_text = ""; 1703 $json->incr_text = "";
1634 1704
1635 $self->_error (Errno::EBADMSG); 1705 $_[0]->_error (Errno::EBADMSG);
1636 1706
1637 () 1707 ()
1638 } else { 1708 } else {
1639 $self->{rbuf} = ""; 1709 $_[0]{rbuf} = "";
1640 1710
1641 () 1711 ()
1642 } 1712 }
1643 } 1713 }
1644}; 1714};
… …
1654=cut 1724=cut
1655 1725
1656register_read_type storable => sub { 1726register_read_type storable => sub {
1657 my ($self, $cb) = @_; 1727 my ($self, $cb) = @_;
1658 1728
1659 require Storable; 1729 require Storable unless $Storable::VERSION;
1660 1730
1661 sub { 1731 sub {
1662 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method 1732 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
1663 defined (my $len = eval { unpack "w", $_[0]{rbuf} }) 1733 defined (my $len = eval { unpack "w", $_[0]{rbuf} })
1664 or return; 1734 or return;
… …
1667 1737
1668 # bypass unshift if we already have the remaining chunk 1738 # bypass unshift if we already have the remaining chunk
1669 if ($format + $len <= length $_[0]{rbuf}) { 1739 if ($format + $len <= length $_[0]{rbuf}) {
1670 my $data = substr $_[0]{rbuf}, $format, $len; 1740 my $data = substr $_[0]{rbuf}, $format, $len;
1671 substr $_[0]{rbuf}, 0, $format + $len, ""; 1741 substr $_[0]{rbuf}, 0, $format + $len, "";
1742
1672 $cb->($_[0], Storable::thaw ($data)); 1743 eval { $cb->($_[0], Storable::thaw ($data)); 1 }
1744 or return $_[0]->_error (Errno::EBADMSG);
1673 } else { 1745 } else {
1674 # remove prefix 1746 # remove prefix
1675 substr $_[0]{rbuf}, 0, $format, ""; 1747 substr $_[0]{rbuf}, 0, $format, "";
1676 1748
1677 # read remaining chunk 1749 # read remaining chunk
1678 $_[0]->unshift_read (chunk => $len, sub { 1750 $_[0]->unshift_read (chunk => $len, sub {
1679 if (my $ref = eval { Storable::thaw ($_[1]) }) { 1751 eval { $cb->($_[0], Storable::thaw ($_[1])); 1 }
1680 $cb->($_[0], $ref);
1681 } else {
1682 $self->_error (Errno::EBADMSG); 1752 or $_[0]->_error (Errno::EBADMSG);
1683 }
1684 }); 1753 });
1685 } 1754 }
1686 1755
1687 1 1756 1
1688 } 1757 }
1758};
1759
1760=item tls_detect => $cb->($handle, $detect, $major, $minor)
1761
1762Checks the input stream for a valid SSL or TLS handshake TLSPaintext
1763record without consuming anything. Only SSL version 3 or higher
1764is handled, up to the fictituous protocol 4.x (but both SSL3+ and
1765SSL2-compatible framing is supported).
1766
1767If it detects that the input data is likely TLS, it calls the callback
1768with a true value for C<$detect> and the (on-wire) TLS version as second
1769and third argument (C<$major> is C<3>, and C<$minor> is 0..3 for SSL
17703.0, TLS 1.0, 1.1 and 1.2, respectively). If it detects the input to
1771be definitely not TLS, it calls the callback with a false value for
1772C<$detect>.
1773
1774The callback could use this information to decide whether or not to start
1775TLS negotiation.
1776
1777In all cases the data read so far is passed to the following read
1778handlers.
1779
1780Usually you want to use the C<tls_autostart> read type instead.
1781
1782If you want to design a protocol that works in the presence of TLS
1783dtection, make sure that any non-TLS data doesn't start with the octet 22
1784(ASCII SYN, 16 hex) or 128-255 (i.e. highest bit set). The checks this
1785read type does are a bit more strict, but might losen in the future to
1786accomodate protocol changes.
1787
1788This read type does not rely on L<AnyEvent::TLS> (and thus, not on
1789L<Net::SSLeay>).
1790
1791=item tls_autostart => $tls[, $tls_ctx]
1792
1793Tries to detect a valid SSL or TLS handshake. If one is detected, it tries
1794to start tls by calling C<starttls> with the given arguments.
1795
1796In practise, C<$tls> must be C<accept>, or a Net::SSLeay context that has
1797been configured to accept, as servers do not normally send a handshake on
1798their own and ths cannot be detected in this way.
1799
1800See C<tls_detect> above for more details.
1801
1802Example: give the client a chance to start TLS before accepting a text
1803line.
1804
1805 $hdl->push_read (tls_detect => "accept");
1806 $hdl->push_read (line => sub {
1807 print "received ", ($_[0]{tls} ? "encrypted" : "cleartext"), " <$_[1]>\n";
1808 });
1809
1810=cut
1811
1812register_read_type tls_detect => sub {
1813 my ($self, $cb) = @_;
1814
1815 sub {
1816 # this regex matches a full or partial tls record
1817 if (
1818 # ssl3+: type(22=handshake) major(=3) minor(any) length_hi
1819 $self->{rbuf} =~ /^(?:\z| \x16 (\z| [\x03\x04] (?:\z| . (?:\z| [\x00-\x40] ))))/xs
1820 # ssl2 comapatible: len_hi len_lo type(1) major minor dummy(forlength)
1821 or $self->{rbuf} =~ /^(?:\z| [\x80-\xff] (?:\z| . (?:\z| \x01 (\z| [\x03\x04] (?:\z| . (?:\z| . ))))))/xs
1822 ) {
1823 return if 3 != length $1; # partial match, can't decide yet
1824
1825 # full match, valid TLS record
1826 my ($major, $minor) = unpack "CC", $1;
1827 $cb->($self, "accept", $major + $minor * 0.1);
1828 } else {
1829 # mismatch == guaranteed not TLS
1830 $cb->($self, undef);
1831 }
1832
1833 1
1834 }
1835};
1836
1837register_read_type tls_autostart => sub {
1838 my ($self, @tls) = @_;
1839
1840 $RH{tls_detect}($self, sub {
1841 return unless $_[1];
1842 $_[0]->starttls (@tls);
1843 })
1689}; 1844};
1690 1845
1691=back 1846=back
1692 1847
1693=item custom read types - Package::anyevent_read_type $handle, $cb, @args 1848=item custom read types - Package::anyevent_read_type $handle, $cb, @args
… …
1725Note that AnyEvent::Handle will automatically C<start_read> for you when 1880Note that AnyEvent::Handle will automatically C<start_read> for you when
1726you change the C<on_read> callback or push/unshift a read callback, and it 1881you change the C<on_read> callback or push/unshift a read callback, and it
1727will automatically C<stop_read> for you when neither C<on_read> is set nor 1882will automatically C<stop_read> for you when neither C<on_read> is set nor
1728there are any read requests in the queue. 1883there are any read requests in the queue.
1729 1884
1730These methods will have no effect when in TLS mode (as TLS doesn't support 1885In older versions of this module (<= 5.3), these methods had no effect,
1731half-duplex connections). 1886as TLS does not support half-duplex connections. In current versions they
1887work as expected, as this behaviour is required to avoid certain resource
1888attacks, where the program would be forced to read (and buffer) arbitrary
1889amounts of data before being able to send some data. The drawback is that
1890some readings of the the SSL/TLS specifications basically require this
1891attack to be working, as SSL/TLS implementations might stall sending data
1892during a rehandshake.
1893
1894As a guideline, during the initial handshake, you should not stop reading,
1895and as a client, it might cause problems, depending on your application.
1732 1896
1733=cut 1897=cut
1734 1898
1735sub stop_read { 1899sub stop_read {
1736 my ($self) = @_; 1900 my ($self) = @_;
1737 1901
1738 delete $self->{_rw} unless $self->{tls}; 1902 delete $self->{_rw};
1739} 1903}
1740 1904
1741sub start_read { 1905sub start_read {
1742 my ($self) = @_; 1906 my ($self) = @_;
1743 1907
1744 unless ($self->{_rw} || $self->{_eof} || !$self->{fh}) { 1908 unless ($self->{_rw} || $self->{_eof} || !$self->{fh}) {
1745 Scalar::Util::weaken $self; 1909 Scalar::Util::weaken $self;
1746 1910
1747 $self->{_rw} = AE::io $self->{fh}, 0, sub { 1911 $self->{_rw} = AE::io $self->{fh}, 0, sub {
1748 my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf}); 1912 my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf});
1749 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf; 1913 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size}, length $$rbuf;
1750 1914
1751 if ($len > 0) { 1915 if ($len > 0) {
1752 $self->{_activity} = $self->{_ractivity} = AE::now; 1916 $self->{_activity} = $self->{_ractivity} = AE::now;
1753 1917
1754 if ($self->{tls}) { 1918 if ($self->{tls}) {
… …
1757 &_dotls ($self); 1921 &_dotls ($self);
1758 } else { 1922 } else {
1759 $self->_drain_rbuf; 1923 $self->_drain_rbuf;
1760 } 1924 }
1761 1925
1926 if ($len == $self->{read_size}) {
1927 $self->{read_size} *= 2;
1928 $self->{read_size} = $self->{max_read_size} || MAX_READ_SIZE
1929 if $self->{read_size} > ($self->{max_read_size} || MAX_READ_SIZE);
1930 }
1931
1762 } elsif (defined $len) { 1932 } elsif (defined $len) {
1763 delete $self->{_rw}; 1933 delete $self->{_rw};
1764 $self->{_eof} = 1; 1934 $self->{_eof} = 1;
1765 $self->_drain_rbuf; 1935 $self->_drain_rbuf;
1766 1936
… …
1778 my ($self, $err) = @_; 1948 my ($self, $err) = @_;
1779 1949
1780 return $self->_error ($!, 1) 1950 return $self->_error ($!, 1)
1781 if $err == Net::SSLeay::ERROR_SYSCALL (); 1951 if $err == Net::SSLeay::ERROR_SYSCALL ();
1782 1952
1783 my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ()); 1953 my $err = Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
1784 1954
1785 # reduce error string to look less scary 1955 # reduce error string to look less scary
1786 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /; 1956 $err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
1787 1957
1788 if ($self->{_on_starttls}) { 1958 if ($self->{_on_starttls}) {
… …
1854 2024
1855=item $handle->starttls ($tls[, $tls_ctx]) 2025=item $handle->starttls ($tls[, $tls_ctx])
1856 2026
1857Instead of starting TLS negotiation immediately when the AnyEvent::Handle 2027Instead of starting TLS negotiation immediately when the AnyEvent::Handle
1858object is created, you can also do that at a later time by calling 2028object is created, you can also do that at a later time by calling
1859C<starttls>. 2029C<starttls>. See the C<tls> constructor argument for general info.
1860 2030
1861Starting TLS is currently an asynchronous operation - when you push some 2031Starting TLS is currently an asynchronous operation - when you push some
1862write data and then call C<< ->starttls >> then TLS negotiation will start 2032write data and then call C<< ->starttls >> then TLS negotiation will start
1863immediately, after which the queued write data is then sent. 2033immediately, after which the queued write data is then sent. This might
2034change in future versions, so best make sure you have no outstanding write
2035data when calling this method.
1864 2036
1865The first argument is the same as the C<tls> constructor argument (either 2037The first argument is the same as the C<tls> constructor argument (either
1866C<"connect">, C<"accept"> or an existing Net::SSLeay object). 2038C<"connect">, C<"accept"> or an existing Net::SSLeay object).
1867 2039
1868The second argument is the optional C<AnyEvent::TLS> object that is used 2040The second argument is the optional C<AnyEvent::TLS> object that is used
… …
1874context in C<< $handle->{tls_ctx} >> after this call and can be used or 2046context in C<< $handle->{tls_ctx} >> after this call and can be used or
1875changed to your liking. Note that the handshake might have already started 2047changed to your liking. Note that the handshake might have already started
1876when this function returns. 2048when this function returns.
1877 2049
1878Due to bugs in OpenSSL, it might or might not be possible to do multiple 2050Due to bugs in OpenSSL, it might or might not be possible to do multiple
1879handshakes on the same stream. Best do not attempt to use the stream after 2051handshakes on the same stream. It is best to not attempt to use the
1880stopping TLS. 2052stream after stopping TLS.
1881 2053
1882This method may invoke callbacks (and therefore the handle might be 2054This method may invoke callbacks (and therefore the handle might be
1883destroyed after it returns). 2055destroyed after it returns).
1884 2056
1885=cut 2057=cut
… …
1890 my ($self, $tls, $ctx) = @_; 2062 my ($self, $tls, $ctx) = @_;
1891 2063
1892 Carp::croak "It is an error to call starttls on an AnyEvent::Handle object while TLS is already active, caught" 2064 Carp::croak "It is an error to call starttls on an AnyEvent::Handle object while TLS is already active, caught"
1893 if $self->{tls}; 2065 if $self->{tls};
1894 2066
2067 unless (defined $AnyEvent::TLS::VERSION) {
2068 eval {
2069 require Net::SSLeay;
2070 require AnyEvent::TLS;
2071 1
2072 } or return $self->_error (Errno::EPROTO, 1, "TLS support not available on this system");
2073 }
2074
1895 $self->{tls} = $tls; 2075 $self->{tls} = $tls;
1896 $self->{tls_ctx} = $ctx if @_ > 2; 2076 $self->{tls_ctx} = $ctx if @_ > 2;
1897 2077
1898 return unless $self->{fh}; 2078 return unless $self->{fh};
1899 2079
1900 require Net::SSLeay;
1901
1902 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL (); 2080 $ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL ();
1903 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ (); 2081 $ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ ();
1904 2082
1905 $tls = delete $self->{tls}; 2083 $tls = delete $self->{tls};
1906 $ctx = $self->{tls_ctx}; 2084 $ctx = $self->{tls_ctx};
1907 2085
1908 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context or session 2086 local $Carp::CarpLevel = 1; # skip ourselves when creating a new context or session
1909 2087
1910 if ("HASH" eq ref $ctx) { 2088 if ("HASH" eq ref $ctx) {
1911 require AnyEvent::TLS;
1912
1913 if ($ctx->{cache}) { 2089 if ($ctx->{cache}) {
1914 my $key = $ctx+0; 2090 my $key = $ctx+0;
1915 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx; 2091 $ctx = $TLS_CACHE{$key} ||= new AnyEvent::TLS %$ctx;
1916 } else { 2092 } else {
1917 $ctx = new AnyEvent::TLS %$ctx; 2093 $ctx = new AnyEvent::TLS %$ctx;
… …
1939 Net::SSLeay::CTX_set_mode ($tls, 1|2); 2115 Net::SSLeay::CTX_set_mode ($tls, 1|2);
1940 2116
1941 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 2117 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1942 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 2118 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1943 2119
1944 Net::SSLeay::BIO_write ($self->{_rbio}, delete $self->{rbuf}); 2120 Net::SSLeay::BIO_write ($self->{_rbio}, $self->{rbuf});
2121 $self->{rbuf} = "";
1945 2122
1946 Net::SSLeay::set_bio ($tls, $self->{_rbio}, $self->{_wbio}); 2123 Net::SSLeay::set_bio ($tls, $self->{_rbio}, $self->{_wbio});
1947 2124
1948 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) } 2125 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
1949 if $self->{on_starttls}; 2126 if $self->{on_starttls};
… …
1987 if $self->{tls} > 0; 2164 if $self->{tls} > 0;
1988 2165
1989 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)}; 2166 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)};
1990} 2167}
1991 2168
2169=item $handle->resettls
2170
2171This rarely-used method simply resets and TLS state on the handle, usually
2172causing data loss.
2173
2174One case where it may be useful is when you want to skip over the data in
2175the stream but you are not interested in interpreting it, so data loss is
2176no concern.
2177
2178=cut
2179
2180*resettls = \&_freetls;
2181
1992sub DESTROY { 2182sub DESTROY {
1993 my ($self) = @_; 2183 my ($self) = @_;
1994 2184
1995 &_freetls; 2185 &_freetls;
1996 2186
… …
2005 push @linger, AE::io $fh, 1, sub { 2195 push @linger, AE::io $fh, 1, sub {
2006 my $len = syswrite $fh, $wbuf, length $wbuf; 2196 my $len = syswrite $fh, $wbuf, length $wbuf;
2007 2197
2008 if ($len > 0) { 2198 if ($len > 0) {
2009 substr $wbuf, 0, $len, ""; 2199 substr $wbuf, 0, $len, "";
2010 } else { 2200 } elsif (defined $len || ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK)) {
2011 @linger = (); # end 2201 @linger = (); # end
2012 } 2202 }
2013 }; 2203 };
2014 push @linger, AE::timer $linger, 0, sub { 2204 push @linger, AE::timer $linger, 0, sub {
2015 @linger = (); 2205 @linger = ();
… …
2111 2301
2112It is only safe to "forget" the reference inside EOF or error callbacks, 2302It is only safe to "forget" the reference inside EOF or error callbacks,
2113from within all other callbacks, you need to explicitly call the C<< 2303from within all other callbacks, you need to explicitly call the C<<
2114->destroy >> method. 2304->destroy >> method.
2115 2305
2306=item Why is my C<on_eof> callback never called?
2307
2308Probably because your C<on_error> callback is being called instead: When
2309you have outstanding requests in your read queue, then an EOF is
2310considered an error as you clearly expected some data.
2311
2312To avoid this, make sure you have an empty read queue whenever your handle
2313is supposed to be "idle" (i.e. connection closes are O.K.). You can set
2314an C<on_read> handler that simply pushes the first read requests in the
2315queue.
2316
2317See also the next question, which explains this in a bit more detail.
2318
2319=item How can I serve requests in a loop?
2320
2321Most protocols consist of some setup phase (authentication for example)
2322followed by a request handling phase, where the server waits for requests
2323and handles them, in a loop.
2324
2325There are two important variants: The first (traditional, better) variant
2326handles requests until the server gets some QUIT command, causing it to
2327close the connection first (highly desirable for a busy TCP server). A
2328client dropping the connection is an error, which means this variant can
2329detect an unexpected detection close.
2330
2331To handle this case, always make sure you have a non-empty read queue, by
2332pushing the "read request start" handler on it:
2333
2334 # we assume a request starts with a single line
2335 my @start_request; @start_request = (line => sub {
2336 my ($hdl, $line) = @_;
2337
2338 ... handle request
2339
2340 # push next request read, possibly from a nested callback
2341 $hdl->push_read (@start_request);
2342 });
2343
2344 # auth done, now go into request handling loop
2345 # now push the first @start_request
2346 $hdl->push_read (@start_request);
2347
2348By always having an outstanding C<push_read>, the handle always expects
2349some data and raises the C<EPIPE> error when the connction is dropped
2350unexpectedly.
2351
2352The second variant is a protocol where the client can drop the connection
2353at any time. For TCP, this means that the server machine may run out of
2354sockets easier, and in general, it means you cannot distinguish a protocl
2355failure/client crash from a normal connection close. Nevertheless, these
2356kinds of protocols are common (and sometimes even the best solution to the
2357problem).
2358
2359Having an outstanding read request at all times is possible if you ignore
2360C<EPIPE> errors, but this doesn't help with when the client drops the
2361connection during a request, which would still be an error.
2362
2363A better solution is to push the initial request read in an C<on_read>
2364callback. This avoids an error, as when the server doesn't expect data
2365(i.e. is idly waiting for the next request, an EOF will not raise an
2366error, but simply result in an C<on_eof> callback. It is also a bit slower
2367and simpler:
2368
2369 # auth done, now go into request handling loop
2370 $hdl->on_read (sub {
2371 my ($hdl) = @_;
2372
2373 # called each time we receive data but the read queue is empty
2374 # simply start read the request
2375
2376 $hdl->push_read (line => sub {
2377 my ($hdl, $line) = @_;
2378
2379 ... handle request
2380
2381 # do nothing special when the request has been handled, just
2382 # let the request queue go empty.
2383 });
2384 });
2385
2116=item I get different callback invocations in TLS mode/Why can't I pause 2386=item I get different callback invocations in TLS mode/Why can't I pause
2117reading? 2387reading?
2118 2388
2119Unlike, say, TCP, TLS connections do not consist of two independent 2389Unlike, say, TCP, TLS connections do not consist of two independent
2120communication channels, one for each direction. Or put differently. The 2390communication channels, one for each direction. Or put differently, the
2121read and write directions are not independent of each other: you cannot 2391read and write directions are not independent of each other: you cannot
2122write data unless you are also prepared to read, and vice versa. 2392write data unless you are also prepared to read, and vice versa.
2123 2393
2124This can mean than, in TLS mode, you might get C<on_error> or C<on_eof> 2394This means that, in TLS mode, you might get C<on_error> or C<on_eof>
2125callback invocations when you are not expecting any read data - the reason 2395callback invocations when you are not expecting any read data - the reason
2126is that AnyEvent::Handle always reads in TLS mode. 2396is that AnyEvent::Handle always reads in TLS mode.
2127 2397
2128During the connection, you have to make sure that you always have a 2398During the connection, you have to make sure that you always have a
2129non-empty read-queue, or an C<on_read> watcher. At the end of the 2399non-empty read-queue, or an C<on_read> watcher. At the end of the
… …
2141 $handle->on_eof (undef); 2411 $handle->on_eof (undef);
2142 $handle->on_error (sub { 2412 $handle->on_error (sub {
2143 my $data = delete $_[0]{rbuf}; 2413 my $data = delete $_[0]{rbuf};
2144 }); 2414 });
2145 2415
2416Note that this example removes the C<rbuf> member from the handle object,
2417which is not normally allowed by the API. It is expressly permitted in
2418this case only, as the handle object needs to be destroyed afterwards.
2419
2146The reason to use C<on_error> is that TCP connections, due to latencies 2420The reason to use C<on_error> is that TCP connections, due to latencies
2147and packets loss, might get closed quite violently with an error, when in 2421and packets loss, might get closed quite violently with an error, when in
2148fact, all data has been received. 2422fact all data has been received.
2149 2423
2150It is usually better to use acknowledgements when transferring data, 2424It is usually better to use acknowledgements when transferring data,
2151to make sure the other side hasn't just died and you got the data 2425to make sure the other side hasn't just died and you got the data
2152intact. This is also one reason why so many internet protocols have an 2426intact. This is also one reason why so many internet protocols have an
2153explicit QUIT command. 2427explicit QUIT command.
… …
2160C<low_water_mark> this will be called precisely when all data has been 2434C<low_water_mark> this will be called precisely when all data has been
2161written to the socket: 2435written to the socket:
2162 2436
2163 $handle->push_write (...); 2437 $handle->push_write (...);
2164 $handle->on_drain (sub { 2438 $handle->on_drain (sub {
2165 warn "all data submitted to the kernel\n"; 2439 AE::log debug => "All data submitted to the kernel.";
2166 undef $handle; 2440 undef $handle;
2167 }); 2441 });
2168 2442
2169If you just want to queue some data and then signal EOF to the other side, 2443If you just want to queue some data and then signal EOF to the other side,
2170consider using C<< ->push_shutdown >> instead. 2444consider using C<< ->push_shutdown >> instead.
2171 2445
2172=item I want to contact a TLS/SSL server, I don't care about security. 2446=item I want to contact a TLS/SSL server, I don't care about security.
2173 2447
2174If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS, 2448If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS,
2175simply connect to it and then create the AnyEvent::Handle with the C<tls> 2449connect to it and then create the AnyEvent::Handle with the C<tls>
2176parameter: 2450parameter:
2177 2451
2178 tcp_connect $host, $port, sub { 2452 tcp_connect $host, $port, sub {
2179 my ($fh) = @_; 2453 my ($fh) = @_;
2180 2454
… …
2254When you have intermediate CA certificates that your clients might not 2528When you have intermediate CA certificates that your clients might not
2255know about, just append them to the C<cert_file>. 2529know about, just append them to the C<cert_file>.
2256 2530
2257=back 2531=back
2258 2532
2259
2260=head1 SUBCLASSING AnyEvent::Handle 2533=head1 SUBCLASSING AnyEvent::Handle
2261 2534
2262In many cases, you might want to subclass AnyEvent::Handle. 2535In many cases, you might want to subclass AnyEvent::Handle.
2263 2536
2264To make this easier, a given version of AnyEvent::Handle uses these 2537To make this easier, a given version of AnyEvent::Handle uses these
… …
2280 2553
2281=item * all members not documented here and not prefixed with an underscore 2554=item * all members not documented here and not prefixed with an underscore
2282are free to use in subclasses. 2555are free to use in subclasses.
2283 2556
2284Of course, new versions of AnyEvent::Handle may introduce more "public" 2557Of course, new versions of AnyEvent::Handle may introduce more "public"
2285member variables, but thats just life, at least it is documented. 2558member variables, but that's just life. At least it is documented.
2286 2559
2287=back 2560=back
2288 2561
2289=head1 AUTHOR 2562=head1 AUTHOR
2290 2563
2291Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>. 2564Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>.
2292 2565
2293=cut 2566=cut
2294 2567
22951; # End of AnyEvent::Handle 25681
2569

Diff Legend

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