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.44 by root, Thu May 29 00:00:07 2008 UTC vs.
Revision 1.55 by root, Tue Jun 3 16:15:30 2008 UTC

… …
14 14
15AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent 15AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent
16 16
17=cut 17=cut
18 18
19our $VERSION = '0.04'; 19our $VERSION = 4.12;
20 20
21=head1 SYNOPSIS 21=head1 SYNOPSIS
22 22
23 use AnyEvent; 23 use AnyEvent;
24 use AnyEvent::Handle; 24 use AnyEvent::Handle;
… …
75NOTE: The filehandle will be set to non-blocking (using 75NOTE: The filehandle will be set to non-blocking (using
76AnyEvent::Util::fh_nonblocking). 76AnyEvent::Util::fh_nonblocking).
77 77
78=item on_eof => $cb->($handle) 78=item on_eof => $cb->($handle)
79 79
80Set the callback to be called on EOF. 80Set the callback to be called when an end-of-file condition is detcted,
81i.e. in the case of a socket, when the other side has closed the
82connection cleanly.
81 83
82While not mandatory, it is highly recommended to set an eof callback, 84While not mandatory, it is highly recommended to set an eof callback,
83otherwise you might end up with a closed socket while you are still 85otherwise you might end up with a closed socket while you are still
84waiting for data. 86waiting for data.
85 87
86=item on_error => $cb->($handle) 88=item on_error => $cb->($handle, $fatal)
87 89
88This is the fatal error callback, that is called when, well, a fatal error 90This is the error callback, which is called when, well, some error
89occurs, such as not being able to resolve the hostname, failure to connect 91occured, such as not being able to resolve the hostname, failure to
90or a read error. 92connect or a read error.
91 93
92The object will not be in a usable state when this callback has been 94Some errors are fatal (which is indicated by C<$fatal> being true). On
93called. 95fatal errors the handle object will be shut down and will not be
96usable. Non-fatal errors can be retried by simply returning, but it is
97recommended to simply ignore this parameter and instead abondon the handle
98object when this callback is invoked.
94 99
95On callback entrance, the value of C<$!> contains the operating system 100On callback entrance, the value of C<$!> contains the operating system
96error (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT> or C<EBADMSG>). 101error (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT> or C<EBADMSG>).
97 102
98The callback should throw an exception. If it returns, then
99AnyEvent::Handle will C<croak> for you.
100
101While not mandatory, it is I<highly> recommended to set this callback, as 103While not mandatory, it is I<highly> recommended to set this callback, as
102you will not be notified of errors otherwise. The default simply calls 104you will not be notified of errors otherwise. The default simply calls
103die. 105C<croak>.
104 106
105=item on_read => $cb->($handle) 107=item on_read => $cb->($handle)
106 108
107This sets the default read callback, which is called when data arrives 109This sets the default read callback, which is called when data arrives
108and no read request is in the queue. 110and no read request is in the queue.
… …
125=item timeout => $fractional_seconds 127=item timeout => $fractional_seconds
126 128
127If non-zero, then this enables an "inactivity" timeout: whenever this many 129If non-zero, then this enables an "inactivity" timeout: whenever this many
128seconds pass without a successful read or write on the underlying file 130seconds pass without a successful read or write on the underlying file
129handle, the C<on_timeout> callback will be invoked (and if that one is 131handle, the C<on_timeout> callback will be invoked (and if that one is
130missing, an C<ETIMEDOUT> errror will be raised). 132missing, an C<ETIMEDOUT> error will be raised).
131 133
132Note that timeout processing is also active when you currently do not have 134Note that timeout processing is also active when you currently do not have
133any outstanding read or write requests: If you plan to keep the connection 135any outstanding read or write requests: If you plan to keep the connection
134idle then you should disable the timout temporarily or ignore the timeout 136idle then you should disable the timout temporarily or ignore the timeout
135in the C<on_timeout> callback. 137in the C<on_timeout> callback.
… …
155isn't finished). 157isn't finished).
156 158
157=item read_size => <bytes> 159=item read_size => <bytes>
158 160
159The default read block size (the amount of bytes this module will try to read 161The default read block size (the amount of bytes this module will try to read
160on each [loop iteration). Default: C<4096>. 162during each (loop iteration). Default: C<8192>.
161 163
162=item low_water_mark => <bytes> 164=item low_water_mark => <bytes>
163 165
164Sets the amount of bytes (default: C<0>) that make up an "empty" write 166Sets the amount of bytes (default: C<0>) that make up an "empty" write
165buffer: If the write reaches this size or gets even samller it is 167buffer: If the write reaches this size or gets even samller it is
… …
238} 240}
239 241
240sub _shutdown { 242sub _shutdown {
241 my ($self) = @_; 243 my ($self) = @_;
242 244
245 delete $self->{_tw};
243 delete $self->{_rw}; 246 delete $self->{_rw};
244 delete $self->{_ww}; 247 delete $self->{_ww};
245 delete $self->{fh}; 248 delete $self->{fh};
246}
247 249
250 $self->stoptls;
251}
252
248sub error { 253sub _error {
249 my ($self) = @_; 254 my ($self, $errno, $fatal) = @_;
250 255
251 {
252 local $!;
253 $self->_shutdown; 256 $self->_shutdown
254 } 257 if $fatal;
255 258
256 $self->{on_error}($self) 259 $! = $errno;
260
257 if $self->{on_error}; 261 if ($self->{on_error}) {
258 262 $self->{on_error}($self, $fatal);
263 } else {
259 Carp::croak "AnyEvent::Handle uncaught fatal error: $!"; 264 Carp::croak "AnyEvent::Handle uncaught error: $!";
265 }
260} 266}
261 267
262=item $fh = $handle->fh 268=item $fh = $handle->fh
263 269
264This method returns the file handle of the L<AnyEvent::Handle> object. 270This method returns the file handle of the L<AnyEvent::Handle> object.
… …
328 # now or in the past already? 334 # now or in the past already?
329 if ($after <= 0) { 335 if ($after <= 0) {
330 $self->{_activity} = $NOW; 336 $self->{_activity} = $NOW;
331 337
332 if ($self->{on_timeout}) { 338 if ($self->{on_timeout}) {
333 $self->{on_timeout}->($self); 339 $self->{on_timeout}($self);
334 } else { 340 } else {
335 $! = Errno::ETIMEDOUT; 341 $self->_error (&Errno::ETIMEDOUT);
336 $self->error;
337 } 342 }
338 343
339 # callbakx could have changed timeout value, optimise 344 # callbakx could have changed timeout value, optimise
340 return unless $self->{timeout}; 345 return unless $self->{timeout};
341 346
… …
414 if $self->{low_water_mark} >= length $self->{wbuf} 419 if $self->{low_water_mark} >= length $self->{wbuf}
415 && $self->{on_drain}; 420 && $self->{on_drain};
416 421
417 delete $self->{_ww} unless length $self->{wbuf}; 422 delete $self->{_ww} unless length $self->{wbuf};
418 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) { 423 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
419 $self->error; 424 $self->_error ($!, 1);
420 } 425 }
421 }; 426 };
422 427
423 # try to write data immediately 428 # try to write data immediately
424 $cb->(); 429 $cb->();
… …
444 @_ = ($WH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_write") 449 @_ = ($WH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_write")
445 ->($self, @_); 450 ->($self, @_);
446 } 451 }
447 452
448 if ($self->{filter_w}) { 453 if ($self->{filter_w}) {
449 $self->{filter_w}->($self, \$_[0]); 454 $self->{filter_w}($self, \$_[0]);
450 } else { 455 } else {
451 $self->{wbuf} .= $_[0]; 456 $self->{wbuf} .= $_[0];
452 $self->_drain_wbuf; 457 $self->_drain_wbuf;
453 } 458 }
454} 459}
455 460
456=item $handle->push_write (type => @args) 461=item $handle->push_write (type => @args)
457 462
458=item $handle->unshift_write (type => @args)
459
460Instead of formatting your data yourself, you can also let this module do 463Instead of formatting your data yourself, you can also let this module do
461the job by specifying a type and type-specific arguments. 464the job by specifying a type and type-specific arguments.
462 465
463Predefined types are (if you have ideas for additional types, feel free to 466Predefined types are (if you have ideas for additional types, feel free to
464drop by and tell us): 467drop by and tell us):
… …
467 470
468=item netstring => $string 471=item netstring => $string
469 472
470Formats the given value as netstring 473Formats the given value as netstring
471(http://cr.yp.to/proto/netstrings.txt, this is not a recommendation to use them). 474(http://cr.yp.to/proto/netstrings.txt, this is not a recommendation to use them).
472
473=back
474 475
475=cut 476=cut
476 477
477register_write_type netstring => sub { 478register_write_type netstring => sub {
478 my ($self, $string) = @_; 479 my ($self, $string) = @_;
… …
519 520
520 $self->{json} ? $self->{json}->encode ($ref) 521 $self->{json} ? $self->{json}->encode ($ref)
521 : JSON::encode_json ($ref) 522 : JSON::encode_json ($ref)
522}; 523};
523 524
525=back
526
524=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args) 527=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args)
525 528
526This function (not method) lets you add your own types to C<push_write>. 529This function (not method) lets you add your own types to C<push_write>.
527Whenever the given C<type> is used, C<push_write> will invoke the code 530Whenever the given C<type> is used, C<push_write> will invoke the code
528reference with the handle object and the remaining arguments. 531reference with the handle object and the remaining arguments.
… …
565the specified number of bytes which give an XML datagram. 568the specified number of bytes which give an XML datagram.
566 569
567 # in the default state, expect some header bytes 570 # in the default state, expect some header bytes
568 $handle->on_read (sub { 571 $handle->on_read (sub {
569 # some data is here, now queue the length-header-read (4 octets) 572 # some data is here, now queue the length-header-read (4 octets)
570 shift->unshift_read_chunk (4, sub { 573 shift->unshift_read (chunk => 4, sub {
571 # header arrived, decode 574 # header arrived, decode
572 my $len = unpack "N", $_[1]; 575 my $len = unpack "N", $_[1];
573 576
574 # now read the payload 577 # now read the payload
575 shift->unshift_read_chunk ($len, sub { 578 shift->unshift_read (chunk => $len, sub {
576 my $xml = $_[1]; 579 my $xml = $_[1];
577 # handle xml 580 # handle xml
578 }); 581 });
579 }); 582 });
580 }); 583 });
… …
587 590
588 # request one 591 # request one
589 $handle->push_write ("request 1\015\012"); 592 $handle->push_write ("request 1\015\012");
590 593
591 # we expect "ERROR" or "OK" as response, so push a line read 594 # we expect "ERROR" or "OK" as response, so push a line read
592 $handle->push_read_line (sub { 595 $handle->push_read (line => sub {
593 # if we got an "OK", we have to _prepend_ another line, 596 # if we got an "OK", we have to _prepend_ another line,
594 # so it will be read before the second request reads its 64 bytes 597 # so it will be read before the second request reads its 64 bytes
595 # which are already in the queue when this callback is called 598 # which are already in the queue when this callback is called
596 # we don't do this in case we got an error 599 # we don't do this in case we got an error
597 if ($_[1] eq "OK") { 600 if ($_[1] eq "OK") {
598 $_[0]->unshift_read_line (sub { 601 $_[0]->unshift_read (line => sub {
599 my $response = $_[1]; 602 my $response = $_[1];
600 ... 603 ...
601 }); 604 });
602 } 605 }
603 }); 606 });
604 607
605 # request two 608 # request two
606 $handle->push_write ("request 2\015\012"); 609 $handle->push_write ("request 2\015\012");
607 610
608 # simply read 64 bytes, always 611 # simply read 64 bytes, always
609 $handle->push_read_chunk (64, sub { 612 $handle->push_read (chunk => 64, sub {
610 my $response = $_[1]; 613 my $response = $_[1];
611 ... 614 ...
612 }); 615 });
613 616
614=over 4 617=over 4
… …
620 623
621 if ( 624 if (
622 defined $self->{rbuf_max} 625 defined $self->{rbuf_max}
623 && $self->{rbuf_max} < length $self->{rbuf} 626 && $self->{rbuf_max} < length $self->{rbuf}
624 ) { 627 ) {
625 $! = &Errno::ENOSPC; 628 return $self->_error (&Errno::ENOSPC, 1);
626 $self->error;
627 } 629 }
628 630
629 return if $self->{in_drain}; 631 return if $self->{in_drain};
630 local $self->{in_drain} = 1; 632 local $self->{in_drain} = 1;
631 633
… …
633 no strict 'refs'; 635 no strict 'refs';
634 if (my $cb = shift @{ $self->{_queue} }) { 636 if (my $cb = shift @{ $self->{_queue} }) {
635 unless ($cb->($self)) { 637 unless ($cb->($self)) {
636 if ($self->{_eof}) { 638 if ($self->{_eof}) {
637 # no progress can be made (not enough data and no data forthcoming) 639 # no progress can be made (not enough data and no data forthcoming)
638 $! = &Errno::EPIPE; 640 return $self->_error (&Errno::EPIPE, 1);
639 $self->error;
640 } 641 }
641 642
642 unshift @{ $self->{_queue} }, $cb; 643 unshift @{ $self->{_queue} }, $cb;
643 return; 644 last;
644 } 645 }
645 } elsif ($self->{on_read}) { 646 } elsif ($self->{on_read}) {
646 $self->{on_read}($self); 647 $self->{on_read}($self);
647 648
648 if ( 649 if (
649 $self->{_eof} # if no further data will arrive
650 && $len == length $self->{rbuf} # and no data has been consumed 650 $len == length $self->{rbuf} # if no data has been consumed
651 && !@{ $self->{_queue} } # and the queue is still empty 651 && !@{ $self->{_queue} } # and the queue is still empty
652 && $self->{on_read} # and we still want to read data 652 && $self->{on_read} # but we still have on_read
653 ) { 653 ) {
654 # no further data will arrive
654 # then no progress can be made 655 # so no progress can be made
655 $! = &Errno::EPIPE; 656 return $self->_error (&Errno::EPIPE, 1)
656 $self->error; 657 if $self->{_eof};
658
659 last; # more data might arrive
657 } 660 }
658 } else { 661 } else {
659 # read side becomes idle 662 # read side becomes idle
660 delete $self->{_rw}; 663 delete $self->{_rw};
661 return; 664 last;
662 } 665 }
663 } 666 }
664 667
665 if ($self->{_eof}) {
666 $self->_shutdown;
667 $self->{on_eof}($self) 668 $self->{on_eof}($self)
668 if $self->{on_eof}; 669 if $self->{_eof} && $self->{on_eof};
670
671 # may need to restart read watcher
672 unless ($self->{_rw}) {
673 $self->start_read
674 if $self->{on_read} || @{ $self->{_queue} };
669 } 675 }
670} 676}
671 677
672=item $handle->on_read ($cb) 678=item $handle->on_read ($cb)
673 679
… …
863 my ($self, $cb) = @_; 869 my ($self, $cb) = @_;
864 870
865 sub { 871 sub {
866 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) { 872 unless ($_[0]{rbuf} =~ s/^(0|[1-9][0-9]*)://) {
867 if ($_[0]{rbuf} =~ /[^0-9]/) { 873 if ($_[0]{rbuf} =~ /[^0-9]/) {
868 $! = &Errno::EBADMSG; 874 $self->_error (&Errno::EBADMSG);
869 $self->error;
870 } 875 }
871 return; 876 return;
872 } 877 }
873 878
874 my $len = $1; 879 my $len = $1;
… …
877 my $string = $_[1]; 882 my $string = $_[1];
878 $_[0]->unshift_read (chunk => 1, sub { 883 $_[0]->unshift_read (chunk => 1, sub {
879 if ($_[1] eq ",") { 884 if ($_[1] eq ",") {
880 $cb->($_[0], $string); 885 $cb->($_[0], $string);
881 } else { 886 } else {
882 $! = &Errno::EBADMSG; 887 $self->_error (&Errno::EBADMSG);
883 $self->error;
884 } 888 }
885 }); 889 });
886 }); 890 });
887 891
888 1 892 1
… …
945 return 1; 949 return 1;
946 } 950 }
947 951
948 # reject 952 # reject
949 if ($reject && $$rbuf =~ $reject) { 953 if ($reject && $$rbuf =~ $reject) {
950 $! = &Errno::EBADMSG; 954 $self->_error (&Errno::EBADMSG);
951 $self->error;
952 } 955 }
953 956
954 # skip 957 # skip
955 if ($skip && $$rbuf =~ $skip) { 958 if ($skip && $$rbuf =~ $skip) {
956 $data .= substr $$rbuf, 0, $+[0], ""; 959 $data .= substr $$rbuf, 0, $+[0], "";
… …
1055 1058
1056 if ($len > 0) { 1059 if ($len > 0) {
1057 $self->{_activity} = AnyEvent->now; 1060 $self->{_activity} = AnyEvent->now;
1058 1061
1059 $self->{filter_r} 1062 $self->{filter_r}
1060 ? $self->{filter_r}->($self, $rbuf) 1063 ? $self->{filter_r}($self, $rbuf)
1061 : $self->_drain_rbuf; 1064 : $self->_drain_rbuf;
1062 1065
1063 } elsif (defined $len) { 1066 } elsif (defined $len) {
1064 delete $self->{_rw}; 1067 delete $self->{_rw};
1065 delete $self->{_ww};
1066 delete $self->{_tw};
1067 $self->{_eof} = 1; 1068 $self->{_eof} = 1;
1068 $self->_drain_rbuf; 1069 $self->_drain_rbuf;
1069 1070
1070 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) { 1071 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
1071 return $self->error; 1072 return $self->_error ($!, 1);
1072 } 1073 }
1073 }); 1074 });
1074 } 1075 }
1075} 1076}
1076 1077
… …
1095 1096
1096 my $err = Net::SSLeay::get_error ($self->{tls}, -1); 1097 my $err = Net::SSLeay::get_error ($self->{tls}, -1);
1097 1098
1098 if ($err!= Net::SSLeay::ERROR_WANT_READ ()) { 1099 if ($err!= Net::SSLeay::ERROR_WANT_READ ()) {
1099 if ($err == Net::SSLeay::ERROR_SYSCALL ()) { 1100 if ($err == Net::SSLeay::ERROR_SYSCALL ()) {
1100 $self->error; 1101 return $self->_error ($!, 1);
1101 } elsif ($err == Net::SSLeay::ERROR_SSL ()) { 1102 } elsif ($err == Net::SSLeay::ERROR_SSL ()) {
1102 $! = &Errno::EIO; 1103 return $self->_error (&Errno::EIO, 1);
1103 $self->error;
1104 } 1104 }
1105 1105
1106 # all others are fine for our purposes 1106 # all others are fine for our purposes
1107 } 1107 }
1108} 1108}
… …
1123call and can be used or changed to your liking. Note that the handshake 1123call and can be used or changed to your liking. Note that the handshake
1124might have already started when this function returns. 1124might have already started when this function returns.
1125 1125
1126=cut 1126=cut
1127 1127
1128# TODO: maybe document...
1129sub starttls { 1128sub starttls {
1130 my ($self, $ssl, $ctx) = @_; 1129 my ($self, $ssl, $ctx) = @_;
1131 1130
1132 $self->stoptls; 1131 $self->stoptls;
1133 1132

Diff Legend

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