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.102 by root, Wed Oct 29 14:32:02 2008 UTC

… …
14 14
15AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent 15AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent
16 16
17=cut 17=cut
18 18
19our $VERSION = 4.233; 19our $VERSION = 4.3;
20 20
21=head1 SYNOPSIS 21=head1 SYNOPSIS
22 22
23 use AnyEvent; 23 use AnyEvent;
24 use AnyEvent::Handle; 24 use AnyEvent::Handle;
… …
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
… …
273texts. 274texts.
274 275
275Note that you are responsible to depend on the JSON module if you want to 276Note 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. 277use this functionality, as AnyEvent does not have a dependency itself.
277 278
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 279=back
286 280
287=cut 281=cut
288 282
289sub new { 283sub new {
… …
293 287
294 $self->{fh} or Carp::croak "mandatory argument fh is missing"; 288 $self->{fh} or Carp::croak "mandatory argument fh is missing";
295 289
296 AnyEvent::Util::fh_nonblocking $self->{fh}, 1; 290 AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
297 291
298 if ($self->{tls}) {
299 require Net::SSLeay;
300 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx}); 292 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
301 } 293 if $self->{tls};
302 294
303 $self->{_activity} = AnyEvent->now; 295 $self->{_activity} = AnyEvent->now;
304 $self->_timeout; 296 $self->_timeout;
305 297
306 $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain}; 298 $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain};
… …
318 delete $self->{_tw}; 310 delete $self->{_tw};
319 delete $self->{_rw}; 311 delete $self->{_rw};
320 delete $self->{_ww}; 312 delete $self->{_ww};
321 delete $self->{fh}; 313 delete $self->{fh};
322 314
323 $self->stoptls; 315 &_freetls;
324 316
325 delete $self->{on_read}; 317 delete $self->{on_read};
326 delete $self->{_queue}; 318 delete $self->{_queue};
327} 319}
328 320
… …
334 326
335 $! = $errno; 327 $! = $errno;
336 328
337 if ($self->{on_error}) { 329 if ($self->{on_error}) {
338 $self->{on_error}($self, $fatal); 330 $self->{on_error}($self, $fatal);
339 } else { 331 } elsif ($self->{fh}) {
340 Carp::croak "AnyEvent::Handle uncaught error: $!"; 332 Carp::croak "AnyEvent::Handle uncaught error: $!";
341 } 333 }
342} 334}
343 335
344=item $fh = $handle->fh 336=item $fh = $handle->fh
… …
487 my ($self, $cb) = @_; 479 my ($self, $cb) = @_;
488 480
489 $self->{on_drain} = $cb; 481 $self->{on_drain} = $cb;
490 482
491 $cb->($self) 483 $cb->($self)
492 if $cb && $self->{low_water_mark} >= length $self->{wbuf}; 484 if $cb && $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf});
493} 485}
494 486
495=item $handle->push_write ($data) 487=item $handle->push_write ($data)
496 488
497Queues the given scalar to be written. You can push as much data as you 489Queues the given scalar to be written. You can push as much data as you
… …
514 substr $self->{wbuf}, 0, $len, ""; 506 substr $self->{wbuf}, 0, $len, "";
515 507
516 $self->{_activity} = AnyEvent->now; 508 $self->{_activity} = AnyEvent->now;
517 509
518 $self->{on_drain}($self) 510 $self->{on_drain}($self)
519 if $self->{low_water_mark} >= length $self->{wbuf} 511 if $self->{low_water_mark} >= (length $self->{wbuf}) + (length $self->{_tls_wbuf})
520 && $self->{on_drain}; 512 && $self->{on_drain};
521 513
522 delete $self->{_ww} unless length $self->{wbuf}; 514 delete $self->{_ww} unless length $self->{wbuf};
523 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) { 515 } elsif ($! != EAGAIN && $! != EINTR && $! != WSAEWOULDBLOCK) {
524 $self->_error ($!, 1); 516 $self->_error ($!, 1);
… …
548 540
549 @_ = ($WH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_write") 541 @_ = ($WH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_write")
550 ->($self, @_); 542 ->($self, @_);
551 } 543 }
552 544
553 if ($self->{filter_w}) { 545 if ($self->{tls}) {
554 $self->{filter_w}($self, \$_[0]); 546 $self->{_tls_wbuf} .= $_[0];
547
548 &_dotls ($self);
555 } else { 549 } else {
556 $self->{wbuf} .= $_[0]; 550 $self->{wbuf} .= $_[0];
557 $self->_drain_wbuf; 551 $self->_drain_wbuf;
558 } 552 }
559} 553}
… …
576=cut 570=cut
577 571
578register_write_type netstring => sub { 572register_write_type netstring => sub {
579 my ($self, $string) = @_; 573 my ($self, $string) = @_;
580 574
581 sprintf "%d:%s,", (length $string), $string 575 (length $string) . ":$string,"
582}; 576};
583 577
584=item packstring => $format, $data 578=item packstring => $format, $data
585 579
586An octet string prefixed with an encoded length. The encoding C<$format> 580An octet string prefixed with an encoded length. The encoding C<$format>
… …
795 789
796 last; # more data might arrive 790 last; # more data might arrive
797 } 791 }
798 } else { 792 } else {
799 # read side becomes idle 793 # read side becomes idle
800 delete $self->{_rw}; 794 delete $self->{_rw} unless $self->{tls};
801 last; 795 last;
802 } 796 }
803 } 797 }
804 798
805 if ($self->{_eof}) { 799 if ($self->{_eof}) {
… …
1100An octet string prefixed with an encoded length. The encoding C<$format> 1094An 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 1095uses 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 1096integer only (only one of C<cCsSlLqQiInNvVjJw> is allowed, plus an
1103optional C<!>, C<< < >> or C<< > >> modifier). 1097optional C<!>, C<< < >> or C<< > >> modifier).
1104 1098
1105DNS over TCP uses a prefix of C<n>, EPP uses a prefix of C<N>. 1099For example, DNS over TCP uses a prefix of C<n> (2 octet network order),
1100EPP uses a prefix of C<N> (4 octtes).
1106 1101
1107Example: read a block of data prefixed by its length in BER-encoded 1102Example: read a block of data prefixed by its length in BER-encoded
1108format (very efficient). 1103format (very efficient).
1109 1104
1110 $handle->push_read (packstring => "w", sub { 1105 $handle->push_read (packstring => "w", sub {
… …
1263Note that AnyEvent::Handle will automatically C<start_read> for you when 1258Note 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 1259you 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 1260will automatically C<stop_read> for you when neither C<on_read> is set nor
1266there are any read requests in the queue. 1261there are any read requests in the queue.
1267 1262
1263These methods will have no effect when in TLS mode (as TLS doesn't support
1264half-duplex connections).
1265
1268=cut 1266=cut
1269 1267
1270sub stop_read { 1268sub stop_read {
1271 my ($self) = @_; 1269 my ($self) = @_;
1272 1270
1273 delete $self->{_rw}; 1271 delete $self->{_rw} unless $self->{tls};
1274} 1272}
1275 1273
1276sub start_read { 1274sub start_read {
1277 my ($self) = @_; 1275 my ($self) = @_;
1278 1276
1279 unless ($self->{_rw} || $self->{_eof}) { 1277 unless ($self->{_rw} || $self->{_eof}) {
1280 Scalar::Util::weaken $self; 1278 Scalar::Util::weaken $self;
1281 1279
1282 $self->{_rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub { 1280 $self->{_rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub {
1283 my $rbuf = $self->{filter_r} ? \my $buf : \$self->{rbuf}; 1281 my $rbuf = \($self->{tls} ? my $buf : $self->{rbuf});
1284 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf; 1282 my $len = sysread $self->{fh}, $$rbuf, $self->{read_size} || 8192, length $$rbuf;
1285 1283
1286 if ($len > 0) { 1284 if ($len > 0) {
1287 $self->{_activity} = AnyEvent->now; 1285 $self->{_activity} = AnyEvent->now;
1288 1286
1289 $self->{filter_r} 1287 if ($self->{tls}) {
1290 ? $self->{filter_r}($self, $rbuf) 1288 Net::SSLeay::BIO_write ($self->{_rbio}, $$rbuf);
1291 : $self->{_in_drain} || $self->_drain_rbuf; 1289
1290 &_dotls ($self);
1291 } else {
1292 $self->_drain_rbuf unless $self->{_in_drain};
1293 }
1292 1294
1293 } elsif (defined $len) { 1295 } elsif (defined $len) {
1294 delete $self->{_rw}; 1296 delete $self->{_rw};
1295 $self->{_eof} = 1; 1297 $self->{_eof} = 1;
1296 $self->_drain_rbuf unless $self->{_in_drain}; 1298 $self->_drain_rbuf unless $self->{_in_drain};
… …
1300 } 1302 }
1301 }); 1303 });
1302 } 1304 }
1303} 1305}
1304 1306
1307# poll the write BIO and send the data if applicable
1305sub _dotls { 1308sub _dotls {
1306 my ($self) = @_; 1309 my ($self) = @_;
1307 1310
1308 my $buf; 1311 my $tmp;
1309 1312
1310 if (length $self->{_tls_wbuf}) { 1313 if (length $self->{_tls_wbuf}) {
1311 while ((my $len = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) { 1314 while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
1312 substr $self->{_tls_wbuf}, 0, $len, ""; 1315 substr $self->{_tls_wbuf}, 0, $tmp, "";
1313 } 1316 }
1314 } 1317 }
1315 1318
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}))) { 1319 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
1322 if (length $buf) { 1320 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 1321 # let's treat SSL-eof as we treat normal EOF
1322 delete $self->{_rw};
1327 $self->{_eof} = 1; 1323 $self->{_eof} = 1;
1328 $self->_shutdown; 1324 &_freetls;
1329 return;
1330 } 1325 }
1331 }
1332 1326
1327 $self->{rbuf} .= $tmp;
1328 $self->_drain_rbuf unless $self->{_in_drain};
1329 $self->{tls} or return; # tls session might have gone away in callback
1330 }
1331
1333 my $err = Net::SSLeay::get_error ($self->{tls}, -1); 1332 $tmp = Net::SSLeay::get_error ($self->{tls}, -1);
1334 1333
1335 if ($err!= Net::SSLeay::ERROR_WANT_READ ()) { 1334 if ($tmp != Net::SSLeay::ERROR_WANT_READ ()) {
1336 if ($err == Net::SSLeay::ERROR_SYSCALL ()) { 1335 if ($tmp == Net::SSLeay::ERROR_SYSCALL ()) {
1337 return $self->_error ($!, 1); 1336 return $self->_error ($!, 1);
1338 } elsif ($err == Net::SSLeay::ERROR_SSL ()) { 1337 } elsif ($tmp == Net::SSLeay::ERROR_SSL ()) {
1339 return $self->_error (&Errno::EIO, 1); 1338 return $self->_error (&Errno::EIO, 1);
1340 } 1339 }
1341 1340
1342 # all others are fine for our purposes 1341 # all other errors are fine for our purposes
1342 }
1343
1344 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
1345 $self->{wbuf} .= $tmp;
1346 $self->_drain_wbuf;
1343 } 1347 }
1344} 1348}
1345 1349
1346=item $handle->starttls ($tls[, $tls_ctx]) 1350=item $handle->starttls ($tls[, $tls_ctx])
1347 1351
… …
1357 1361
1358The TLS connection object will end up in C<< $handle->{tls} >> after this 1362The 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 1363call and can be used or changed to your liking. Note that the handshake
1360might have already started when this function returns. 1364might have already started when this function returns.
1361 1365
1366If it an error to start a TLS handshake more than once per
1367AnyEvent::Handle object (this is due to bugs in OpenSSL).
1368
1362=cut 1369=cut
1363 1370
1364sub starttls { 1371sub starttls {
1365 my ($self, $ssl, $ctx) = @_; 1372 my ($self, $ssl, $ctx) = @_;
1366 1373
1367 $self->stoptls; 1374 require Net::SSLeay;
1368 1375
1376 Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object"
1377 if $self->{tls};
1378
1369 if ($ssl eq "accept") { 1379 if ($ssl eq "accept") {
1370 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ()); 1380 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ());
1371 Net::SSLeay::set_accept_state ($ssl); 1381 Net::SSLeay::set_accept_state ($ssl);
1372 } elsif ($ssl eq "connect") { 1382 } elsif ($ssl eq "connect") {
1373 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ()); 1383 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ());
… …
1382 # and mismaintained ssleay-module doesn't even offer them). 1392 # and mismaintained ssleay-module doesn't even offer them).
1383 # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html 1393 # http://www.mail-archive.com/openssl-dev@openssl.org/msg22420.html
1384 # 1394 #
1385 # in short: this is a mess. 1395 # in short: this is a mess.
1386 # 1396 #
1387 # note that we do not try to kepe the length constant between writes as we are required to do. 1397 # 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, 1398 # 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. 1399 # and we drive openssl fully in blocking mode here. Or maybe we don't - openssl seems to
1400 # have identity issues in that area.
1390 Net::SSLeay::CTX_set_mode ($self->{tls}, 1401 Net::SSLeay::CTX_set_mode ($self->{tls},
1391 (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1) 1402 (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ENABLE_PARTIAL_WRITE () } || 1)
1392 | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2)); 1403 | (eval { local $SIG{__DIE__}; Net::SSLeay::MODE_ACCEPT_MOVING_WRITE_BUFFER () } || 2));
1393 1404
1394 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1405 $self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1395 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ()); 1406 $self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1396 1407
1397 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio}); 1408 Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});
1398 1409
1399 $self->{filter_w} = sub { 1410 &_dotls; # need to trigger the initial handshake
1400 $_[0]{_tls_wbuf} .= ${$_[1]}; 1411 $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} 1412}
1408 1413
1409=item $handle->stoptls 1414=item $handle->stoptls
1410 1415
1411Destroys the SSL connection, if any. Partial read or write data will be 1416Shuts down the SSL connection - this makes a proper EOF handshake by
1412lost. 1417sending a close notify to the other side, but since OpenSSL doesn't
1418support non-blocking shut downs, it is not possible to re-use the stream
1419afterwards.
1413 1420
1414=cut 1421=cut
1415 1422
1416sub stoptls { 1423sub stoptls {
1417 my ($self) = @_; 1424 my ($self) = @_;
1418 1425
1426 if ($self->{tls}) {
1427 Net::SSLeay::shutdown ($self->{tls});
1428
1429 &_dotls;
1430
1431 # we don't give a shit. no, we do, but we can't. no...
1432 # we, we... have to use openssl :/
1433 &_freetls;
1434 }
1435}
1436
1437sub _freetls {
1438 my ($self) = @_;
1439
1440 return unless $self->{tls};
1441
1419 Net::SSLeay::free (delete $self->{tls}) if $self->{tls}; 1442 Net::SSLeay::free (delete $self->{tls});
1420 1443
1421 delete $self->{_rbio}; 1444 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} 1445}
1427 1446
1428sub DESTROY { 1447sub DESTROY {
1429 my $self = shift; 1448 my $self = shift;
1430 1449
1431 $self->stoptls; 1450 &_freetls;
1432 1451
1433 my $linger = exists $self->{linger} ? $self->{linger} : 3600; 1452 my $linger = exists $self->{linger} ? $self->{linger} : 3600;
1434 1453
1435 if ($linger && length $self->{wbuf}) { 1454 if ($linger && length $self->{wbuf}) {
1436 my $fh = delete $self->{fh}; 1455 my $fh = delete $self->{fh};
… …
1451 @linger = (); 1470 @linger = ();
1452 }); 1471 });
1453 } 1472 }
1454} 1473}
1455 1474
1475=item $handle->destroy
1476
1477Shuts down the handle object as much as possible - this call ensures that
1478no further callbacks will be invoked and resources will be freed as much
1479as possible. You must not call any methods on the object afterwards.
1480
1481Normally, you can just "forget" any references to an AnyEvent::Handle
1482object and it will simply shut down. This works in fatal error and EOF
1483callbacks, as well as code outside. It does I<NOT> work in a read or write
1484callback, so when you want to destroy the AnyEvent::Handle object from
1485within such an callback. You I<MUST> call C<< ->destroy >> explicitly in
1486that case.
1487
1488The handle might still linger in the background and write out remaining
1489data, as specified by the C<linger> option, however.
1490
1491=cut
1492
1493sub destroy {
1494 my ($self) = @_;
1495
1496 $self->DESTROY;
1497 %$self = ();
1498}
1499
1456=item AnyEvent::Handle::TLS_CTX 1500=item AnyEvent::Handle::TLS_CTX
1457 1501
1458This function creates and returns the Net::SSLeay::CTX object used by 1502This function creates and returns the Net::SSLeay::CTX object used by
1459default for TLS mode. 1503default for TLS mode.
1460 1504
… …
1488 } 1532 }
1489} 1533}
1490 1534
1491=back 1535=back
1492 1536
1537
1538=head1 NONFREQUENTLY ASKED QUESTIONS
1539
1540=over 4
1541
1542=item I C<undef> the AnyEvent::Handle reference inside my callback and
1543still get further invocations!
1544
1545That's because AnyEvent::Handle keeps a reference to itself when handling
1546read or write callbacks.
1547
1548It is only safe to "forget" the reference inside EOF or error callbacks,
1549from within all other callbacks, you need to explicitly call the C<<
1550->destroy >> method.
1551
1552=item I get different callback invocations in TLS mode/Why can't I pause
1553reading?
1554
1555Unlike, say, TCP, TLS connections do not consist of two independent
1556communication channels, one for each direction. Or put differently. The
1557read and write directions are not independent of each other: you cannot
1558write data unless you are also prepared to read, and vice versa.
1559
1560This can mean than, in TLS mode, you might get C<on_error> or C<on_eof>
1561callback invocations when you are not expecting any read data - the reason
1562is that AnyEvent::Handle always reads in TLS mode.
1563
1564During the connection, you have to make sure that you always have a
1565non-empty read-queue, or an C<on_read> watcher. At the end of the
1566connection (or when you no longer want to use it) you can call the
1567C<destroy> method.
1568
1569=item How do I read data until the other side closes the connection?
1570
1571If you just want to read your data into a perl scalar, the easiest way
1572to achieve this is by setting an C<on_read> callback that does nothing,
1573clearing the C<on_eof> callback and in the C<on_error> callback, the data
1574will be in C<$_[0]{rbuf}>:
1575
1576 $handle->on_read (sub { });
1577 $handle->on_eof (undef);
1578 $handle->on_error (sub {
1579 my $data = delete $_[0]{rbuf};
1580 undef $handle;
1581 });
1582
1583The reason to use C<on_error> is that TCP connections, due to latencies
1584and packets loss, might get closed quite violently with an error, when in
1585fact, all data has been received.
1586
1587It is usually better to use acknowledgements when transferring data,
1588to make sure the other side hasn't just died and you got the data
1589intact. This is also one reason why so many internet protocols have an
1590explicit QUIT command.
1591
1592=item I don't want to destroy the handle too early - how do I wait until
1593all data has been written?
1594
1595After writing your last bits of data, set the C<on_drain> callback
1596and destroy the handle in there - with the default setting of
1597C<low_water_mark> this will be called precisely when all data has been
1598written to the socket:
1599
1600 $handle->push_write (...);
1601 $handle->on_drain (sub {
1602 warn "all data submitted to the kernel\n";
1603 undef $handle;
1604 });
1605
1606=back
1607
1608
1493=head1 SUBCLASSING AnyEvent::Handle 1609=head1 SUBCLASSING AnyEvent::Handle
1494 1610
1495In many cases, you might want to subclass AnyEvent::Handle. 1611In many cases, you might want to subclass AnyEvent::Handle.
1496 1612
1497To make this easier, a given version of AnyEvent::Handle uses these 1613To make this easier, a given version of AnyEvent::Handle uses these

Diff Legend

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