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.202 by root, Sat Oct 16 02:01:54 2010 UTC vs.
Revision 1.232 by root, Fri Mar 30 03:11:17 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 => "Got 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
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 that the 125seconds (or C<0>, or C<undef>, or the empty list, to indicate that the
124default timeout 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 peer's 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
133If, for some reason, the handle is not acceptable, calling C<$retry> 140If, for some reason, the handle is not acceptable, calling C<$retry> will
134will continue with the next connection target (in case of multi-homed 141continue with the next connection target (in case of multi-homed hosts or
135hosts or SRV records there can be multiple connection endpoints). At the 142SRV records there can be multiple connection endpoints). The C<$retry>
136time it is called the read and write queues, eof status, tls status and 143callback can be invoked after the connect callback returns, i.e. one can
137similar properties of the handle will have been reset. 144start a handshake and then decide to retry with the next host if the
145handshake fails.
138 146
139In most cases, you should ignore the C<$retry> parameter. 147In most cases, you should ignore the C<$retry> parameter.
140 148
141=item on_connect_error => $cb->($handle, $message) 149=item on_connect_error => $cb->($handle, $message)
142 150
157 165
158Some 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
159fatal 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<< ->
160destroy >>) after invoking the error callback (which means you are free to 168destroy >>) after invoking the error callback (which means you are free to
161examine the handle object). Examples of fatal errors are an EOF condition 169examine the handle object). Examples of fatal errors are an EOF condition
162with 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
163cases where the other side can close the connection at will, it is 171cases where the other side can close the connection at will, it is
164often easiest to not report C<EPIPE> errors in this callback. 172often easiest to not report C<EPIPE> errors in this callback.
165 173
166AnyEvent::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
167against, 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. It is
222If an EOF condition has been detected but no C<on_eof> callback has been 230If an EOF condition has been detected but no C<on_eof> callback has been
223set, then a fatal error will be raised with C<$!> set to <0>. 231set, then a fatal error will be raised with C<$!> set to <0>.
224 232
225=item on_drain => $cb->($handle) 233=item on_drain => $cb->($handle)
226 234
227This sets the callback that is called when the write buffer becomes empty 235This sets the callback that is called once when the write buffer becomes
228(or immediately if the buffer is empty already). 236empty (and immediately when the handle object is created).
229 237
230To append to the write buffer, use the C<< ->push_write >> method. 238To append to the write buffer, use the C<< ->push_write >> method.
231 239
232This callback is useful when you don't want to put all of your write data 240This callback is useful when you don't want to put all of your write data
233into the queue at once, for example, when you want to write the contents 241into the queue at once, for example, when you want to write the contents
245many seconds pass without a successful read or write on the underlying 253many seconds pass without a successful read or write on the underlying
246file handle (or a call to C<timeout_reset>), the C<on_timeout> callback 254file handle (or a call to C<timeout_reset>), the C<on_timeout> callback
247will be invoked (and if that one is missing, a non-fatal C<ETIMEDOUT> 255will be invoked (and if that one is missing, a non-fatal C<ETIMEDOUT>
248error will be raised). 256error will be raised).
249 257
250There are three variants of the timeouts that work independently 258There are three variants of the timeouts that work independently of each
251of each other, for both read and write, just read, and just write: 259other, for both read and write (triggered when nothing was read I<OR>
260written), just read (triggered when nothing was read), and just write:
252C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks 261C<timeout>, C<rtimeout> and C<wtimeout>, with corresponding callbacks
253C<on_timeout>, C<on_rtimeout> and C<on_wtimeout>, and reset functions 262C<on_timeout>, C<on_rtimeout> and C<on_wtimeout>, and reset functions
254C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>. 263C<timeout_reset>, C<rtimeout_reset>, and C<wtimeout_reset>.
255 264
256Note that timeout processing is active even when you do not have 265Note that timeout processing is active even when you do not have any
257any outstanding read or write requests: If you plan to keep the connection 266outstanding read or write requests: If you plan to keep the connection
258idle then you should disable the timeout temporarily or ignore the timeout 267idle then you should disable the timeout temporarily or ignore the
259in the C<on_timeout> callback, in which case AnyEvent::Handle will simply 268timeout in the corresponding C<on_timeout> callback, in which case
260restart the timeout. 269AnyEvent::Handle will simply restart the timeout.
261 270
262Zero (the default) disables this timeout. 271Zero (the default) disables the corresponding timeout.
263 272
264=item on_timeout => $cb->($handle) 273=item on_timeout => $cb->($handle)
274
275=item on_rtimeout => $cb->($handle)
276
277=item on_wtimeout => $cb->($handle)
265 278
266Called whenever the inactivity timeout passes. If you return from this 279Called whenever the inactivity timeout passes. If you return from this
267callback, then the timeout will be reset as if some activity had happened, 280callback, then the timeout will be reset as if some activity had happened,
268so this condition is not fatal in any way. 281so this condition is not fatal in any way.
269 282
276For example, a server accepting connections from untrusted sources should 289For example, a server accepting connections from untrusted sources should
277be configured to accept only so-and-so much data that it cannot act on 290be configured to accept only so-and-so much data that it cannot act on
278(for example, when expecting a line, an attacker could send an unlimited 291(for example, when expecting a line, an attacker could send an unlimited
279amount of data without a callback ever being called as long as the line 292amount of data without a callback ever being called as long as the line
280isn't finished). 293isn't finished).
294
295=item wbuf_max => <bytes>
296
297If defined, then a fatal error will be raised (with C<$!> set to C<ENOSPC>)
298when the write buffer ever (strictly) exceeds this size. This is useful to
299avoid some forms of denial-of-service attacks.
300
301Although the units of this parameter is bytes, this is the I<raw> number
302of bytes not yet accepted by the kernel. This can make a difference when
303you e.g. use TLS, as TLS typically makes your write data larger (but it
304can also make it smaller due to compression).
305
306As an example of when this limit is useful, take a chat server that sends
307chat messages to a client. If the client does not read those in a timely
308manner then the send buffer in the server would grow unbounded.
281 309
282=item autocork => <boolean> 310=item autocork => <boolean>
283 311
284When disabled (the default), C<push_write> will try to immediately 312When disabled (the default), C<push_write> will try to immediately
285write the data to the handle if possible. This avoids having to register 313write the data to the handle if possible. This avoids having to register
337already have occured on BSD systems), but at least it will protect you 365already have occured on BSD systems), but at least it will protect you
338from most attacks. 366from most attacks.
339 367
340=item read_size => <bytes> 368=item read_size => <bytes>
341 369
342The default read block size (the number of bytes this module will 370The initial read block size, the number of bytes this module will try
343try to read during each loop iteration, which affects memory 371to read during each loop iteration. Each handle object will consume
344requirements). Default: C<8192>. 372at least this amount of memory for the read buffer as well, so when
373handling many connections watch out for memory requirements). See also
374C<max_read_size>. Default: C<2048>.
375
376=item max_read_size => <bytes>
377
378The maximum read buffer size used by the dynamic adjustment
379algorithm: Each time AnyEvent::Handle can read C<read_size> bytes in
380one go it will double C<read_size> up to the maximum given by this
381option. Default: C<131072> or C<read_size>, whichever is higher.
345 382
346=item low_water_mark => <bytes> 383=item low_water_mark => <bytes>
347 384
348Sets the number of bytes (default: C<0>) that make up an "empty" write 385Sets the number of bytes (default: C<0>) that make up an "empty" write
349buffer: If the buffer reaches this size or gets even samller it is 386buffer: If the buffer reaches this size or gets even samller it is
412Use the C<< ->starttls >> method if you need to start TLS negotiation later. 449Use the C<< ->starttls >> method if you need to start TLS negotiation later.
413 450
414=item tls_ctx => $anyevent_tls 451=item tls_ctx => $anyevent_tls
415 452
416Use the given C<AnyEvent::TLS> object to create the new TLS connection 453Use the given C<AnyEvent::TLS> object to create the new TLS connection
417(unless a connection object was specified directly). If this parameter is 454(unless a connection object was specified directly). If this
418missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>. 455parameter is missing (or C<undef>), then AnyEvent::Handle will use
456C<AnyEvent::Handle::TLS_CTX>.
419 457
420Instead of an object, you can also specify a hash reference with C<< key 458Instead of an object, you can also specify a hash reference with C<< key
421=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a 459=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a
422new TLS context object. 460new TLS context object.
423 461
492 $self->{connect}[0], 530 $self->{connect}[0],
493 $self->{connect}[1], 531 $self->{connect}[1],
494 sub { 532 sub {
495 my ($fh, $host, $port, $retry) = @_; 533 my ($fh, $host, $port, $retry) = @_;
496 534
535 delete $self->{_connect}; # no longer needed
536
497 if ($fh) { 537 if ($fh) {
498 $self->{fh} = $fh; 538 $self->{fh} = $fh;
499 539
500 delete $self->{_skip_drain_rbuf}; 540 delete $self->{_skip_drain_rbuf};
501 $self->_start; 541 $self->_start;
508 }); 548 });
509 549
510 } else { 550 } else {
511 if ($self->{on_connect_error}) { 551 if ($self->{on_connect_error}) {
512 $self->{on_connect_error}($self, "$!"); 552 $self->{on_connect_error}($self, "$!");
513 $self->destroy; 553 $self->destroy if $self;
514 } else { 554 } else {
515 $self->_error ($!, 1); 555 $self->_error ($!, 1);
516 } 556 }
517 } 557 }
518 }, 558 },
519 sub { 559 sub {
520 local $self->{fh} = $_[0]; 560 local $self->{fh} = $_[0];
521 561
522 $self->{on_prepare} 562 $self->{on_prepare}
523 ? $self->{on_prepare}->($self) 563 ? $self->{on_prepare}->($self)
524 : () 564 : ()
525 } 565 }
526 ); 566 );
527 } 567 }
528 568
545 AnyEvent::Util::fh_nonblocking $self->{fh}, 1; 585 AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
546 586
547 $self->{_activity} = 587 $self->{_activity} =
548 $self->{_ractivity} = 588 $self->{_ractivity} =
549 $self->{_wactivity} = AE::now; 589 $self->{_wactivity} = AE::now;
590
591 $self->{read_size} ||= 2048;
592 $self->{max_read_size} = $self->{read_size}
593 if $self->{read_size} > ($self->{max_read_size} || MAX_READ_SIZE);
550 594
551 $self->timeout (delete $self->{timeout} ) if $self->{timeout}; 595 $self->timeout (delete $self->{timeout} ) if $self->{timeout};
552 $self->rtimeout (delete $self->{rtimeout} ) if $self->{rtimeout}; 596 $self->rtimeout (delete $self->{rtimeout} ) if $self->{rtimeout};
553 $self->wtimeout (delete $self->{wtimeout} ) if $self->{wtimeout}; 597 $self->wtimeout (delete $self->{wtimeout} ) if $self->{wtimeout};
554 598
723 767
724=item $handle->rbuf_max ($max_octets) 768=item $handle->rbuf_max ($max_octets)
725 769
726Configures the C<rbuf_max> setting (C<undef> disables it). 770Configures the C<rbuf_max> setting (C<undef> disables it).
727 771
772=item $handle->wbuf_max ($max_octets)
773
774Configures the C<wbuf_max> setting (C<undef> disables it).
775
728=cut 776=cut
729 777
730sub rbuf_max { 778sub rbuf_max {
731 $_[0]{rbuf_max} = $_[1]; 779 $_[0]{rbuf_max} = $_[1];
732} 780}
733 781
782sub wbuf_max {
783 $_[0]{wbuf_max} = $_[1];
784}
785
734############################################################################# 786#############################################################################
735 787
736=item $handle->timeout ($seconds) 788=item $handle->timeout ($seconds)
737 789
738=item $handle->rtimeout ($seconds) 790=item $handle->rtimeout ($seconds)
739 791
740=item $handle->wtimeout ($seconds) 792=item $handle->wtimeout ($seconds)
741 793
742Configures (or disables) the inactivity timeout. 794Configures (or disables) the inactivity timeout.
795
796The timeout will be checked instantly, so this method might destroy the
797handle before it returns.
743 798
744=item $handle->timeout_reset 799=item $handle->timeout_reset
745 800
746=item $handle->rtimeout_reset 801=item $handle->rtimeout_reset
747 802
831 886
832The write queue is very simple: you can add data to its end, and 887The write queue is very simple: you can add data to its end, and
833AnyEvent::Handle will automatically try to get rid of it for you. 888AnyEvent::Handle will automatically try to get rid of it for you.
834 889
835When data could be written and the write buffer is shorter then the low 890When data could be written and the write buffer is shorter then the low
836water mark, the C<on_drain> callback will be invoked. 891water mark, the C<on_drain> callback will be invoked once.
837 892
838=over 4 893=over 4
839 894
840=item $handle->on_drain ($cb) 895=item $handle->on_drain ($cb)
841 896
856 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf}); 911 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf});
857} 912}
858 913
859=item $handle->push_write ($data) 914=item $handle->push_write ($data)
860 915
861Queues the given scalar to be written. You can push as much data as you 916Queues the given scalar to be written. You can push as much data as
862want (only limited by the available memory), as C<AnyEvent::Handle> 917you want (only limited by the available memory and C<wbuf_max>), as
863buffers it independently of the kernel. 918C<AnyEvent::Handle> buffers it independently of the kernel.
864 919
865This method may invoke callbacks (and therefore the handle might be 920This method may invoke callbacks (and therefore the handle might be
866destroyed after it returns). 921destroyed after it returns).
867 922
868=cut 923=cut
896 $cb->() unless $self->{autocork}; 951 $cb->() unless $self->{autocork};
897 952
898 # if still data left in wbuf, we need to poll 953 # if still data left in wbuf, we need to poll
899 $self->{_ww} = AE::io $self->{fh}, 1, $cb 954 $self->{_ww} = AE::io $self->{fh}, 1, $cb
900 if length $self->{wbuf}; 955 if length $self->{wbuf};
956
957 if (
958 defined $self->{wbuf_max}
959 && $self->{wbuf_max} < length $self->{wbuf}
960 ) {
961 $self->_error (Errno::ENOSPC, 1), return;
962 }
901 }; 963 };
902} 964}
903 965
904our %WH; 966our %WH;
905 967
1025=cut 1087=cut
1026 1088
1027register_write_type storable => sub { 1089register_write_type storable => sub {
1028 my ($self, $ref) = @_; 1090 my ($self, $ref) = @_;
1029 1091
1030 require Storable; 1092 require Storable unless $Storable::VERSION;
1031 1093
1032 pack "w/a*", Storable::nfreeze ($ref) 1094 pack "w/a*", Storable::nfreeze ($ref)
1033}; 1095};
1034 1096
1035=back 1097=back
1040before it was actually written. One way to do that is to replace your 1102before it was actually written. One way to do that is to replace your
1041C<on_drain> handler by a callback that shuts down the socket (and set 1103C<on_drain> handler by a callback that shuts down the socket (and set
1042C<low_water_mark> to C<0>). This method is a shorthand for just that, and 1104C<low_water_mark> to C<0>). This method is a shorthand for just that, and
1043replaces the C<on_drain> callback with: 1105replaces the C<on_drain> callback with:
1044 1106
1045 sub { shutdown $_[0]{fh}, 1 } # for push_shutdown 1107 sub { shutdown $_[0]{fh}, 1 }
1046 1108
1047This simply shuts down the write side and signals an EOF condition to the 1109This simply shuts down the write side and signals an EOF condition to the
1048the peer. 1110the peer.
1049 1111
1050You can rely on the normal read queue and C<on_eof> handling 1112You can rely on the normal read queue and C<on_eof> handling
1072 1134
1073Whenever the given C<type> is used, C<push_write> will the function with 1135Whenever the given C<type> is used, C<push_write> will the function with
1074the handle object and the remaining arguments. 1136the handle object and the remaining arguments.
1075 1137
1076The function is supposed to return a single octet string that will be 1138The function is supposed to return a single octet string that will be
1077appended to the write buffer, so you cna mentally treat this function as a 1139appended to the write buffer, so you can mentally treat this function as a
1078"arguments to on-the-wire-format" converter. 1140"arguments to on-the-wire-format" converter.
1079 1141
1080Example: implement a custom write type C<join> that joins the remaining 1142Example: implement a custom write type C<join> that joins the remaining
1081arguments using the first one. 1143arguments using the first one.
1082 1144
1376data. 1438data.
1377 1439
1378Example: read 2 bytes. 1440Example: read 2 bytes.
1379 1441
1380 $handle->push_read (chunk => 2, sub { 1442 $handle->push_read (chunk => 2, sub {
1381 warn "yay ", unpack "H*", $_[1]; 1443 say "yay " . unpack "H*", $_[1];
1382 }); 1444 });
1383 1445
1384=cut 1446=cut
1385 1447
1386register_read_type chunk => sub { 1448register_read_type chunk => sub {
1420 if (@_ < 3) { 1482 if (@_ < 3) {
1421 # this is more than twice as fast as the generic code below 1483 # this is more than twice as fast as the generic code below
1422 sub { 1484 sub {
1423 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return; 1485 $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return;
1424 1486
1425 $cb->($_[0], $1, $2); 1487 $cb->($_[0], "$1", "$2");
1426 1 1488 1
1427 } 1489 }
1428 } else { 1490 } else {
1429 $eol = quotemeta $eol unless ref $eol; 1491 $eol = quotemeta $eol unless ref $eol;
1430 $eol = qr|^(.*?)($eol)|s; 1492 $eol = qr|^(.*?)($eol)|s;
1431 1493
1432 sub { 1494 sub {
1433 $_[0]{rbuf} =~ s/$eol// or return; 1495 $_[0]{rbuf} =~ s/$eol// or return;
1434 1496
1435 $cb->($_[0], $1, $2); 1497 $cb->($_[0], "$1", "$2");
1436 1 1498 1
1437 } 1499 }
1438 } 1500 }
1439}; 1501};
1440 1502
1488 1550
1489 sub { 1551 sub {
1490 # accept 1552 # accept
1491 if ($$rbuf =~ $accept) { 1553 if ($$rbuf =~ $accept) {
1492 $data .= substr $$rbuf, 0, $+[0], ""; 1554 $data .= substr $$rbuf, 0, $+[0], "";
1493 $cb->($self, $data); 1555 $cb->($_[0], $data);
1494 return 1; 1556 return 1;
1495 } 1557 }
1496 1558
1497 # reject 1559 # reject
1498 if ($reject && $$rbuf =~ $reject) { 1560 if ($reject && $$rbuf =~ $reject) {
1499 $self->_error (Errno::EBADMSG); 1561 $_[0]->_error (Errno::EBADMSG);
1500 } 1562 }
1501 1563
1502 # skip 1564 # skip
1503 if ($skip && $$rbuf =~ $skip) { 1565 if ($skip && $$rbuf =~ $skip) {
1504 $data .= substr $$rbuf, 0, $+[0], ""; 1566 $data .= substr $$rbuf, 0, $+[0], "";
1520 my ($self, $cb) = @_; 1582 my ($self, $cb) = @_;
1521 1583
1522 sub { 1584 sub {
1523 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) { 1585 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) {
1524 if ($_[0]{rbuf} =~ /[^0-9]/) { 1586 if ($_[0]{rbuf} =~ /[^0-9]/) {
1525 $self->_error (Errno::EBADMSG); 1587 $_[0]->_error (Errno::EBADMSG);
1526 } 1588 }
1527 return; 1589 return;
1528 } 1590 }
1529 1591
1530 my $len = $1; 1592 my $len = $1;
1531 1593
1532 $self->unshift_read (chunk => $len, sub { 1594 $_[0]->unshift_read (chunk => $len, sub {
1533 my $string = $_[1]; 1595 my $string = $_[1];
1534 $_[0]->unshift_read (chunk => 1, sub { 1596 $_[0]->unshift_read (chunk => 1, sub {
1535 if ($_[1] eq ",") { 1597 if ($_[1] eq ",") {
1536 $cb->($_[0], $string); 1598 $cb->($_[0], $string);
1537 } else { 1599 } else {
1538 $self->_error (Errno::EBADMSG); 1600 $_[0]->_error (Errno::EBADMSG);
1539 } 1601 }
1540 }); 1602 });
1541 }); 1603 });
1542 1604
1543 1 1605 1
1616 1678
1617 my $data; 1679 my $data;
1618 my $rbuf = \$self->{rbuf}; 1680 my $rbuf = \$self->{rbuf};
1619 1681
1620 sub { 1682 sub {
1621 my $ref = eval { $json->incr_parse ($self->{rbuf}) }; 1683 my $ref = eval { $json->incr_parse ($_[0]{rbuf}) };
1622 1684
1623 if ($ref) { 1685 if ($ref) {
1624 $self->{rbuf} = $json->incr_text; 1686 $_[0]{rbuf} = $json->incr_text;
1625 $json->incr_text = ""; 1687 $json->incr_text = "";
1626 $cb->($self, $ref); 1688 $cb->($_[0], $ref);
1627 1689
1628 1 1690 1
1629 } elsif ($@) { 1691 } elsif ($@) {
1630 # error case 1692 # error case
1631 $json->incr_skip; 1693 $json->incr_skip;
1632 1694
1633 $self->{rbuf} = $json->incr_text; 1695 $_[0]{rbuf} = $json->incr_text;
1634 $json->incr_text = ""; 1696 $json->incr_text = "";
1635 1697
1636 $self->_error (Errno::EBADMSG); 1698 $_[0]->_error (Errno::EBADMSG);
1637 1699
1638 () 1700 ()
1639 } else { 1701 } else {
1640 $self->{rbuf} = ""; 1702 $_[0]{rbuf} = "";
1641 1703
1642 () 1704 ()
1643 } 1705 }
1644 } 1706 }
1645}; 1707};
1655=cut 1717=cut
1656 1718
1657register_read_type storable => sub { 1719register_read_type storable => sub {
1658 my ($self, $cb) = @_; 1720 my ($self, $cb) = @_;
1659 1721
1660 require Storable; 1722 require Storable unless $Storable::VERSION;
1661 1723
1662 sub { 1724 sub {
1663 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method 1725 # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
1664 defined (my $len = eval { unpack "w", $_[0]{rbuf} }) 1726 defined (my $len = eval { unpack "w", $_[0]{rbuf} })
1665 or return; 1727 or return;
1668 1730
1669 # bypass unshift if we already have the remaining chunk 1731 # bypass unshift if we already have the remaining chunk
1670 if ($format + $len <= length $_[0]{rbuf}) { 1732 if ($format + $len <= length $_[0]{rbuf}) {
1671 my $data = substr $_[0]{rbuf}, $format, $len; 1733 my $data = substr $_[0]{rbuf}, $format, $len;
1672 substr $_[0]{rbuf}, 0, $format + $len, ""; 1734 substr $_[0]{rbuf}, 0, $format + $len, "";
1735
1673 $cb->($_[0], Storable::thaw ($data)); 1736 eval { $cb->($_[0], Storable::thaw ($data)); 1 }
1737 or return $_[0]->_error (Errno::EBADMSG);
1674 } else { 1738 } else {
1675 # remove prefix 1739 # remove prefix
1676 substr $_[0]{rbuf}, 0, $format, ""; 1740 substr $_[0]{rbuf}, 0, $format, "";
1677 1741
1678 # read remaining chunk 1742 # read remaining chunk
1679 $_[0]->unshift_read (chunk => $len, sub { 1743 $_[0]->unshift_read (chunk => $len, sub {
1680 if (my $ref = eval { Storable::thaw ($_[1]) }) { 1744 eval { $cb->($_[0], Storable::thaw ($_[1])); 1 }
1681 $cb->($_[0], $ref);
1682 } else {
1683 $self->_error (Errno::EBADMSG); 1745 or $_[0]->_error (Errno::EBADMSG);
1684 }
1685 }); 1746 });
1686 } 1747 }
1687 1748
1688 1 1749 1
1689 } 1750 }
1726Note that AnyEvent::Handle will automatically C<start_read> for you when 1787Note that AnyEvent::Handle will automatically C<start_read> for you when
1727you change the C<on_read> callback or push/unshift a read callback, and it 1788you change the C<on_read> callback or push/unshift a read callback, and it
1728will automatically C<stop_read> for you when neither C<on_read> is set nor 1789will automatically C<stop_read> for you when neither C<on_read> is set nor
1729there are any read requests in the queue. 1790there are any read requests in the queue.
1730 1791
1731These methods will have no effect when in TLS mode (as TLS doesn't support 1792In older versions of this module (<= 5.3), these methods had no effect,
1732half-duplex connections). 1793as TLS does not support half-duplex connections. In current versions they
1794work as expected, as this behaviour is required to avoid certain resource
1795attacks, where the program would be forced to read (and buffer) arbitrary
1796amounts of data before being able to send some data. The drawback is that
1797some readings of the the SSL/TLS specifications basically require this
1798attack to be working, as SSL/TLS implementations might stall sending data
1799during a rehandshake.
1800
1801As a guideline, during the initial handshake, you should not stop reading,
1802and as a client, it might cause problems, depending on your application.
1733 1803
1734=cut 1804=cut
1735 1805
1736sub stop_read { 1806sub stop_read {
1737 my ($self) = @_; 1807 my ($self) = @_;
1738 1808
1739 delete $self->{_rw} unless $self->{tls}; 1809 delete $self->{_rw};
1740} 1810}
1741 1811
1742sub start_read { 1812sub start_read {
1743 my ($self) = @_; 1813 my ($self) = @_;
1744 1814
1745 unless ($self->{_rw} || $self->{_eof} || !$self->{fh}) { 1815 unless ($self->{_rw} || $self->{_eof} || !$self->{fh}) {
1746 Scalar::Util::weaken $self; 1816 Scalar::Util::weaken $self;
1747 1817
1748 $self->{_rw} = AE::io $self->{fh}, 0, sub { 1818 $self->{_rw} = AE::io $self->{fh}, 0, sub {
1749 my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf}); 1819 my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf});
1750 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf; 1820 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size}, length $$rbuf;
1751 1821
1752 if ($len > 0) { 1822 if ($len > 0) {
1753 $self->{_activity} = $self->{_ractivity} = AE::now; 1823 $self->{_activity} = $self->{_ractivity} = AE::now;
1754 1824
1755 if ($self->{tls}) { 1825 if ($self->{tls}) {
1756 Net::SSLeay::BIO_write ($self->{_rbio}, $$rbuf); 1826 Net::SSLeay::BIO_write ($self->{_rbio}, $$rbuf);
1757 1827
1758 &_dotls ($self); 1828 &_dotls ($self);
1759 } else { 1829 } else {
1760 $self->_drain_rbuf; 1830 $self->_drain_rbuf;
1831 }
1832
1833 if ($len == $self->{read_size}) {
1834 $self->{read_size} *= 2;
1835 $self->{read_size} = $self->{max_read_size} || MAX_READ_SIZE
1836 if $self->{read_size} > ($self->{max_read_size} || MAX_READ_SIZE);
1761 } 1837 }
1762 1838
1763 } elsif (defined $len) { 1839 } elsif (defined $len) {
1764 delete $self->{_rw}; 1840 delete $self->{_rw};
1765 $self->{_eof} = 1; 1841 $self->{_eof} = 1;
1940 Net::SSLeay::CTX_set_mode ($tls, 1|2); 2016 Net::SSLeay::CTX_set_mode ($tls, 1|2);
1941 2017
1942 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 2018 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1943 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 2019 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1944 2020
1945 Net::SSLeay::BIO_write ($self->{_rbio}, delete $self->{rbuf}); 2021 Net::SSLeay::BIO_write ($self->{_rbio}, $self->{rbuf});
2022 $self->{rbuf} = "";
1946 2023
1947 Net::SSLeay::set_bio ($tls, $self->{_rbio}, $self->{_wbio}); 2024 Net::SSLeay::set_bio ($tls, $self->{_rbio}, $self->{_wbio});
1948 2025
1949 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) } 2026 $self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
1950 if $self->{on_starttls}; 2027 if $self->{on_starttls};
1987 $self->{tls_ctx}->_put_session (delete $self->{tls}) 2064 $self->{tls_ctx}->_put_session (delete $self->{tls})
1988 if $self->{tls} > 0; 2065 if $self->{tls} > 0;
1989 2066
1990 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)}; 2067 delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)};
1991} 2068}
2069
2070=item $handle->resettls
2071
2072This rarely-used method simply resets and TLS state on the handle, usually
2073causing data loss.
2074
2075One case where it may be useful is when you want to skip over the data in
2076the stream but you are not interested in interpreting it, so data loss is
2077no concern.
2078
2079=cut
2080
2081*resettls = \&_freetls;
1992 2082
1993sub DESTROY { 2083sub DESTROY {
1994 my ($self) = @_; 2084 my ($self) = @_;
1995 2085
1996 &_freetls; 2086 &_freetls;
2112 2202
2113It is only safe to "forget" the reference inside EOF or error callbacks, 2203It is only safe to "forget" the reference inside EOF or error callbacks,
2114from within all other callbacks, you need to explicitly call the C<< 2204from within all other callbacks, you need to explicitly call the C<<
2115->destroy >> method. 2205->destroy >> method.
2116 2206
2207=item Why is my C<on_eof> callback never called?
2208
2209Probably because your C<on_error> callback is being called instead: When
2210you have outstanding requests in your read queue, then an EOF is
2211considered an error as you clearly expected some data.
2212
2213To avoid this, make sure you have an empty read queue whenever your handle
2214is supposed to be "idle" (i.e. connection closes are O.K.). You can set
2215an C<on_read> handler that simply pushes the first read requests in the
2216queue.
2217
2218See also the next question, which explains this in a bit more detail.
2219
2220=item How can I serve requests in a loop?
2221
2222Most protocols consist of some setup phase (authentication for example)
2223followed by a request handling phase, where the server waits for requests
2224and handles them, in a loop.
2225
2226There are two important variants: The first (traditional, better) variant
2227handles requests until the server gets some QUIT command, causing it to
2228close the connection first (highly desirable for a busy TCP server). A
2229client dropping the connection is an error, which means this variant can
2230detect an unexpected detection close.
2231
2232To handle this case, always make sure you have a on-empty read queue, by
2233pushing the "read request start" handler on it:
2234
2235 # we assume a request starts with a single line
2236 my @start_request; @start_request = (line => sub {
2237 my ($hdl, $line) = @_;
2238
2239 ... handle request
2240
2241 # push next request read, possibly from a nested callback
2242 $hdl->push_read (@start_request);
2243 });
2244
2245 # auth done, now go into request handling loop
2246 # now push the first @start_request
2247 $hdl->push_read (@start_request);
2248
2249By always having an outstanding C<push_read>, the handle always expects
2250some data and raises the C<EPIPE> error when the connction is dropped
2251unexpectedly.
2252
2253The second variant is a protocol where the client can drop the connection
2254at any time. For TCP, this means that the server machine may run out of
2255sockets easier, and in general, it means you cannot distinguish a protocl
2256failure/client crash from a normal connection close. Nevertheless, these
2257kinds of protocols are common (and sometimes even the best solution to the
2258problem).
2259
2260Having an outstanding read request at all times is possible if you ignore
2261C<EPIPE> errors, but this doesn't help with when the client drops the
2262connection during a request, which would still be an error.
2263
2264A better solution is to push the initial request read in an C<on_read>
2265callback. This avoids an error, as when the server doesn't expect data
2266(i.e. is idly waiting for the next request, an EOF will not raise an
2267error, but simply result in an C<on_eof> callback. It is also a bit slower
2268and simpler:
2269
2270 # auth done, now go into request handling loop
2271 $hdl->on_read (sub {
2272 my ($hdl) = @_;
2273
2274 # called each time we receive data but the read queue is empty
2275 # simply start read the request
2276
2277 $hdl->push_read (line => sub {
2278 my ($hdl, $line) = @_;
2279
2280 ... handle request
2281
2282 # do nothing special when the request has been handled, just
2283 # let the request queue go empty.
2284 });
2285 });
2286
2117=item I get different callback invocations in TLS mode/Why can't I pause 2287=item I get different callback invocations in TLS mode/Why can't I pause
2118reading? 2288reading?
2119 2289
2120Unlike, say, TCP, TLS connections do not consist of two independent 2290Unlike, say, TCP, TLS connections do not consist of two independent
2121communication channels, one for each direction. Or put differently, the 2291communication channels, one for each direction. Or put differently, the
2142 $handle->on_eof (undef); 2312 $handle->on_eof (undef);
2143 $handle->on_error (sub { 2313 $handle->on_error (sub {
2144 my $data = delete $_[0]{rbuf}; 2314 my $data = delete $_[0]{rbuf};
2145 }); 2315 });
2146 2316
2317Note that this example removes the C<rbuf> member from the handle object,
2318which is not normally allowed by the API. It is expressly permitted in
2319this case only, as the handle object needs to be destroyed afterwards.
2320
2147The reason to use C<on_error> is that TCP connections, due to latencies 2321The reason to use C<on_error> is that TCP connections, due to latencies
2148and packets loss, might get closed quite violently with an error, when in 2322and packets loss, might get closed quite violently with an error, when in
2149fact all data has been received. 2323fact all data has been received.
2150 2324
2151It is usually better to use acknowledgements when transferring data, 2325It is usually better to use acknowledgements when transferring data,
2161C<low_water_mark> this will be called precisely when all data has been 2335C<low_water_mark> this will be called precisely when all data has been
2162written to the socket: 2336written to the socket:
2163 2337
2164 $handle->push_write (...); 2338 $handle->push_write (...);
2165 $handle->on_drain (sub { 2339 $handle->on_drain (sub {
2166 warn "all data submitted to the kernel\n"; 2340 AE::log debug => "All data submitted to the kernel.";
2167 undef $handle; 2341 undef $handle;
2168 }); 2342 });
2169 2343
2170If you just want to queue some data and then signal EOF to the other side, 2344If you just want to queue some data and then signal EOF to the other side,
2171consider using C<< ->push_shutdown >> instead. 2345consider using C<< ->push_shutdown >> instead.
2255When you have intermediate CA certificates that your clients might not 2429When you have intermediate CA certificates that your clients might not
2256know about, just append them to the C<cert_file>. 2430know about, just append them to the C<cert_file>.
2257 2431
2258=back 2432=back
2259 2433
2260
2261=head1 SUBCLASSING AnyEvent::Handle 2434=head1 SUBCLASSING AnyEvent::Handle
2262 2435
2263In many cases, you might want to subclass AnyEvent::Handle. 2436In many cases, you might want to subclass AnyEvent::Handle.
2264 2437
2265To make this easier, a given version of AnyEvent::Handle uses these 2438To make this easier, a given version of AnyEvent::Handle uses these
2291 2464
2292Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>. 2465Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>.
2293 2466
2294=cut 2467=cut
2295 2468
22961; # End of AnyEvent::Handle 24691
2470

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines