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.88 by root, Thu Aug 21 23:48:35 2008 UTC vs.
Revision 1.115 by root, Tue Feb 10 13:58:49 2009 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.233; 19our $VERSION = 4.331;
20 20
21=head1 SYNOPSIS 21=head1 SYNOPSIS
22 22
23 use AnyEvent; 23 use AnyEvent;
24 use AnyEvent::Handle; 24 use AnyEvent::Handle;
… …
27 27
28 my $handle = 28 my $handle =
29 AnyEvent::Handle->new ( 29 AnyEvent::Handle->new (
30 fh => \*STDIN, 30 fh => \*STDIN,
31 on_eof => sub { 31 on_eof => sub {
32 $cv->broadcast; 32 $cv->send;
33 }, 33 },
34 ); 34 );
35 35
36 # send some request line 36 # send some request line
37 $handle->push_write ("getinfo\015\012"); 37 $handle->push_write ("getinfo\015\012");
… …
84Set 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,
85i.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
86connection cleanly. 86connection cleanly.
87 87
88For sockets, this just means that the other side has stopped sending data, 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 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 90callback and continue writing data, as only the read part has been shut
91down. 91down.
92 92
93While 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,
94otherwise 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
95waiting for data. 95waiting for data.
96 96
97If 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
98set, then a fatal error will be raised with C<$!> set to <0>. 98set, then a fatal error will be raised with C<$!> set to <0>.
… …
232write data and will install a watcher that will write this data to the 232write data and will install a watcher that will write this data to the
233socket. No errors will be reported (this mostly matches how the operating 233socket. No errors will be reported (this mostly matches how the operating
234system treats outstanding data at socket close time). 234system treats outstanding data at socket close time).
235 235
236This will not work for partial TLS data that could not be encoded 236This will not work for partial TLS data that could not be encoded
237yet. This data will be lost. 237yet. This data will be lost. Calling the C<stoptls> method in time might
238help.
238 239
239=item tls => "accept" | "connect" | Net::SSLeay::SSL object 240=item tls => "accept" | "connect" | Net::SSLeay::SSL object
240 241
241When this parameter is given, it enables TLS (SSL) mode, that means 242When this parameter is given, it enables TLS (SSL) mode, that means
242AnyEvent will start a TLS handshake as soon as the conenction has been 243AnyEvent will start a TLS handshake as soon as the conenction has been
… …
254You can also provide your own TLS connection object, but you have 255You can also provide your own TLS connection object, but you have
255to make sure that you call either C<Net::SSLeay::set_connect_state> 256to make sure that you call either C<Net::SSLeay::set_connect_state>
256or C<Net::SSLeay::set_accept_state> on it before you pass it to 257or C<Net::SSLeay::set_accept_state> on it before you pass it to
257AnyEvent::Handle. 258AnyEvent::Handle.
258 259
260B<IMPORTANT:> since Net::SSLeay "objects" are really only integers,
261passing in the wrong integer will lead to certain crash. This most often
262happens when one uses a stylish C<< tls => 1 >> and is surprised about the
263segmentation fault.
264
259See the C<< ->starttls >> method for when need to start TLS negotiation later. 265See the C<< ->starttls >> method for when need to start TLS negotiation later.
260 266
261=item tls_ctx => $ssl_ctx 267=item tls_ctx => $ssl_ctx
262 268
263Use the given C<Net::SSLeay::CTX> object to create the new TLS connection 269Use the given C<Net::SSLeay::CTX> object to create the new TLS connection
… …
273texts. 279texts.
274 280
275Note that you are responsible to depend on the JSON module if you want to 281Note that you are responsible to depend on the JSON module if you want to
276use this functionality, as AnyEvent does not have a dependency itself. 282use this functionality, as AnyEvent does not have a dependency itself.
277 283
278=item filter_r => $cb
279
280=item filter_w => $cb
281
282These exist, but are undocumented at this time. (They are used internally
283by the TLS code).
284
285=back 284=back
286 285
287=cut 286=cut
288 287
289sub new { 288sub new {
… …
293 292
294 $self->{fh} or Carp::croak "mandatory argument fh is missing"; 293 $self->{fh} or Carp::croak "mandatory argument fh is missing";
295 294
296 AnyEvent::Util::fh_nonblocking $self->{fh}, 1; 295 AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
297 296
298 if ($self->{tls}) {
299 require Net::SSLeay;
300 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx}); 297 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
301 } 298 if $self->{tls};
302 299
303 $self->{_activity} = AnyEvent->now; 300 $self->{_activity} = AnyEvent->now;
304 $self->_timeout; 301 $self->_timeout;
305 302
306 $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain}; 303 $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain};
… …
318 delete $self->{_tw}; 315 delete $self->{_tw};
319 delete $self->{_rw}; 316 delete $self->{_rw};
320 delete $self->{_ww}; 317 delete $self->{_ww};
321 delete $self->{fh}; 318 delete $self->{fh};
322 319
323 $self->stoptls; 320 &_freetls;
324 321
325 delete $self->{on_read}; 322 delete $self->{on_read};
326 delete $self->{_queue}; 323 delete $self->{_queue};
327} 324}
328 325
… …
334 331
335 $! = $errno; 332 $! = $errno;
336 333
337 if ($self->{on_error}) { 334 if ($self->{on_error}) {
338 $self->{on_error}($self, $fatal); 335 $self->{on_error}($self, $fatal);
339 } else { 336 } elsif ($self->{fh}) {
340 Carp::croak "AnyEvent::Handle uncaught error: $!"; 337 Carp::croak "AnyEvent::Handle uncaught error: $!";
341 } 338 }
342} 339}
343 340
344=item $fh = $handle->fh 341=item $fh = $handle->fh
… …
382} 379}
383 380
384=item $handle->autocork ($boolean) 381=item $handle->autocork ($boolean)
385 382
386Enables or disables the current autocork behaviour (see C<autocork> 383Enables or disables the current autocork behaviour (see C<autocork>
387constructor argument). 384constructor argument). Changes will only take effect on the next write.
388 385
389=cut 386=cut
387
388sub autocork {
389 $_[0]{autocork} = $_[1];
390}
390 391
391=item $handle->no_delay ($boolean) 392=item $handle->no_delay ($boolean)
392 393
393Enables or disables the C<no_delay> setting (see constructor argument of 394Enables or disables the C<no_delay> setting (see constructor argument of
394the same name for details). 395the same name for details).
… …
487 my ($self, $cb) = @_; 488 my ($self, $cb) = @_;
488 489
489 $self->{on_drain} = $cb; 490 $self->{on_drain} = $cb;
490 491
491 $cb->($self) 492 $cb->($self)
492 if $cb && $self->{low_water_mark} >= length $self->{wbuf}; 493 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf});
493} 494}
494 495
495=item $handle->push_write ($data) 496=item $handle->push_write ($data)
496 497
497Queues the given scalar to be written. You can push as much data as you 498Queues the given scalar to be written. You can push as much data as you
… …
514 substr $self->{wbuf}, 0, $len, ""; 515 substr $self->{wbuf}, 0, $len, "";
515 516
516 $self->{_activity} = AnyEvent->now; 517 $self->{_activity} = AnyEvent->now;
517 518
518 $self->{on_drain}($self) 519 $self->{on_drain}($self)
519 if $self->{low_water_mark} >= length $self->{wbuf} 520 if $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf})
520 && $self->{on_drain}; 521 && $self->{on_drain};
521 522
522 delete $self->{_ww} unless length $self->{wbuf}; 523 delete $self->{_ww} unless length $self->{wbuf};
523 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) { 524 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
524 $self->_error ($!, 1); 525 $self->_error ($!, 1);
… …
548 549
549 @_ = ($WH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_write") 550 @_ = ($WH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_write")
550 ->($self, @_); 551 ->($self, @_);
551 } 552 }
552 553
553 if ($self->{filter_w}) { 554 if ($self->{tls}) {
554 $self->{filter_w}($self, \$_[0]); 555 $self->{_tls_wbuf} .= $_[0];
556
557 &_dotls ($self);
555 } else { 558 } else {
556 $self->{wbuf} .= $_[0]; 559 $self->{wbuf} .= $_[0];
557 $self->_drain_wbuf; 560 $self->_drain_wbuf;
558 } 561 }
559} 562}
… …
576=cut 579=cut
577 580
578register_write_type netstring => sub { 581register_write_type netstring => sub {
579 my ($self, $string) = @_; 582 my ($self, $string) = @_;
580 583
581 sprintf "%d:%s,", (length $string), $string 584 (length $string) . ":$string,"
582}; 585};
583 586
584=item packstring => $format, $data 587=item packstring => $format, $data
585 588
586An octet string prefixed with an encoded length. The encoding C<$format> 589An octet string prefixed with an encoded length. The encoding C<$format>
… …
764 ) { 767 ) {
765 $self->_error (&Errno::ENOSPC, 1), return; 768 $self->_error (&Errno::ENOSPC, 1), return;
766 } 769 }
767 770
768 while () { 771 while () {
772 $self->{rbuf} .= delete $self->{tls_rbuf} if exists $self->{tls_rbuf};#d#
773
769 my $len = length $self->{rbuf}; 774 my $len = length $self->{rbuf};
770 775
771 if (my $cb = shift @{ $self->{_queue} }) { 776 if (my $cb = shift @{ $self->{_queue} }) {
772 unless ($cb->($self)) { 777 unless ($cb->($self)) {
773 if ($self->{_eof}) { 778 if ($self->{_eof}) {
… …
795 800
796 last; # more data might arrive 801 last; # more data might arrive
797 } 802 }
798 } else { 803 } else {
799 # read side becomes idle 804 # read side becomes idle
800 delete $self->{_rw}; 805 delete $self->{_rw} unless $self->{tls};
801 last; 806 last;
802 } 807 }
803 } 808 }
804 809
805 if ($self->{_eof}) { 810 if ($self->{_eof}) {
… …
1100An octet string prefixed with an encoded length. The encoding C<$format> 1105An octet string prefixed with an encoded length. The encoding C<$format>
1101uses the same format as a Perl C<pack> format, but must specify a single 1106uses the same format as a Perl C<pack> format, but must specify a single
1102integer only (only one of C<cCsSlLqQiInNvVjJw> is allowed, plus an 1107integer only (only one of C<cCsSlLqQiInNvVjJw> is allowed, plus an
1103optional C<!>, C<< < >> or C<< > >> modifier). 1108optional C<!>, C<< < >> or C<< > >> modifier).
1104 1109
1105DNS over TCP uses a prefix of C<n>, EPP uses a prefix of C<N>. 1110For example, DNS over TCP uses a prefix of C<n> (2 octet network order),
1111EPP uses a prefix of C<N> (4 octtes).
1106 1112
1107Example: read a block of data prefixed by its length in BER-encoded 1113Example: read a block of data prefixed by its length in BER-encoded
1108format (very efficient). 1114format (very efficient).
1109 1115
1110 $handle->push_read (packstring => "w", sub { 1116 $handle->push_read (packstring => "w", sub {
… …
1140 } 1146 }
1141}; 1147};
1142 1148
1143=item json => $cb->($handle, $hash_or_arrayref) 1149=item json => $cb->($handle, $hash_or_arrayref)
1144 1150
1145Reads a JSON object or array, decodes it and passes it to the callback. 1151Reads a JSON object or array, decodes it and passes it to the
1152callback. When a parse error occurs, an C<EBADMSG> error will be raised.
1146 1153
1147If a C<json> object was passed to the constructor, then that will be used 1154If a C<json> object was passed to the constructor, then that will be used
1148for the final decode, otherwise it will create a JSON coder expecting UTF-8. 1155for the final decode, otherwise it will create a JSON coder expecting UTF-8.
1149 1156
1150This read type uses the incremental parser available with JSON version 1157This read type uses the incremental parser available with JSON version
… …
1167 my $rbuf = \$self->{rbuf}; 1174 my $rbuf = \$self->{rbuf};
1168 1175
1169 my $json = $self->{json} ||= JSON->new->utf8; 1176 my $json = $self->{json} ||= JSON->new->utf8;
1170 1177
1171 sub { 1178 sub {
1172 my $ref = $json->incr_parse ($self->{rbuf}); 1179 my $ref = eval { $json->incr_parse ($self->{rbuf}) };
1173 1180
1174 if ($ref) { 1181 if ($ref) {
1175 $self->{rbuf} = $json->incr_text; 1182 $self->{rbuf} = $json->incr_text;
1176 $json->incr_text = ""; 1183 $json->incr_text = "";
1177 $cb->($self, $ref); 1184 $cb->($self, $ref);
1178 1185
1179 1 1186 1
1187 } elsif ($@) {
1188 # error case
1189 $json->incr_skip;
1190
1191 $self->{rbuf} = $json->incr_text;
1192 $json->incr_text = "";
1193
1194 $self->_error (&Errno::EBADMSG);
1195
1196 ()
1180 } else { 1197 } else {
1181 $self->{rbuf} = ""; 1198 $self->{rbuf} = "";
1199
1182 () 1200 ()
1183 } 1201 }
1184 } 1202 }
1185}; 1203};
1186 1204
… …
1263Note that AnyEvent::Handle will automatically C<start_read> for you when 1281Note that AnyEvent::Handle will automatically C<start_read> for you when
1264you change the C<on_read> callback or push/unshift a read callback, and it 1282you change the C<on_read> callback or push/unshift a read callback, and it
1265will automatically C<stop_read> for you when neither C<on_read> is set nor 1283will automatically C<stop_read> for you when neither C<on_read> is set nor
1266there are any read requests in the queue. 1284there are any read requests in the queue.
1267 1285
1286These methods will have no effect when in TLS mode (as TLS doesn't support
1287half-duplex connections).
1288
1268=cut 1289=cut
1269 1290
1270sub stop_read { 1291sub stop_read {
1271 my ($self) = @_; 1292 my ($self) = @_;
1272 1293
1273 delete $self->{_rw}; 1294 delete $self->{_rw} unless $self->{tls};
1274} 1295}
1275 1296
1276sub start_read { 1297sub start_read {
1277 my ($self) = @_; 1298 my ($self) = @_;
1278 1299
1279 unless ($self->{_rw} || $self->{_eof}) { 1300 unless ($self->{_rw} || $self->{_eof}) {
1280 Scalar::Util::weaken $self; 1301 Scalar::Util::weaken $self;
1281 1302
1282 $self->{_rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub { 1303 $self->{_rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub {
1283 my $rbuf = $self->{filter_r} ? \my $buf : \$self->{rbuf}; 1304 my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf});
1284 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf; 1305 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf;
1285 1306
1286 if ($len > 0) { 1307 if ($len > 0) {
1287 $self->{_activity} = AnyEvent->now; 1308 $self->{_activity} = AnyEvent->now;
1288 1309
1289 $self->{filter_r} 1310 if ($self->{tls}) {
1290 ? $self->{filter_r}($self, $rbuf) 1311 Net::SSLeay::BIO_write ($self->{_rbio}, $$rbuf);
1291 : $self->{_in_drain} || $self->_drain_rbuf; 1312
1313 &_dotls ($self);
1314 } else {
1315 $self->_drain_rbuf unless $self->{_in_drain};
1316 }
1292 1317
1293 } elsif (defined $len) { 1318 } elsif (defined $len) {
1294 delete $self->{_rw}; 1319 delete $self->{_rw};
1295 $self->{_eof} = 1; 1320 $self->{_eof} = 1;
1296 $self->_drain_rbuf unless $self->{_in_drain}; 1321 $self->_drain_rbuf unless $self->{_in_drain};
… …
1300 } 1325 }
1301 }); 1326 });
1302 } 1327 }
1303} 1328}
1304 1329
1330# poll the write BIO and send the data if applicable
1305sub _dotls { 1331sub _dotls {
1306 my ($self) = @_; 1332 my ($self) = @_;
1307 1333
1308 my $buf; 1334 my $tmp;
1309 1335
1310 if (length $self->{_tls_wbuf}) { 1336 if (length $self->{_tls_wbuf}) {
1311 while ((my $len = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) { 1337 while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
1312 substr $self->{_tls_wbuf}, 0, $len, ""; 1338 substr $self->{_tls_wbuf}, 0, $tmp, "";
1313 } 1339 }
1314 } 1340 }
1315 1341
1316 if (length ($buf = Net::SSLeay::BIO_read ($self->{_wbio}))) {
1317 $self->{wbuf} .= $buf;
1318 $self->_drain_wbuf;
1319 }
1320
1321 while (defined ($buf = Net::SSLeay::read ($self->{tls}))) { 1342 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
1322 if (length $buf) { 1343 unless (length $tmp) {
1323 $self->{rbuf} .= $buf;
1324 $self->_drain_rbuf unless $self->{_in_drain};
1325 } else {
1326 # let's treat SSL-eof as we treat normal EOF 1344 # let's treat SSL-eof as we treat normal EOF
1345 delete $self->{_rw};
1327 $self->{_eof} = 1; 1346 $self->{_eof} = 1;
1328 $self->_shutdown; 1347 &_freetls;
1329 return;
1330 } 1348 }
1331 }
1332 1349
1350 $self->{tls_rbuf} .= $tmp;#d#
1351 $self->_drain_rbuf unless $self->{_in_drain};
1352 $self->{tls} or return; # tls session might have gone away in callback
1353 }
1354
1333 my $err = Net::SSLeay::get_error ($self->{tls}, -1); 1355 $tmp = Net::SSLeay::get_error ($self->{tls}, -1);
1334 1356
1335 if ($err!= Net::SSLeay::ERROR_WANT_READ ()) { 1357 if ($tmp != Net::SSLeay::ERROR_WANT_READ ()) {
1336 if ($err == Net::SSLeay::ERROR_SYSCALL ()) { 1358 if ($tmp == Net::SSLeay::ERROR_SYSCALL ()) {
1337 return $self->_error ($!, 1); 1359 return $self->_error ($!, 1);
1338 } elsif ($err == Net::SSLeay::ERROR_SSL ()) { 1360 } elsif ($tmp == Net::SSLeay::ERROR_SSL ()) {
1339 return $self->_error (&Errno::EIO, 1); 1361 return $self->_error (&Errno::EIO, 1);
1340 } 1362 }
1341 1363
1342 # all others are fine for our purposes 1364 # all other errors are fine for our purposes
1365 }
1366
1367 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
1368 $self->{wbuf} .= $tmp;
1369 $self->_drain_wbuf;
1343 } 1370 }
1344} 1371}
1345 1372
1346=item $handle->starttls ($tls[, $tls_ctx]) 1373=item $handle->starttls ($tls[, $tls_ctx])
1347 1374
… …
1357 1384
1358The TLS connection object will end up in C<< $handle->{tls} >> after this 1385The TLS connection object will end up in C<< $handle->{tls} >> after this
1359call and can be used or changed to your liking. Note that the handshake 1386call and can be used or changed to your liking. Note that the handshake
1360might have already started when this function returns. 1387might have already started when this function returns.
1361 1388
1389If it an error to start a TLS handshake more than once per
1390AnyEvent::Handle object (this is due to bugs in OpenSSL).
1391
1362=cut 1392=cut
1363 1393
1364sub starttls { 1394sub starttls {
1365 my ($self, $ssl, $ctx) = @_; 1395 my ($self, $ssl, $ctx) = @_;
1366 1396
1367 $self->stoptls; 1397 require Net::SSLeay;
1368 1398
1399 Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object"
1400 if $self->{tls};
1401
1369 if ($ssl eq "accept") { 1402 if ($ssl eq "accept") {
1370 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ()); 1403 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ());
1371 Net::SSLeay::set_accept_state ($ssl); 1404 Net::SSLeay::set_accept_state ($ssl);
1372 } elsif ($ssl eq "connect") { 1405 } elsif ($ssl eq "connect") {
1373 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ()); 1406 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ());
… …
1382 # and mismaintained ssleay-module doesn't even offer them). 1415 # and mismaintained ssleay-module doesn't even offer them).
1383 # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html 1416 # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html
1384 # 1417 #
1385 # in short: this is a mess. 1418 # in short: this is a mess.
1386 # 1419 #
1387 # note that we do not try to kepe the length constant between writes as we are required to do. 1420 # note that we do not try to keep the length constant between writes as we are required to do.
1388 # we assume that most (but not all) of this insanity only applies to non-blocking cases, 1421 # we assume that most (but not all) of this insanity only applies to non-blocking cases,
1389 # and we drive openssl fully in blocking mode here. 1422 # and we drive openssl fully in blocking mode here. Or maybe we don't - openssl seems to
1423 # have identity issues in that area.
1390 Net::SSLeay::CTX_set_mode ($self->{tls}, 1424 Net::SSLeay::CTX_set_mode ($self->{tls},
1391 (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1) 1425 (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1)
1392 | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2)); 1426 | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2));
1393 1427
1394 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1428 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1395 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1429 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1396 1430
1397 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio}); 1431 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});
1398 1432
1399 $self->{filter_w} = sub { 1433 &_dotls; # need to trigger the initial handshake
1400 $_[0]{_tls_wbuf} .= ${$_[1]}; 1434 $self->start_read; # make sure we actually do read
1401 &_dotls;
1402 };
1403 $self->{filter_r} = sub {
1404 Net::SSLeay::BIO_write ($_[0]{_rbio}, ${$_[1]});
1405 &_dotls;
1406 };
1407} 1435}
1408 1436
1409=item $handle->stoptls 1437=item $handle->stoptls
1410 1438
1411Destroys the SSL connection, if any. Partial read or write data will be 1439Shuts down the SSL connection - this makes a proper EOF handshake by
1412lost. 1440sending a close notify to the other side, but since OpenSSL doesn't
1441support non-blocking shut downs, it is not possible to re-use the stream
1442afterwards.
1413 1443
1414=cut 1444=cut
1415 1445
1416sub stoptls { 1446sub stoptls {
1417 my ($self) = @_; 1447 my ($self) = @_;
1418 1448
1449 if ($self->{tls}) {
1450 Net::SSLeay::shutdown ($self->{tls});
1451
1452 &_dotls;
1453
1454 # we don't give a shit. no, we do, but we can't. no...
1455 # we, we... have to use openssl :/
1456 &_freetls;
1457 }
1458}
1459
1460sub _freetls {
1461 my ($self) = @_;
1462
1463 return unless $self->{tls};
1464
1419 Net::SSLeay::free (delete $self->{tls}) if $self->{tls}; 1465 Net::SSLeay::free (delete $self->{tls});
1420 1466
1421 delete $self->{_rbio}; 1467 delete @$self{qw(_rbio _wbio _tls_wbuf)};
1422 delete $self->{_wbio};
1423 delete $self->{_tls_wbuf};
1424 delete $self->{filter_r};
1425 delete $self->{filter_w};
1426} 1468}
1427 1469
1428sub DESTROY { 1470sub DESTROY {
1429 my $self = shift; 1471 my $self = shift;
1430 1472
1431 $self->stoptls; 1473 &_freetls;
1432 1474
1433 my $linger = exists $self->{linger} ? $self->{linger} : 3600; 1475 my $linger = exists $self->{linger} ? $self->{linger} : 3600;
1434 1476
1435 if ($linger && length $self->{wbuf}) { 1477 if ($linger && length $self->{wbuf}) {
1436 my $fh = delete $self->{fh}; 1478 my $fh = delete $self->{fh};
… …
1451 @linger = (); 1493 @linger = ();
1452 }); 1494 });
1453 } 1495 }
1454} 1496}
1455 1497
1498=item $handle->destroy
1499
1500Shuts down the handle object as much as possible - this call ensures that
1501no further callbacks will be invoked and resources will be freed as much
1502as possible. You must not call any methods on the object afterwards.
1503
1504Normally, you can just "forget" any references to an AnyEvent::Handle
1505object and it will simply shut down. This works in fatal error and EOF
1506callbacks, as well as code outside. It does I<NOT> work in a read or write
1507callback, so when you want to destroy the AnyEvent::Handle object from
1508within such an callback. You I<MUST> call C<< ->destroy >> explicitly in
1509that case.
1510
1511The handle might still linger in the background and write out remaining
1512data, as specified by the C<linger> option, however.
1513
1514=cut
1515
1516sub destroy {
1517 my ($self) = @_;
1518
1519 $self->DESTROY;
1520 %$self = ();
1521}
1522
1456=item AnyEvent::Handle::TLS_CTX 1523=item AnyEvent::Handle::TLS_CTX
1457 1524
1458This function creates and returns the Net::SSLeay::CTX object used by 1525This function creates and returns the Net::SSLeay::CTX object used by
1459default for TLS mode. 1526default for TLS mode.
1460 1527
… …
1488 } 1555 }
1489} 1556}
1490 1557
1491=back 1558=back
1492 1559
1560
1561=head1 NONFREQUENTLY ASKED QUESTIONS
1562
1563=over 4
1564
1565=item I C<undef> the AnyEvent::Handle reference inside my callback and
1566still get further invocations!
1567
1568That's because AnyEvent::Handle keeps a reference to itself when handling
1569read or write callbacks.
1570
1571It is only safe to "forget" the reference inside EOF or error callbacks,
1572from within all other callbacks, you need to explicitly call the C<<
1573->destroy >> method.
1574
1575=item I get different callback invocations in TLS mode/Why can't I pause
1576reading?
1577
1578Unlike, say, TCP, TLS connections do not consist of two independent
1579communication channels, one for each direction. Or put differently. The
1580read and write directions are not independent of each other: you cannot
1581write data unless you are also prepared to read, and vice versa.
1582
1583This can mean than, in TLS mode, you might get C<on_error> or C<on_eof>
1584callback invocations when you are not expecting any read data - the reason
1585is that AnyEvent::Handle always reads in TLS mode.
1586
1587During the connection, you have to make sure that you always have a
1588non-empty read-queue, or an C<on_read> watcher. At the end of the
1589connection (or when you no longer want to use it) you can call the
1590C<destroy> method.
1591
1592=item How do I read data until the other side closes the connection?
1593
1594If you just want to read your data into a perl scalar, the easiest way
1595to achieve this is by setting an C<on_read> callback that does nothing,
1596clearing the C<on_eof> callback and in the C<on_error> callback, the data
1597will be in C<$_[0]{rbuf}>:
1598
1599 $handle->on_read (sub { });
1600 $handle->on_eof (undef);
1601 $handle->on_error (sub {
1602 my $data = delete $_[0]{rbuf};
1603 undef $handle;
1604 });
1605
1606The reason to use C<on_error> is that TCP connections, due to latencies
1607and packets loss, might get closed quite violently with an error, when in
1608fact, all data has been received.
1609
1610It is usually better to use acknowledgements when transferring data,
1611to make sure the other side hasn't just died and you got the data
1612intact. This is also one reason why so many internet protocols have an
1613explicit QUIT command.
1614
1615=item I don't want to destroy the handle too early - how do I wait until
1616all data has been written?
1617
1618After writing your last bits of data, set the C<on_drain> callback
1619and destroy the handle in there - with the default setting of
1620C<low_water_mark> this will be called precisely when all data has been
1621written to the socket:
1622
1623 $handle->push_write (...);
1624 $handle->on_drain (sub {
1625 warn "all data submitted to the kernel\n";
1626 undef $handle;
1627 });
1628
1629=back
1630
1631
1493=head1 SUBCLASSING AnyEvent::Handle 1632=head1 SUBCLASSING AnyEvent::Handle
1494 1633
1495In many cases, you might want to subclass AnyEvent::Handle. 1634In many cases, you might want to subclass AnyEvent::Handle.
1496 1635
1497To make this easier, a given version of AnyEvent::Handle uses these 1636To make this easier, a given version of AnyEvent::Handle uses these

Diff Legend

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