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.80 by root, Sun Jul 27 08:43:32 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 I<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.
87 96
88If an EOF condition has been detected but no C<on_eof> callback has been 97If an EOF condition has been detected but no C<on_eof> callback has been
… …
93This is the error callback, which is called when, well, some error 102This is the error callback, which is called when, well, some error
94occured, such as not being able to resolve the hostname, failure to 103occured, such as not being able to resolve the hostname, failure to
95connect or a read error. 104connect or a read error.
96 105
97Some 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
98fatal 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
99usable. 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
100recommended to simply ignore this parameter and instead abondon the handle 113to simply ignore this parameter and instead abondon the handle object
101object 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>).
102 116
103On callback entrance, the value of C<$!> contains the operating system 117On callback entrance, the value of C<$!> contains the operating system
104error (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT> or C<EBADMSG>). 118error (or C<ENOSPC>, C<EPIPE>, C<ETIMEDOUT> or C<EBADMSG>).
105 119
106While 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
… …
291 delete $self->{_rw}; 305 delete $self->{_rw};
292 delete $self->{_ww}; 306 delete $self->{_ww};
293 delete $self->{fh}; 307 delete $self->{fh};
294 308
295 $self->stoptls; 309 $self->stoptls;
310
311 delete $self->{on_read};
312 delete $self->{_queue};
296} 313}
297 314
298sub _error { 315sub _error {
299 my ($self, $errno, $fatal) = @_; 316 my ($self, $errno, $fatal) = @_;
300 317
… …
729 746
730 if ( 747 if (
731 defined $self->{rbuf_max} 748 defined $self->{rbuf_max}
732 && $self->{rbuf_max} < length $self->{rbuf} 749 && $self->{rbuf_max} < length $self->{rbuf}
733 ) { 750 ) {
734 return $self->_error (&Errno::ENOSPC, 1); 751 $self->_error (&Errno::ENOSPC, 1), return;
735 } 752 }
736 753
737 while () { 754 while () {
738 my $len = length $self->{rbuf}; 755 my $len = length $self->{rbuf};
739 756
740 if (my $cb = shift @{ $self->{_queue} }) { 757 if (my $cb = shift @{ $self->{_queue} }) {
741 unless ($cb->($self)) { 758 unless ($cb->($self)) {
742 if ($self->{_eof}) { 759 if ($self->{_eof}) {
743 # 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)
744 $self->_error (&Errno::EPIPE, 1), last; 761 $self->_error (&Errno::EPIPE, 1), return;
745 } 762 }
746 763
747 unshift @{ $self->{_queue} }, $cb; 764 unshift @{ $self->{_queue} }, $cb;
748 last; 765 last;
749 } 766 }
… …
757 && !@{ $self->{_queue} } # and the queue is still empty 774 && !@{ $self->{_queue} } # and the queue is still empty
758 && $self->{on_read} # but we still have on_read 775 && $self->{on_read} # but we still have on_read
759 ) { 776 ) {
760 # no further data will arrive 777 # no further data will arrive
761 # so no progress can be made 778 # so no progress can be made
762 $self->_error (&Errno::EPIPE, 1), last 779 $self->_error (&Errno::EPIPE, 1), return
763 if $self->{_eof}; 780 if $self->{_eof};
764 781
765 last; # more data might arrive 782 last; # more data might arrive
766 } 783 }
767 } else { 784 } else {

Diff Legend

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