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.79 by root, Sun Jul 27 08:37:56 2008 UTC vs.
Revision 1.84 by root, Thu Aug 21 19:13:05 2008 UTC

… …
14 14
15AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent 15AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent
16 16
17=cut 17=cut
18 18
19our $VERSION = 4.22; 19our $VERSION = 4.232;
20 20
21=head1 SYNOPSIS 21=head1 SYNOPSIS
22 22
23 use AnyEvent; 23 use AnyEvent;
24 use AnyEvent::Handle; 24 use AnyEvent::Handle;
… …
49 49
50This module is a helper module to make it easier to do event-based I/O on 50This module is a helper module to make it easier to do event-based I/O on
51filehandles. For utility functions for doing non-blocking connects and accepts 51filehandles. For utility functions for doing non-blocking connects and accepts
52on sockets see L<AnyEvent::Util>. 52on sockets see L<AnyEvent::Util>.
53 53
54The L<AnyEvent::Intro> tutorial contains some well-documented
55AnyEvent::Handle examples.
56
54In the following, when the documentation refers to of "bytes" then this 57In the following, when the documentation refers to of "bytes" then this
55means characters. As sysread and syswrite are used for all I/O, their 58means characters. As sysread and syswrite are used for all I/O, their
56treatment of characters applies to this module as well. 59treatment of characters applies to this module as well.
57 60
58All callbacks will be invoked with the handle object as their first 61All callbacks will be invoked with the handle object as their first
… …
70 73
71=item fh => $filehandle [MANDATORY] 74=item fh => $filehandle [MANDATORY]
72 75
73The filehandle this L<AnyEvent::Handle> object will operate on. 76The filehandle this L<AnyEvent::Handle> object will operate on.
74 77
75NOTE: The filehandle will be set to non-blocking (using 78NOTE: The filehandle will be set to non-blocking mode (using
76AnyEvent::Util::fh_nonblocking). 79C<AnyEvent::Util::fh_nonblocking>) by the constructor and needs to stay in
80that mode.
77 81
78=item on_eof => $cb->($handle) 82=item on_eof => $cb->($handle)
79 83
80Set the callback to be called when an end-of-file condition is detected, 84Set the callback to be called when an end-of-file condition is detected,
81i.e. in the case of a socket, when the other side has closed the 85i.e. in the case of a socket, when the other side has closed the
82connection cleanly. 86connection cleanly.
83 87
88For sockets, this just means that the other side has stopped sending data,
89you can still try to write data, and, in fact, one can return from the eof
90callback and continue writing data, as only the read part has been shut
91down.
92
84While not mandatory, it is highly recommended to set an eof callback, 93While not mandatory, it is I<highly> recommended to set an eof callback,
85otherwise you might end up with a closed socket while you are still 94otherwise you might end up with a closed socket while you are still
86waiting for data. 95waiting for data.
96
97If an EOF condition has been detected but no C<on_eof> callback has been
98set, then a fatal error will be raised with C<$!> set to <0>.
87 99
88=item on_error => $cb->($handle, $fatal) 100=item on_error => $cb->($handle, $fatal)
89 101
90This is the error callback, which is called when, well, some error 102This is the error callback, which is called when, well, some error
91occured, such as not being able to resolve the hostname, failure to 103occured, such as not being able to resolve the hostname, failure to
92connect or a read error. 104connect or a read error.
93 105
94Some errors are fatal (which is indicated by C<$fatal> being true). On 106Some errors are fatal (which is indicated by C<$fatal> being true). On
95fatal errors the handle object will be shut down and will not be 107fatal errors the handle object will be shut down and will not be usable
108(but you are free to look at the current C< ->rbuf >). Examples of fatal
109errors are an EOF condition with active (but unsatisifable) read watchers
110(C<EPIPE>) or I/O errors.
111
96usable. Non-fatal errors can be retried by simply returning, but it is 112Non-fatal errors can be retried by simply returning, but it is recommended
97recommended to simply ignore this parameter and instead abondon the handle 113to simply ignore this parameter and instead abondon the handle object
98object when this callback is invoked. 114when this callback is invoked. Examples of non-fatal errors are timeouts
115C<ETIMEDOUT>) or badly-formatted data (C<EBADMSG>).
99 116
100On callback entrance, the value of C<$!> contains the operating system 117On callback entrance, the value of C<$!> contains the operating system
101error (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT> or C<EBADMSG>). 118error (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT> or C<EBADMSG>).
102 119
103While not mandatory, it is I<highly> recommended to set this callback, as 120While not mandatory, it is I<highly> recommended to set this callback, as
… …
288 delete $self->{_rw}; 305 delete $self->{_rw};
289 delete $self->{_ww}; 306 delete $self->{_ww};
290 delete $self->{fh}; 307 delete $self->{fh};
291 308
292 $self->stoptls; 309 $self->stoptls;
310
311 delete $self->{on_read};
312 delete $self->{_queue};
293} 313}
294 314
295sub _error { 315sub _error {
296 my ($self, $errno, $fatal) = @_; 316 my ($self, $errno, $fatal) = @_;
297 317
… …
726 746
727 if ( 747 if (
728 defined $self->{rbuf_max} 748 defined $self->{rbuf_max}
729 && $self->{rbuf_max} < length $self->{rbuf} 749 && $self->{rbuf_max} < length $self->{rbuf}
730 ) { 750 ) {
731 return $self->_error (&Errno::ENOSPC, 1); 751 $self->_error (&Errno::ENOSPC, 1), return;
732 } 752 }
733 753
734 while () { 754 while () {
735 my $len = length $self->{rbuf}; 755 my $len = length $self->{rbuf};
736 756
737 if (my $cb = shift @{ $self->{_queue} }) { 757 if (my $cb = shift @{ $self->{_queue} }) {
738 unless ($cb->($self)) { 758 unless ($cb->($self)) {
739 if ($self->{_eof}) { 759 if ($self->{_eof}) {
740 # no progress can be made (not enough data and no data forthcoming) 760 # no progress can be made (not enough data and no data forthcoming)
741 $self->_error (&Errno::EPIPE, 1), last; 761 $self->_error (&Errno::EPIPE, 1), return;
742 } 762 }
743 763
744 unshift @{ $self->{_queue} }, $cb; 764 unshift @{ $self->{_queue} }, $cb;
745 last; 765 last;
746 } 766 }
… …
754 && !@{ $self->{_queue} } # and the queue is still empty 774 && !@{ $self->{_queue} } # and the queue is still empty
755 && $self->{on_read} # but we still have on_read 775 && $self->{on_read} # but we still have on_read
756 ) { 776 ) {
757 # no further data will arrive 777 # no further data will arrive
758 # so no progress can be made 778 # so no progress can be made
759 $self->_error (&Errno::EPIPE, 1), last 779 $self->_error (&Errno::EPIPE, 1), return
760 if $self->{_eof}; 780 if $self->{_eof};
761 781
762 last; # more data might arrive 782 last; # more data might arrive
763 } 783 }
764 } else { 784 } else {
… …
766 delete $self->{_rw}; 786 delete $self->{_rw};
767 last; 787 last;
768 } 788 }
769 } 789 }
770 790
791 if ($self->{_eof}) {
792 if ($self->{on_eof}) {
771 $self->{on_eof}($self) 793 $self->{on_eof}($self)
772 if $self->{_eof} && $self->{on_eof}; 794 } else {
795 $self->_error (0, 1);
796 }
797 }
773 798
774 # may need to restart read watcher 799 # may need to restart read watcher
775 unless ($self->{_rw}) { 800 unless ($self->{_rw}) {
776 $self->start_read 801 $self->start_read
777 if $self->{on_read} || @{ $self->{_queue} }; 802 if $self->{on_read} || @{ $self->{_queue} };

Diff Legend

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