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.29 by root, Sat May 24 23:10:18 2008 UTC vs.
Revision 1.38 by root, Mon May 26 21:28:33 2008 UTC

… …
2 2
3no warnings; 3no warnings;
4use strict; 4use strict;
5 5
6use AnyEvent (); 6use AnyEvent ();
7use AnyEvent::Util (); 7use AnyEvent::Util qw(WSAWOULDBLOCK);
8use Scalar::Util (); 8use Scalar::Util ();
9use Carp (); 9use Carp ();
10use Fcntl (); 10use Fcntl ();
11use Errno qw/EAGAIN EINTR/; 11use Errno qw/EAGAIN EINTR/;
12 12
13=head1 NAME 13=head1 NAME
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
17This module is experimental.
18
19=cut 17=cut
20 18
21our $VERSION = '0.04'; 19our $VERSION = '0.04';
22 20
23=head1 SYNOPSIS 21=head1 SYNOPSIS
… …
25 use AnyEvent; 23 use AnyEvent;
26 use AnyEvent::Handle; 24 use AnyEvent::Handle;
27 25
28 my $cv = AnyEvent->condvar; 26 my $cv = AnyEvent->condvar;
29 27
30 my $ae_fh = AnyEvent::Handle->new (fh => \*STDIN); 28 my $handle =
31
32 #TODO
33
34 # or use the constructor to pass the callback:
35
36 my $ae_fh2 =
37 AnyEvent::Handle->new ( 29 AnyEvent::Handle->new (
38 fh => \*STDIN, 30 fh => \*STDIN,
39 on_eof => sub { 31 on_eof => sub {
40 $cv->broadcast; 32 $cv->broadcast;
41 }, 33 },
42 #TODO
43 ); 34 );
44 35
45 $cv->wait; 36 # send some request line
37 $handle->push_write ("getinfo\015\012");
38
39 # read the response line
40 $handle->push_read (line => sub {
41 my ($handle, $line) = @_;
42 warn "read line <$line>\n";
43 $cv->send;
44 });
45
46 $cv->recv;
46 47
47=head1 DESCRIPTION 48=head1 DESCRIPTION
48 49
49This 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
50filehandles. For utility functions for doing non-blocking connects and accepts 51filehandles. For utility functions for doing non-blocking connects and accepts
… …
91The object will not be in a usable state when this callback has been 92The object will not be in a usable state when this callback has been
92called. 93called.
93 94
94On callback entrance, the value of C<$!> contains the operating system 95On callback entrance, the value of C<$!> contains the operating system
95error (or C<ENOSPC>, C<EPIPE> or C<EBADMSG>). 96error (or C<ENOSPC>, C<EPIPE> or C<EBADMSG>).
97
98The callback should throw an exception. If it returns, then
99AnyEvent::Handle will C<croak> for you.
96 100
97While not mandatory, it is I<highly> recommended to set this callback, as 101While not mandatory, it is I<highly> recommended to set this callback, as
98you will not be notified of errors otherwise. The default simply calls 102you will not be notified of errors otherwise. The default simply calls
99die. 103die.
100 104
… …
164 168
165Use the given Net::SSLeay::CTX object to create the new TLS connection 169Use the given Net::SSLeay::CTX object to create the new TLS connection
166(unless a connection object was specified directly). If this parameter is 170(unless a connection object was specified directly). If this parameter is
167missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>. 171missing, then AnyEvent::Handle will use C<AnyEvent::Handle::TLS_CTX>.
168 172
173=item filter_r => $cb
174
175=item filter_w => $cb
176
177These exist, but are undocumented at this time.
178
169=back 179=back
170 180
171=cut 181=cut
172
173our (%RH, %WH);
174
175sub register_read_type($$) {
176 $RH{$_[0]} = $_[1];
177}
178
179sub register_write_type($$) {
180 $WH{$_[0]} = $_[1];
181}
182 182
183sub new { 183sub new {
184 my $class = shift; 184 my $class = shift;
185 185
186 my $self = bless { @_ }, $class; 186 my $self = bless { @_ }, $class;
… …
205} 205}
206 206
207sub _shutdown { 207sub _shutdown {
208 my ($self) = @_; 208 my ($self) = @_;
209 209
210 delete $self->{rw}; 210 delete $self->{_rw};
211 delete $self->{ww}; 211 delete $self->{_ww};
212 delete $self->{fh}; 212 delete $self->{fh};
213} 213}
214 214
215sub error { 215sub error {
216 my ($self) = @_; 216 my ($self) = @_;
… …
218 { 218 {
219 local $!; 219 local $!;
220 $self->_shutdown; 220 $self->_shutdown;
221 } 221 }
222 222
223 if ($self->{on_error}) {
224 $self->{on_error}($self); 223 $self->{on_error}($self)
225 } else { 224 if $self->{on_error};
225
226 Carp::croak "AnyEvent::Handle uncaught fatal error: $!"; 226 Carp::croak "AnyEvent::Handle uncaught fatal error: $!";
227 }
228} 227}
229 228
230=item $fh = $handle->fh 229=item $fh = $handle->fh
231 230
232This method returns the file handle of the L<AnyEvent::Handle> object. 231This method returns the file handle of the L<AnyEvent::Handle> object.
233 232
234=cut 233=cut
235 234
236sub fh { $_[0]->{fh} } 235sub fh { $_[0]{fh} }
237 236
238=item $handle->on_error ($cb) 237=item $handle->on_error ($cb)
239 238
240Replace the current C<on_error> callback (see the C<on_error> constructor argument). 239Replace the current C<on_error> callback (see the C<on_error> constructor argument).
241 240
… …
297=cut 296=cut
298 297
299sub _drain_wbuf { 298sub _drain_wbuf {
300 my ($self) = @_; 299 my ($self) = @_;
301 300
302 if (!$self->{ww} && length $self->{wbuf}) { 301 if (!$self->{_ww} && length $self->{wbuf}) {
302
303 Scalar::Util::weaken $self; 303 Scalar::Util::weaken $self;
304
304 my $cb = sub { 305 my $cb = sub {
305 my $len = syswrite $self->{fh}, $self->{wbuf}; 306 my $len = syswrite $self->{fh}, $self->{wbuf};
306 307
307 if ($len >= 0) { 308 if ($len >= 0) {
308 substr $self->{wbuf}, 0, $len, ""; 309 substr $self->{wbuf}, 0, $len, "";
309 310
310 $self->{on_drain}($self) 311 $self->{on_drain}($self)
311 if $self->{low_water_mark} >= length $self->{wbuf} 312 if $self->{low_water_mark} >= length $self->{wbuf}
312 && $self->{on_drain}; 313 && $self->{on_drain};
313 314
314 delete $self->{ww} unless length $self->{wbuf}; 315 delete $self->{_ww} unless length $self->{wbuf};
315 } elsif ($! != EAGAIN && $! != EINTR) { 316 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAWOULDBLOCK) {
316 $self->error; 317 $self->error;
317 } 318 }
318 }; 319 };
319 320
321 # try to write data immediately
322 $cb->();
323
324 # if still data left in wbuf, we need to poll
320 $self->{ww} = AnyEvent->io (fh => $self->{fh}, poll => "w", cb => $cb); 325 $self->{_ww} = AnyEvent->io (fh => $self->{fh}, poll => "w", cb => $cb)
321 326 if length $self->{wbuf};
322 $cb->($self);
323 }; 327 };
328}
329
330our %WH;
331
332sub register_write_type($$) {
333 $WH{$_[0]} = $_[1];
324} 334}
325 335
326sub push_write { 336sub push_write {
327 my $self = shift; 337 my $self = shift;
328 338
… …
346=item $handle->unshift_write (type => @args) 356=item $handle->unshift_write (type => @args)
347 357
348Instead of formatting your data yourself, you can also let this module do 358Instead of formatting your data yourself, you can also let this module do
349the job by specifying a type and type-specific arguments. 359the job by specifying a type and type-specific arguments.
350 360
351Predefined types are: 361Predefined types are (if you have ideas for additional types, feel free to
362drop by and tell us):
352 363
353=over 4 364=over 4
354 365
355=item netstring => $string 366=item netstring => $string
356 367
357Formats the given value as netstring 368Formats the given value as netstring
358(http://cr.yp.to/proto/netstrings.txt, this is not a recommendation to use them). 369(http://cr.yp.to/proto/netstrings.txt, this is not a recommendation to use them).
359 370
371=back
372
360=cut 373=cut
361 374
362register_write_type netstring => sub { 375register_write_type netstring => sub {
363 my ($self, $string) = @_; 376 my ($self, $string) = @_;
364 377
365 sprintf "%d:%s,", (length $string), $string 378 sprintf "%d:%s,", (length $string), $string
366}; 379};
367 380
368=back 381=item AnyEvent::Handle::register_write_type type => $coderef->($self, @args)
369 382
370=cut 383This function (not method) lets you add your own types to C<push_write>.
384Whenever the given C<type> is used, C<push_write> will invoke the code
385reference with the handle object and the remaining arguments.
371 386
387The code reference is supposed to return a single octet string that will
388be appended to the write buffer.
372 389
390Note that this is a function, and all types registered this way will be
391global, so try to use unique names.
392
393=cut
373 394
374############################################################################# 395#############################################################################
375 396
376=back 397=back
377 398
… …
456 477
457 if ( 478 if (
458 defined $self->{rbuf_max} 479 defined $self->{rbuf_max}
459 && $self->{rbuf_max} < length $self->{rbuf} 480 && $self->{rbuf_max} < length $self->{rbuf}
460 ) { 481 ) {
461 $! = &Errno::ENOSPC; return $self->error; 482 $! = &Errno::ENOSPC;
483 $self->error;
462 } 484 }
463 485
464 return if $self->{in_drain}; 486 return if $self->{in_drain};
465 local $self->{in_drain} = 1; 487 local $self->{in_drain} = 1;
466 488
467 while (my $len = length $self->{rbuf}) { 489 while (my $len = length $self->{rbuf}) {
468 no strict 'refs'; 490 no strict 'refs';
469 if (my $cb = shift @{ $self->{queue} }) { 491 if (my $cb = shift @{ $self->{_queue} }) {
470 unless ($cb->($self)) { 492 unless ($cb->($self)) {
471 if ($self->{eof}) { 493 if ($self->{_eof}) {
472 # no progress can be made (not enough data and no data forthcoming) 494 # no progress can be made (not enough data and no data forthcoming)
473 $! = &Errno::EPIPE; return $self->error; 495 $! = &Errno::EPIPE;
496 $self->error;
474 } 497 }
475 498
476 unshift @{ $self->{queue} }, $cb; 499 unshift @{ $self->{_queue} }, $cb;
477 return; 500 return;
478 } 501 }
479 } elsif ($self->{on_read}) { 502 } elsif ($self->{on_read}) {
480 $self->{on_read}($self); 503 $self->{on_read}($self);
481 504
482 if ( 505 if (
483 $self->{eof} # if no further data will arrive 506 $self->{_eof} # if no further data will arrive
484 && $len == length $self->{rbuf} # and no data has been consumed 507 && $len == length $self->{rbuf} # and no data has been consumed
485 && !@{ $self->{queue} } # and the queue is still empty 508 && !@{ $self->{_queue} } # and the queue is still empty
486 && $self->{on_read} # and we still want to read data 509 && $self->{on_read} # and we still want to read data
487 ) { 510 ) {
488 # then no progress can be made 511 # then no progress can be made
489 $! = &Errno::EPIPE; return $self->error; 512 $! = &Errno::EPIPE;
513 $self->error;
490 } 514 }
491 } else { 515 } else {
492 # read side becomes idle 516 # read side becomes idle
493 delete $self->{rw}; 517 delete $self->{_rw};
494 return; 518 return;
495 } 519 }
496 } 520 }
497 521
498 if ($self->{eof}) { 522 if ($self->{_eof}) {
499 $self->_shutdown; 523 $self->_shutdown;
500 $self->{on_eof}($self) 524 $self->{on_eof}($self)
501 if $self->{on_eof}; 525 if $self->{on_eof};
502 } 526 }
503} 527}
… …
552interested in (which can be none at all) and return a true value. After returning 576interested in (which can be none at all) and return a true value. After returning
553true, it will be removed from the queue. 577true, it will be removed from the queue.
554 578
555=cut 579=cut
556 580
581our %RH;
582
583sub register_read_type($$) {
584 $RH{$_[0]} = $_[1];
585}
586
557sub push_read { 587sub push_read {
558 my $self = shift; 588 my $self = shift;
559 my $cb = pop; 589 my $cb = pop;
560 590
561 if (@_) { 591 if (@_) {
… …
563 593
564 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_read") 594 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_read")
565 ->($self, $cb, @_); 595 ->($self, $cb, @_);
566 } 596 }
567 597
568 push @{ $self->{queue} }, $cb; 598 push @{ $self->{_queue} }, $cb;
569 $self->_drain_rbuf; 599 $self->_drain_rbuf;
570} 600}
571 601
572sub unshift_read { 602sub unshift_read {
573 my $self = shift; 603 my $self = shift;
… …
579 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::unshift_read") 609 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::unshift_read")
580 ->($self, $cb, @_); 610 ->($self, $cb, @_);
581 } 611 }
582 612
583 613
584 unshift @{ $self->{queue} }, $cb; 614 unshift @{ $self->{_queue} }, $cb;
585 $self->_drain_rbuf; 615 $self->_drain_rbuf;
586} 616}
587 617
588=item $handle->push_read (type => @args, $cb) 618=item $handle->push_read (type => @args, $cb)
589 619
… …
591 621
592Instead of providing a callback that parses the data itself you can chose 622Instead of providing a callback that parses the data itself you can chose
593between a number of predefined parsing formats, for chunks of data, lines 623between a number of predefined parsing formats, for chunks of data, lines
594etc. 624etc.
595 625
596The types currently supported are: 626Predefined types are (if you have ideas for additional types, feel free to
627drop by and tell us):
597 628
598=over 4 629=over 4
599 630
600=item chunk => $octets, $cb->($self, $data) 631=item chunk => $octets, $cb->($self, $data)
601 632
… …
713 744
714 1 745 1
715 } 746 }
716}; 747};
717 748
749=item regex => $accept[, $reject[, $skip], $cb->($data)
750
751Makes a regex match against the regex object C<$accept> and returns
752everything up to and including the match.
753
754Example: read a single line terminated by '\n'.
755
756 $handle->push_read (regex => qr<\n>, sub { ... });
757
758If C<$reject> is given and not undef, then it determines when the data is
759to be rejected: it is matched against the data when the C<$accept> regex
760does not match and generates an C<EBADMSG> error when it matches. This is
761useful to quickly reject wrong data (to avoid waiting for a timeout or a
762receive buffer overflow).
763
764Example: expect a single decimal number followed by whitespace, reject
765anything else (not the use of an anchor).
766
767 $handle->push_read (regex => qr<^[0-9]+\s>, qr<[^0-9]>, sub { ... });
768
769If C<$skip> is given and not C<undef>, then it will be matched against
770the receive buffer when neither C<$accept> nor C<$reject> match,
771and everything preceding and including the match will be accepted
772unconditionally. This is useful to skip large amounts of data that you
773know cannot be matched, so that the C<$accept> or C<$reject> regex do not
774have to start matching from the beginning. This is purely an optimisation
775and is usually worth only when you expect more than a few kilobytes.
776
777Example: expect a http header, which ends at C<\015\012\015\012>. Since we
778expect the header to be very large (it isn't in practise, but...), we use
779a skip regex to skip initial portions. The skip regex is tricky in that
780it only accepts something not ending in either \015 or \012, as these are
781required for the accept regex.
782
783 $handle->push_read (regex =>
784 qr<\015\012\015\012>,
785 undef, # no reject
786 qr<^.*[^\015\012]>,
787 sub { ... });
788
789=cut
790
791register_read_type regex => sub {
792 my ($self, $cb, $accept, $reject, $skip) = @_;
793
794 my $data;
795 my $rbuf = \$self->{rbuf};
796
797 sub {
798 # accept
799 if ($$rbuf =~ $accept) {
800 $data .= substr $$rbuf, 0, $+[0], "";
801 $cb->($self, $data);
802 return 1;
803 }
804
805 # reject
806 if ($reject && $$rbuf =~ $reject) {
807 $! = &Errno::EBADMSG;
808 $self->error;
809 }
810
811 # skip
812 if ($skip && $$rbuf =~ $skip) {
813 $data .= substr $$rbuf, 0, $+[0], "";
814 }
815
816 ()
817 }
818};
819
718=back 820=back
821
822=item AnyEvent::Handle::register_read_type type => $coderef->($self, $cb, @args)
823
824This function (not method) lets you add your own types to C<push_read>.
825
826Whenever the given C<type> is used, C<push_read> will invoke the code
827reference with the handle object, the callback and the remaining
828arguments.
829
830The code reference is supposed to return a callback (usually a closure)
831that works as a plain read callback (see C<< ->push_read ($cb) >>).
832
833It should invoke the passed callback when it is done reading (remember to
834pass C<$self> as first argument as all other callbacks do that).
835
836Note that this is a function, and all types registered this way will be
837global, so try to use unique names.
838
839For examples, see the source of this module (F<perldoc -m AnyEvent::Handle>,
840search for C<register_read_type>)).
719 841
720=item $handle->stop_read 842=item $handle->stop_read
721 843
722=item $handle->start_read 844=item $handle->start_read
723 845
… …
729=cut 851=cut
730 852
731sub stop_read { 853sub stop_read {
732 my ($self) = @_; 854 my ($self) = @_;
733 855
734 delete $self->{rw}; 856 delete $self->{_rw};
735} 857}
736 858
737sub start_read { 859sub start_read {
738 my ($self) = @_; 860 my ($self) = @_;
739 861
740 unless ($self->{rw} || $self->{eof}) { 862 unless ($self->{_rw} || $self->{_eof}) {
741 Scalar::Util::weaken $self; 863 Scalar::Util::weaken $self;
742 864
743 $self->{rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub { 865 $self->{_rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub {
744 my $rbuf = $self->{filter_r} ? \my $buf : \$self->{rbuf}; 866 my $rbuf = $self->{filter_r} ? \my $buf : \$self->{rbuf};
745 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf; 867 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf;
746 868
747 if ($len > 0) { 869 if ($len > 0) {
748 $self->{filter_r} 870 $self->{filter_r}
749 ? $self->{filter_r}->($self, $rbuf) 871 ? $self->{filter_r}->($self, $rbuf)
750 : $self->_drain_rbuf; 872 : $self->_drain_rbuf;
751 873
752 } elsif (defined $len) { 874 } elsif (defined $len) {
753 delete $self->{rw}; 875 delete $self->{_rw};
754 $self->{eof} = 1; 876 $self->{_eof} = 1;
755 $self->_drain_rbuf; 877 $self->_drain_rbuf;
756 878
757 } elsif ($! != EAGAIN && $! != EINTR) { 879 } elsif ($! != EAGAIN && $! != EINTR && $! != &AnyEvent::Util::WSAWOULDBLOCK) {
758 return $self->error; 880 return $self->error;
759 } 881 }
760 }); 882 });
761 } 883 }
762} 884}
763 885
764sub _dotls { 886sub _dotls {
765 my ($self) = @_; 887 my ($self) = @_;
766 888
767 if (length $self->{tls_wbuf}) { 889 if (length $self->{_tls_wbuf}) {
768 while ((my $len = Net::SSLeay::write ($self->{tls}, $self->{tls_wbuf})) > 0) { 890 while ((my $len = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
769 substr $self->{tls_wbuf}, 0, $len, ""; 891 substr $self->{_tls_wbuf}, 0, $len, "";
770 } 892 }
771 } 893 }
772 894
773 if (defined (my $buf = Net::SSLeay::BIO_read ($self->{tls_wbio}))) { 895 if (defined (my $buf = Net::SSLeay::BIO_read ($self->{_wbio}))) {
774 $self->{wbuf} .= $buf; 896 $self->{wbuf} .= $buf;
775 $self->_drain_wbuf; 897 $self->_drain_wbuf;
776 } 898 }
777 899
778 while (defined (my $buf = Net::SSLeay::read ($self->{tls}))) { 900 while (defined (my $buf = Net::SSLeay::read ($self->{tls}))) {
… …
804C<"connect">, C<"accept"> or an existing Net::SSLeay object). 926C<"connect">, C<"accept"> or an existing Net::SSLeay object).
805 927
806The second argument is the optional C<Net::SSLeay::CTX> object that is 928The second argument is the optional C<Net::SSLeay::CTX> object that is
807used when AnyEvent::Handle has to create its own TLS connection object. 929used when AnyEvent::Handle has to create its own TLS connection object.
808 930
931The TLS connection object will end up in C<< $handle->{tls} >> after this
932call and can be used or changed to your liking. Note that the handshake
933might have already started when this function returns.
934
809=cut 935=cut
810 936
811# TODO: maybe document... 937# TODO: maybe document...
812sub starttls { 938sub starttls {
813 my ($self, $ssl, $ctx) = @_; 939 my ($self, $ssl, $ctx) = @_;
… …
828 # but the openssl maintainers basically said: "trust us, it just works". 954 # but the openssl maintainers basically said: "trust us, it just works".
829 # (unfortunately, we have to hardcode constants because the abysmally misdesigned 955 # (unfortunately, we have to hardcode constants because the abysmally misdesigned
830 # and mismaintained ssleay-module doesn't even offer them). 956 # and mismaintained ssleay-module doesn't even offer them).
831 # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html 957 # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html
832 Net::SSLeay::CTX_set_mode ($self->{tls}, 958 Net::SSLeay::CTX_set_mode ($self->{tls},
833 (eval { Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1) 959 (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1)
834 | (eval { Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2)); 960 | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2));
835 961
836 $self->{tls_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 962 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
837 $self->{tls_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 963 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
838 964
839 Net::SSLeay::set_bio ($ssl, $self->{tls_rbio}, $self->{tls_wbio}); 965 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});
840 966
841 $self->{filter_w} = sub { 967 $self->{filter_w} = sub {
842 $_[0]{tls_wbuf} .= ${$_[1]}; 968 $_[0]{_tls_wbuf} .= ${$_[1]};
843 &_dotls; 969 &_dotls;
844 }; 970 };
845 $self->{filter_r} = sub { 971 $self->{filter_r} = sub {
846 Net::SSLeay::BIO_write ($_[0]{tls_rbio}, ${$_[1]}); 972 Net::SSLeay::BIO_write ($_[0]{_rbio}, ${$_[1]});
847 &_dotls; 973 &_dotls;
848 }; 974 };
849} 975}
850 976
851=item $handle->stoptls 977=item $handle->stoptls
… …
857 983
858sub stoptls { 984sub stoptls {
859 my ($self) = @_; 985 my ($self) = @_;
860 986
861 Net::SSLeay::free (delete $self->{tls}) if $self->{tls}; 987 Net::SSLeay::free (delete $self->{tls}) if $self->{tls};
988
862 delete $self->{tls_rbio}; 989 delete $self->{_rbio};
863 delete $self->{tls_wbio}; 990 delete $self->{_wbio};
864 delete $self->{tls_wbuf}; 991 delete $self->{_tls_wbuf};
865 delete $self->{filter_r}; 992 delete $self->{filter_r};
866 delete $self->{filter_w}; 993 delete $self->{filter_w};
867} 994}
868 995
869sub DESTROY { 996sub DESTROY {
… …
907 } 1034 }
908} 1035}
909 1036
910=back 1037=back
911 1038
1039=head1 SUBCLASSING AnyEvent::Handle
1040
1041In many cases, you might want to subclass AnyEvent::Handle.
1042
1043To make this easier, a given version of AnyEvent::Handle uses these
1044conventions:
1045
1046=over 4
1047
1048=item * all constructor arguments become object members.
1049
1050At least initially, when you pass a C<tls>-argument to the constructor it
1051will end up in C<< $handle->{tls} >>. Those members might be changes or
1052mutated later on (for example C<tls> will hold the TLS connection object).
1053
1054=item * other object member names are prefixed with an C<_>.
1055
1056All object members not explicitly documented (internal use) are prefixed
1057with an underscore character, so the remaining non-C<_>-namespace is free
1058for use for subclasses.
1059
1060=item * all members not documented here and not prefixed with an underscore
1061are free to use in subclasses.
1062
1063Of course, new versions of AnyEvent::Handle may introduce more "public"
1064member variables, but thats just life, at least it is documented.
1065
1066=back
1067
912=head1 AUTHOR 1068=head1 AUTHOR
913 1069
914Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>. 1070Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>.
915 1071
916=cut 1072=cut

Diff Legend

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