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

Diff Legend

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