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.114 by root, Wed Jan 21 06:06:22 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>
… …
795 798
796 last; # more data might arrive 799 last; # more data might arrive
797 } 800 }
798 } else { 801 } else {
799 # read side becomes idle 802 # read side becomes idle
800 delete $self->{_rw}; 803 delete $self->{_rw} unless $self->{tls};
801 last; 804 last;
802 } 805 }
803 } 806 }
804 807
805 if ($self->{_eof}) { 808 if ($self->{_eof}) {
… …
1100An octet string prefixed with an encoded length. The encoding C<$format> 1103An 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 1104uses 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 1105integer only (only one of C<cCsSlLqQiInNvVjJw> is allowed, plus an
1103optional C<!>, C<< < >> or C<< > >> modifier). 1106optional C<!>, C<< < >> or C<< > >> modifier).
1104 1107
1105DNS over TCP uses a prefix of C<n>, EPP uses a prefix of C<N>. 1108For example, DNS over TCP uses a prefix of C<n> (2 octet network order),
1109EPP uses a prefix of C<N> (4 octtes).
1106 1110
1107Example: read a block of data prefixed by its length in BER-encoded 1111Example: read a block of data prefixed by its length in BER-encoded
1108format (very efficient). 1112format (very efficient).
1109 1113
1110 $handle->push_read (packstring => "w", sub { 1114 $handle->push_read (packstring => "w", sub {
… …
1140 } 1144 }
1141}; 1145};
1142 1146
1143=item json => $cb->($handle, $hash_or_arrayref) 1147=item json => $cb->($handle, $hash_or_arrayref)
1144 1148
1145Reads a JSON object or array, decodes it and passes it to the callback. 1149Reads a JSON object or array, decodes it and passes it to the
1150callback. When a parse error occurs, an C<EBADMSG> error will be raised.
1146 1151
1147If a C<json> object was passed to the constructor, then that will be used 1152If 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. 1153for the final decode, otherwise it will create a JSON coder expecting UTF-8.
1149 1154
1150This read type uses the incremental parser available with JSON version 1155This read type uses the incremental parser available with JSON version
… …
1167 my $rbuf = \$self->{rbuf}; 1172 my $rbuf = \$self->{rbuf};
1168 1173
1169 my $json = $self->{json} ||= JSON->new->utf8; 1174 my $json = $self->{json} ||= JSON->new->utf8;
1170 1175
1171 sub { 1176 sub {
1172 my $ref = $json->incr_parse ($self->{rbuf}); 1177 my $ref = eval { $json->incr_parse ($self->{rbuf}) };
1173 1178
1174 if ($ref) { 1179 if ($ref) {
1175 $self->{rbuf} = $json->incr_text; 1180 $self->{rbuf} = $json->incr_text;
1176 $json->incr_text = ""; 1181 $json->incr_text = "";
1177 $cb->($self, $ref); 1182 $cb->($self, $ref);
1178 1183
1179 1 1184 1
1185 } elsif ($@) {
1186 # error case
1187 $json->incr_skip;
1188
1189 $self->{rbuf} = $json->incr_text;
1190 $json->incr_text = "";
1191
1192 $self->_error (&Errno::EBADMSG);
1193
1194 ()
1180 } else { 1195 } else {
1181 $self->{rbuf} = ""; 1196 $self->{rbuf} = "";
1197
1182 () 1198 ()
1183 } 1199 }
1184 } 1200 }
1185}; 1201};
1186 1202
… …
1263Note that AnyEvent::Handle will automatically C<start_read> for you when 1279Note 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 1280you 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 1281will automatically C<stop_read> for you when neither C<on_read> is set nor
1266there are any read requests in the queue. 1282there are any read requests in the queue.
1267 1283
1284These methods will have no effect when in TLS mode (as TLS doesn't support
1285half-duplex connections).
1286
1268=cut 1287=cut
1269 1288
1270sub stop_read { 1289sub stop_read {
1271 my ($self) = @_; 1290 my ($self) = @_;
1272 1291
1273 delete $self->{_rw}; 1292 delete $self->{_rw} unless $self->{tls};
1274} 1293}
1275 1294
1276sub start_read { 1295sub start_read {
1277 my ($self) = @_; 1296 my ($self) = @_;
1278 1297
1279 unless ($self->{_rw} || $self->{_eof}) { 1298 unless ($self->{_rw} || $self->{_eof}) {
1280 Scalar::Util::weaken $self; 1299 Scalar::Util::weaken $self;
1281 1300
1282 $self->{_rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub { 1301 $self->{_rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub {
1283 my $rbuf = $self->{filter_r} ? \my $buf : \$self->{rbuf}; 1302 my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf});
1284 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf; 1303 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf;
1285 1304
1286 if ($len > 0) { 1305 if ($len > 0) {
1287 $self->{_activity} = AnyEvent->now; 1306 $self->{_activity} = AnyEvent->now;
1288 1307
1289 $self->{filter_r} 1308 if ($self->{tls}) {
1290 ? $self->{filter_r}($self, $rbuf) 1309 Net::SSLeay::BIO_write ($self->{_rbio}, $$rbuf);
1291 : $self->{_in_drain} || $self->_drain_rbuf; 1310
1311 &_dotls ($self);
1312 } else {
1313 $self->_drain_rbuf unless $self->{_in_drain};
1314 }
1292 1315
1293 } elsif (defined $len) { 1316 } elsif (defined $len) {
1294 delete $self->{_rw}; 1317 delete $self->{_rw};
1295 $self->{_eof} = 1; 1318 $self->{_eof} = 1;
1296 $self->_drain_rbuf unless $self->{_in_drain}; 1319 $self->_drain_rbuf unless $self->{_in_drain};
… …
1300 } 1323 }
1301 }); 1324 });
1302 } 1325 }
1303} 1326}
1304 1327
1328# poll the write BIO and send the data if applicable
1305sub _dotls { 1329sub _dotls {
1306 my ($self) = @_; 1330 my ($self) = @_;
1307 1331
1308 my $buf; 1332 my $tmp;
1309 1333
1310 if (length $self->{_tls_wbuf}) { 1334 if (length $self->{_tls_wbuf}) {
1311 while ((my $len = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) { 1335 while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
1312 substr $self->{_tls_wbuf}, 0, $len, ""; 1336 substr $self->{_tls_wbuf}, 0, $tmp, "";
1313 } 1337 }
1314 } 1338 }
1315 1339
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}))) { 1340 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
1322 if (length $buf) { 1341 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 1342 # let's treat SSL-eof as we treat normal EOF
1343 delete $self->{_rw};
1327 $self->{_eof} = 1; 1344 $self->{_eof} = 1;
1328 $self->_shutdown; 1345 &_freetls;
1329 return;
1330 } 1346 }
1331 }
1332 1347
1348 $self->{rbuf} .= $tmp;
1349 $self->_drain_rbuf unless $self->{_in_drain};
1350 $self->{tls} or return; # tls session might have gone away in callback
1351 }
1352
1333 my $err = Net::SSLeay::get_error ($self->{tls}, -1); 1353 $tmp = Net::SSLeay::get_error ($self->{tls}, -1);
1334 1354
1335 if ($err!= Net::SSLeay::ERROR_WANT_READ ()) { 1355 if ($tmp != Net::SSLeay::ERROR_WANT_READ ()) {
1336 if ($err == Net::SSLeay::ERROR_SYSCALL ()) { 1356 if ($tmp == Net::SSLeay::ERROR_SYSCALL ()) {
1337 return $self->_error ($!, 1); 1357 return $self->_error ($!, 1);
1338 } elsif ($err == Net::SSLeay::ERROR_SSL ()) { 1358 } elsif ($tmp == Net::SSLeay::ERROR_SSL ()) {
1339 return $self->_error (&Errno::EIO, 1); 1359 return $self->_error (&Errno::EIO, 1);
1340 } 1360 }
1341 1361
1342 # all others are fine for our purposes 1362 # all other errors are fine for our purposes
1363 }
1364
1365 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
1366 $self->{wbuf} .= $tmp;
1367 $self->_drain_wbuf;
1343 } 1368 }
1344} 1369}
1345 1370
1346=item $handle->starttls ($tls[, $tls_ctx]) 1371=item $handle->starttls ($tls[, $tls_ctx])
1347 1372
… …
1357 1382
1358The TLS connection object will end up in C<< $handle->{tls} >> after this 1383The 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 1384call and can be used or changed to your liking. Note that the handshake
1360might have already started when this function returns. 1385might have already started when this function returns.
1361 1386
1387If it an error to start a TLS handshake more than once per
1388AnyEvent::Handle object (this is due to bugs in OpenSSL).
1389
1362=cut 1390=cut
1363 1391
1364sub starttls { 1392sub starttls {
1365 my ($self, $ssl, $ctx) = @_; 1393 my ($self, $ssl, $ctx) = @_;
1366 1394
1367 $self->stoptls; 1395 require Net::SSLeay;
1368 1396
1397 Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object"
1398 if $self->{tls};
1399
1369 if ($ssl eq "accept") { 1400 if ($ssl eq "accept") {
1370 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ()); 1401 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ());
1371 Net::SSLeay::set_accept_state ($ssl); 1402 Net::SSLeay::set_accept_state ($ssl);
1372 } elsif ($ssl eq "connect") { 1403 } elsif ($ssl eq "connect") {
1373 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ()); 1404 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ());
… …
1382 # and mismaintained ssleay-module doesn't even offer them). 1413 # and mismaintained ssleay-module doesn't even offer them).
1383 # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html 1414 # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html
1384 # 1415 #
1385 # in short: this is a mess. 1416 # in short: this is a mess.
1386 # 1417 #
1387 # note that we do not try to kepe the length constant between writes as we are required to do. 1418 # 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, 1419 # 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. 1420 # and we drive openssl fully in blocking mode here. Or maybe we don't - openssl seems to
1421 # have identity issues in that area.
1390 Net::SSLeay::CTX_set_mode ($self->{tls}, 1422 Net::SSLeay::CTX_set_mode ($self->{tls},
1391 (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1) 1423 (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1)
1392 | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2)); 1424 | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2));
1393 1425
1394 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1426 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1395 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1427 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1396 1428
1397 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio}); 1429 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});
1398 1430
1399 $self->{filter_w} = sub { 1431 &_dotls; # need to trigger the initial handshake
1400 $_[0]{_tls_wbuf} .= ${$_[1]}; 1432 $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} 1433}
1408 1434
1409=item $handle->stoptls 1435=item $handle->stoptls
1410 1436
1411Destroys the SSL connection, if any. Partial read or write data will be 1437Shuts down the SSL connection - this makes a proper EOF handshake by
1412lost. 1438sending a close notify to the other side, but since OpenSSL doesn't
1439support non-blocking shut downs, it is not possible to re-use the stream
1440afterwards.
1413 1441
1414=cut 1442=cut
1415 1443
1416sub stoptls { 1444sub stoptls {
1417 my ($self) = @_; 1445 my ($self) = @_;
1418 1446
1447 if ($self->{tls}) {
1448 Net::SSLeay::shutdown ($self->{tls});
1449
1450 &_dotls;
1451
1452 # we don't give a shit. no, we do, but we can't. no...
1453 # we, we... have to use openssl :/
1454 &_freetls;
1455 }
1456}
1457
1458sub _freetls {
1459 my ($self) = @_;
1460
1461 return unless $self->{tls};
1462
1419 Net::SSLeay::free (delete $self->{tls}) if $self->{tls}; 1463 Net::SSLeay::free (delete $self->{tls});
1420 1464
1421 delete $self->{_rbio}; 1465 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} 1466}
1427 1467
1428sub DESTROY { 1468sub DESTROY {
1429 my $self = shift; 1469 my $self = shift;
1430 1470
1431 $self->stoptls; 1471 &_freetls;
1432 1472
1433 my $linger = exists $self->{linger} ? $self->{linger} : 3600; 1473 my $linger = exists $self->{linger} ? $self->{linger} : 3600;
1434 1474
1435 if ($linger && length $self->{wbuf}) { 1475 if ($linger && length $self->{wbuf}) {
1436 my $fh = delete $self->{fh}; 1476 my $fh = delete $self->{fh};
… …
1451 @linger = (); 1491 @linger = ();
1452 }); 1492 });
1453 } 1493 }
1454} 1494}
1455 1495
1496=item $handle->destroy
1497
1498Shuts down the handle object as much as possible - this call ensures that
1499no further callbacks will be invoked and resources will be freed as much
1500as possible. You must not call any methods on the object afterwards.
1501
1502Normally, you can just "forget" any references to an AnyEvent::Handle
1503object and it will simply shut down. This works in fatal error and EOF
1504callbacks, as well as code outside. It does I<NOT> work in a read or write
1505callback, so when you want to destroy the AnyEvent::Handle object from
1506within such an callback. You I<MUST> call C<< ->destroy >> explicitly in
1507that case.
1508
1509The handle might still linger in the background and write out remaining
1510data, as specified by the C<linger> option, however.
1511
1512=cut
1513
1514sub destroy {
1515 my ($self) = @_;
1516
1517 $self->DESTROY;
1518 %$self = ();
1519}
1520
1456=item AnyEvent::Handle::TLS_CTX 1521=item AnyEvent::Handle::TLS_CTX
1457 1522
1458This function creates and returns the Net::SSLeay::CTX object used by 1523This function creates and returns the Net::SSLeay::CTX object used by
1459default for TLS mode. 1524default for TLS mode.
1460 1525
… …
1488 } 1553 }
1489} 1554}
1490 1555
1491=back 1556=back
1492 1557
1558
1559=head1 NONFREQUENTLY ASKED QUESTIONS
1560
1561=over 4
1562
1563=item I C<undef> the AnyEvent::Handle reference inside my callback and
1564still get further invocations!
1565
1566That's because AnyEvent::Handle keeps a reference to itself when handling
1567read or write callbacks.
1568
1569It is only safe to "forget" the reference inside EOF or error callbacks,
1570from within all other callbacks, you need to explicitly call the C<<
1571->destroy >> method.
1572
1573=item I get different callback invocations in TLS mode/Why can't I pause
1574reading?
1575
1576Unlike, say, TCP, TLS connections do not consist of two independent
1577communication channels, one for each direction. Or put differently. The
1578read and write directions are not independent of each other: you cannot
1579write data unless you are also prepared to read, and vice versa.
1580
1581This can mean than, in TLS mode, you might get C<on_error> or C<on_eof>
1582callback invocations when you are not expecting any read data - the reason
1583is that AnyEvent::Handle always reads in TLS mode.
1584
1585During the connection, you have to make sure that you always have a
1586non-empty read-queue, or an C<on_read> watcher. At the end of the
1587connection (or when you no longer want to use it) you can call the
1588C<destroy> method.
1589
1590=item How do I read data until the other side closes the connection?
1591
1592If you just want to read your data into a perl scalar, the easiest way
1593to achieve this is by setting an C<on_read> callback that does nothing,
1594clearing the C<on_eof> callback and in the C<on_error> callback, the data
1595will be in C<$_[0]{rbuf}>:
1596
1597 $handle->on_read (sub { });
1598 $handle->on_eof (undef);
1599 $handle->on_error (sub {
1600 my $data = delete $_[0]{rbuf};
1601 undef $handle;
1602 });
1603
1604The reason to use C<on_error> is that TCP connections, due to latencies
1605and packets loss, might get closed quite violently with an error, when in
1606fact, all data has been received.
1607
1608It is usually better to use acknowledgements when transferring data,
1609to make sure the other side hasn't just died and you got the data
1610intact. This is also one reason why so many internet protocols have an
1611explicit QUIT command.
1612
1613=item I don't want to destroy the handle too early - how do I wait until
1614all data has been written?
1615
1616After writing your last bits of data, set the C<on_drain> callback
1617and destroy the handle in there - with the default setting of
1618C<low_water_mark> this will be called precisely when all data has been
1619written to the socket:
1620
1621 $handle->push_write (...);
1622 $handle->on_drain (sub {
1623 warn "all data submitted to the kernel\n";
1624 undef $handle;
1625 });
1626
1627=back
1628
1629
1493=head1 SUBCLASSING AnyEvent::Handle 1630=head1 SUBCLASSING AnyEvent::Handle
1494 1631
1495In many cases, you might want to subclass AnyEvent::Handle. 1632In many cases, you might want to subclass AnyEvent::Handle.
1496 1633
1497To make this easier, a given version of AnyEvent::Handle uses these 1634To make this easier, a given version of AnyEvent::Handle uses these

Diff Legend

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