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.81 by root, Wed Aug 20 12:37:21 2008 UTC vs.
Revision 1.85 by root, Thu Aug 21 19:53:19 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.231; 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
… …
213This will not work for partial TLS data that could not yet been 227This will not work for partial TLS data that could not yet been
214encoded. This data will be lost. 228encoded. This data will be lost.
215 229
216=item tls => "accept" | "connect" | Net::SSLeay::SSL object 230=item tls => "accept" | "connect" | Net::SSLeay::SSL object
217 231
218When this parameter is given, it enables TLS (SSL) mode, that means it 232When this parameter is given, it enables TLS (SSL) mode, that means
219will start making tls handshake and will transparently encrypt/decrypt 233AnyEvent will start a TLS handshake and will transparently encrypt/decrypt
220data. 234data.
221 235
222TLS mode requires Net::SSLeay to be installed (it will be loaded 236TLS mode requires Net::SSLeay to be installed (it will be loaded
223automatically when you try to create a TLS handle). 237automatically when you try to create a TLS handle).
224 238
225For the TLS server side, use C<accept>, and for the TLS client side of a 239Unlike TCP, TLS has a server and client side: for the TLS server side, use
226connection, use C<connect> mode. 240C<accept>, and for the TLS client side of a connection, use C<connect>
241mode.
227 242
228You can also provide your own TLS connection object, but you have 243You can also provide your own TLS connection object, but you have
229to make sure that you call either C<Net::SSLeay::set_connect_state> 244to make sure that you call either C<Net::SSLeay::set_connect_state>
230or C<Net::SSLeay::set_accept_state> on it before you pass it to 245or C<Net::SSLeay::set_accept_state> on it before you pass it to
231AnyEvent::Handle. 246AnyEvent::Handle.
232 247
233See the C<starttls> method if you need to start TLS negotiation later. 248See the C<starttls> method for when need to start TLS negotiation later.
234 249
235=item tls_ctx => $ssl_ctx 250=item tls_ctx => $ssl_ctx
236 251
237Use the given Net::SSLeay::CTX object to create the new TLS connection 252Use the given Net::SSLeay::CTX object to create the new TLS connection
238(unless a connection object was specified directly). If this parameter is 253(unless a connection object was specified directly). If this parameter is
… …
291 delete $self->{_rw}; 306 delete $self->{_rw};
292 delete $self->{_ww}; 307 delete $self->{_ww};
293 delete $self->{fh}; 308 delete $self->{fh};
294 309
295 $self->stoptls; 310 $self->stoptls;
311
312 delete $self->{on_read};
313 delete $self->{_queue};
296} 314}
297 315
298sub _error { 316sub _error {
299 my ($self, $errno, $fatal) = @_; 317 my ($self, $errno, $fatal) = @_;
300 318
… …
729 747
730 if ( 748 if (
731 defined $self->{rbuf_max} 749 defined $self->{rbuf_max}
732 && $self->{rbuf_max} < length $self->{rbuf} 750 && $self->{rbuf_max} < length $self->{rbuf}
733 ) { 751 ) {
734 return $self->_error (&Errno::ENOSPC, 1); 752 $self->_error (&Errno::ENOSPC, 1), return;
735 } 753 }
736 754
737 while () { 755 while () {
738 my $len = length $self->{rbuf}; 756 my $len = length $self->{rbuf};
739 757
740 if (my $cb = shift @{ $self->{_queue} }) { 758 if (my $cb = shift @{ $self->{_queue} }) {
741 unless ($cb->($self)) { 759 unless ($cb->($self)) {
742 if ($self->{_eof}) { 760 if ($self->{_eof}) {
743 # no progress can be made (not enough data and no data forthcoming) 761 # no progress can be made (not enough data and no data forthcoming)
744 $self->_error (&Errno::EPIPE, 1), last; 762 $self->_error (&Errno::EPIPE, 1), return;
745 } 763 }
746 764
747 unshift @{ $self->{_queue} }, $cb; 765 unshift @{ $self->{_queue} }, $cb;
748 last; 766 last;
749 } 767 }
… …
757 && !@{ $self->{_queue} } # and the queue is still empty 775 && !@{ $self->{_queue} } # and the queue is still empty
758 && $self->{on_read} # but we still have on_read 776 && $self->{on_read} # but we still have on_read
759 ) { 777 ) {
760 # no further data will arrive 778 # no further data will arrive
761 # so no progress can be made 779 # so no progress can be made
762 $self->_error (&Errno::EPIPE, 1), last 780 $self->_error (&Errno::EPIPE, 1), return
763 if $self->{_eof}; 781 if $self->{_eof};
764 782
765 last; # more data might arrive 783 last; # more data might arrive
766 } 784 }
767 } else { 785 } else {

Diff Legend

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