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.93 by root, Wed Oct 1 14:49:23 2008 UTC vs.
Revision 1.121 by root, Fri Mar 27 10:49:50 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.3; 19our $VERSION = 4.35;
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");
59treatment of characters applies to this module as well. 59treatment of characters applies to this module as well.
60 60
61All callbacks will be invoked with the handle object as their first 61All callbacks will be invoked with the handle object as their first
62argument. 62argument.
63 63
64=head2 SIGPIPE is not handled by this module
65
66SIGPIPE is not handled by this module, so one of the practical
67requirements of using it is to ignore SIGPIPE (C<$SIG{PIPE} =
68'IGNORE'>). At least, this is highly recommend in a networked program: If
69you use AnyEvent::Handle in a filter program (like sort), exiting on
70SIGPIPE is probably the right thing to do.
71
72=head1 METHODS 64=head1 METHODS
73 65
74=over 4 66=over 4
75 67
76=item B<new (%args)> 68=item B<new (%args)>
92Set 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,
93i.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
94connection cleanly. 86connection cleanly.
95 87
96For 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,
97you 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
98callback 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
99down. 91down.
100 92
101While 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,
102otherwise 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
103waiting for data. 95waiting for data.
104 96
105If 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
106set, 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>.
135and no read request is in the queue (unlike read queue callbacks, this 127and no read request is in the queue (unlike read queue callbacks, this
136callback will only be called when at least one octet of data is in the 128callback will only be called when at least one octet of data is in the
137read buffer). 129read buffer).
138 130
139To access (and remove data from) the read buffer, use the C<< ->rbuf >> 131To access (and remove data from) the read buffer, use the C<< ->rbuf >>
140method or access the C<$handle->{rbuf}> member directly. 132method or access the C<$handle->{rbuf}> member directly. Note that you
133must not enlarge or modify the read buffer, you can only remove data at
134the beginning from it.
141 135
142When an EOF condition is detected then AnyEvent::Handle will first try to 136When an EOF condition is detected then AnyEvent::Handle will first try to
143feed all the remaining data to the queued callbacks and C<on_read> before 137feed all the remaining data to the queued callbacks and C<on_read> before
144calling the C<on_eof> callback. If no progress can be made, then a fatal 138calling the C<on_eof> callback. If no progress can be made, then a fatal
145error will be raised (with C<$!> set to C<EPIPE>). 139error will be raised (with C<$!> set to C<EPIPE>).
263You can also provide your own TLS connection object, but you have 257You can also provide your own TLS connection object, but you have
264to make sure that you call either C<Net::SSLeay::set_connect_state> 258to make sure that you call either C<Net::SSLeay::set_connect_state>
265or C<Net::SSLeay::set_accept_state> on it before you pass it to 259or C<Net::SSLeay::set_accept_state> on it before you pass it to
266AnyEvent::Handle. 260AnyEvent::Handle.
267 261
262B<IMPORTANT:> since Net::SSLeay "objects" are really only integers,
263passing in the wrong integer will lead to certain crash. This most often
264happens when one uses a stylish C<< tls => 1 >> and is surprised about the
265segmentation fault.
266
268See the C<< ->starttls >> method for when need to start TLS negotiation later. 267See the C<< ->starttls >> method for when need to start TLS negotiation later.
269 268
270=item tls_ctx => $ssl_ctx 269=item tls_ctx => $ssl_ctx
271 270
272Use the given C<Net::SSLeay::CTX> object to create the new TLS connection 271Use the given C<Net::SSLeay::CTX> object to create the new TLS connection
295 294
296 $self->{fh} or Carp::croak "mandatory argument fh is missing"; 295 $self->{fh} or Carp::croak "mandatory argument fh is missing";
297 296
298 AnyEvent::Util::fh_nonblocking $self->{fh}, 1; 297 AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
299 298
300 if ($self->{tls}) {
301 require Net::SSLeay;
302 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx}); 299 $self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
303 } 300 if $self->{tls};
304 301
305 $self->{_activity} = AnyEvent->now; 302 $self->{_activity} = AnyEvent->now;
306 $self->_timeout; 303 $self->_timeout;
307 304
308 $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain}; 305 $self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain};
336 333
337 $! = $errno; 334 $! = $errno;
338 335
339 if ($self->{on_error}) { 336 if ($self->{on_error}) {
340 $self->{on_error}($self, $fatal); 337 $self->{on_error}($self, $fatal);
341 } else { 338 } elsif ($self->{fh}) {
342 Carp::croak "AnyEvent::Handle uncaught error: $!"; 339 Carp::croak "AnyEvent::Handle uncaught error: $!";
343 } 340 }
344} 341}
345 342
346=item $fh = $handle->fh 343=item $fh = $handle->fh
384} 381}
385 382
386=item $handle->autocork ($boolean) 383=item $handle->autocork ($boolean)
387 384
388Enables or disables the current autocork behaviour (see C<autocork> 385Enables or disables the current autocork behaviour (see C<autocork>
389constructor argument). 386constructor argument). Changes will only take effect on the next write.
390 387
391=cut 388=cut
389
390sub autocork {
391 $_[0]{autocork} = $_[1];
392}
392 393
393=item $handle->no_delay ($boolean) 394=item $handle->no_delay ($boolean)
394 395
395Enables or disables the C<no_delay> setting (see constructor argument of 396Enables or disables the C<no_delay> setting (see constructor argument of
396the same name for details). 397the same name for details).
552 ->($self, @_); 553 ->($self, @_);
553 } 554 }
554 555
555 if ($self->{tls}) { 556 if ($self->{tls}) {
556 $self->{_tls_wbuf} .= $_[0]; 557 $self->{_tls_wbuf} .= $_[0];
558
557 &_dotls ($self); 559 &_dotls ($self);
558 } else { 560 } else {
559 $self->{wbuf} .= $_[0]; 561 $self->{wbuf} .= $_[0];
560 $self->_drain_wbuf; 562 $self->_drain_wbuf;
561 } 563 }
579=cut 581=cut
580 582
581register_write_type netstring => sub { 583register_write_type netstring => sub {
582 my ($self, $string) = @_; 584 my ($self, $string) = @_;
583 585
584 sprintf "%d:%s,", (length $string), $string 586 (length $string) . ":$string,"
585}; 587};
586 588
587=item packstring => $format, $data 589=item packstring => $format, $data
588 590
589An octet string prefixed with an encoded length. The encoding C<$format> 591An octet string prefixed with an encoded length. The encoding C<$format>
767 ) { 769 ) {
768 $self->_error (&Errno::ENOSPC, 1), return; 770 $self->_error (&Errno::ENOSPC, 1), return;
769 } 771 }
770 772
771 while () { 773 while () {
774 # we need to use a separate tls read buffer, as we must not receive data while
775 # we are draining the buffer, and this can only happen with TLS.
776 $self->{rbuf} .= delete $self->{_tls_rbuf} if exists $self->{_tls_rbuf};
777
772 my $len = length $self->{rbuf}; 778 my $len = length $self->{rbuf};
773 779
774 if (my $cb = shift @{ $self->{_queue} }) { 780 if (my $cb = shift @{ $self->{_queue} }) {
775 unless ($cb->($self)) { 781 unless ($cb->($self)) {
776 if ($self->{_eof}) { 782 if ($self->{_eof}) {
837 843
838=item $handle->rbuf 844=item $handle->rbuf
839 845
840Returns the read buffer (as a modifiable lvalue). 846Returns the read buffer (as a modifiable lvalue).
841 847
842You can access the read buffer directly as the C<< ->{rbuf} >> member, if 848You can access the read buffer directly as the C<< ->{rbuf} >>
843you want. 849member, if you want. However, the only operation allowed on the
850read buffer (apart from looking at it) is removing data from its
851beginning. Otherwise modifying or appending to it is not allowed and will
852lead to hard-to-track-down bugs.
844 853
845NOTE: The read buffer should only be used or modified if the C<on_read>, 854NOTE: The read buffer should only be used or modified if the C<on_read>,
846C<push_read> or C<unshift_read> methods are used. The other read methods 855C<push_read> or C<unshift_read> methods are used. The other read methods
847automatically manage the read buffer. 856automatically manage the read buffer.
848 857
1103An octet string prefixed with an encoded length. The encoding C<$format> 1112An octet string prefixed with an encoded length. The encoding C<$format>
1104uses the same format as a Perl C<pack> format, but must specify a single 1113uses the same format as a Perl C<pack> format, but must specify a single
1105integer only (only one of C<cCsSlLqQiInNvVjJw> is allowed, plus an 1114integer only (only one of C<cCsSlLqQiInNvVjJw> is allowed, plus an
1106optional C<!>, C<< < >> or C<< > >> modifier). 1115optional C<!>, C<< < >> or C<< > >> modifier).
1107 1116
1108DNS over TCP uses a prefix of C<n>, EPP uses a prefix of C<N>. 1117For example, DNS over TCP uses a prefix of C<n> (2 octet network order),
1118EPP uses a prefix of C<N> (4 octtes).
1109 1119
1110Example: read a block of data prefixed by its length in BER-encoded 1120Example: read a block of data prefixed by its length in BER-encoded
1111format (very efficient). 1121format (very efficient).
1112 1122
1113 $handle->push_read (packstring => "w", sub { 1123 $handle->push_read (packstring => "w", sub {
1143 } 1153 }
1144}; 1154};
1145 1155
1146=item json => $cb->($handle, $hash_or_arrayref) 1156=item json => $cb->($handle, $hash_or_arrayref)
1147 1157
1148Reads a JSON object or array, decodes it and passes it to the callback. 1158Reads a JSON object or array, decodes it and passes it to the
1159callback. When a parse error occurs, an C<EBADMSG> error will be raised.
1149 1160
1150If a C<json> object was passed to the constructor, then that will be used 1161If a C<json> object was passed to the constructor, then that will be used
1151for the final decode, otherwise it will create a JSON coder expecting UTF-8. 1162for the final decode, otherwise it will create a JSON coder expecting UTF-8.
1152 1163
1153This read type uses the incremental parser available with JSON version 1164This read type uses the incremental parser available with JSON version
1170 my $rbuf = \$self->{rbuf}; 1181 my $rbuf = \$self->{rbuf};
1171 1182
1172 my $json = $self->{json} ||= JSON->new->utf8; 1183 my $json = $self->{json} ||= JSON->new->utf8;
1173 1184
1174 sub { 1185 sub {
1175 my $ref = $json->incr_parse ($self->{rbuf}); 1186 my $ref = eval { $json->incr_parse ($self->{rbuf}) };
1176 1187
1177 if ($ref) { 1188 if ($ref) {
1178 $self->{rbuf} = $json->incr_text; 1189 $self->{rbuf} = $json->incr_text;
1179 $json->incr_text = ""; 1190 $json->incr_text = "";
1180 $cb->($self, $ref); 1191 $cb->($self, $ref);
1181 1192
1182 1 1193 1
1194 } elsif ($@) {
1195 # error case
1196 $json->incr_skip;
1197
1198 $self->{rbuf} = $json->incr_text;
1199 $json->incr_text = "";
1200
1201 $self->_error (&Errno::EBADMSG);
1202
1203 ()
1183 } else { 1204 } else {
1184 $self->{rbuf} = ""; 1205 $self->{rbuf} = "";
1206
1185 () 1207 ()
1186 } 1208 }
1187 } 1209 }
1188}; 1210};
1189 1211
1292 if ($len > 0) { 1314 if ($len > 0) {
1293 $self->{_activity} = AnyEvent->now; 1315 $self->{_activity} = AnyEvent->now;
1294 1316
1295 if ($self->{tls}) { 1317 if ($self->{tls}) {
1296 Net::SSLeay::BIO_write ($self->{_rbio}, $$rbuf); 1318 Net::SSLeay::BIO_write ($self->{_rbio}, $$rbuf);
1319
1297 &_dotls ($self); 1320 &_dotls ($self);
1298 } else { 1321 } else {
1299 $self->_drain_rbuf unless $self->{_in_drain}; 1322 $self->_drain_rbuf unless $self->{_in_drain};
1300 } 1323 }
1301 1324
1309 } 1332 }
1310 }); 1333 });
1311 } 1334 }
1312} 1335}
1313 1336
1337# poll the write BIO and send the data if applicable
1314sub _dotls { 1338sub _dotls {
1315 my ($self) = @_; 1339 my ($self) = @_;
1316 1340
1317 my $buf; 1341 my $tmp;
1318 1342
1319 if (length $self->{_tls_wbuf}) { 1343 if (length $self->{_tls_wbuf}) {
1320 while ((my $len = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) { 1344 while (($tmp = Net::SSLeay::write ($self->{tls}, $self->{_tls_wbuf})) > 0) {
1321 substr $self->{_tls_wbuf}, 0, $len, ""; 1345 substr $self->{_tls_wbuf}, 0, $tmp, "";
1322 } 1346 }
1323 } 1347 }
1324 1348
1325 while (defined ($buf = Net::SSLeay::read ($self->{tls}))) { 1349 while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
1326 unless (length $buf) { 1350 unless (length $tmp) {
1327 # let's treat SSL-eof as we treat normal EOF 1351 # let's treat SSL-eof as we treat normal EOF
1328 delete $self->{_rw}; 1352 delete $self->{_rw};
1329 $self->{_eof} = 1; 1353 $self->{_eof} = 1;
1330 &_freetls; 1354 &_freetls;
1331 } 1355 }
1332 1356
1333 $self->{rbuf} .= $buf; 1357 $self->{_tls_rbuf} .= $tmp;
1334 $self->_drain_rbuf unless $self->{_in_drain}; 1358 $self->_drain_rbuf unless $self->{_in_drain};
1335 $self->{tls} or return; # tls session might have gone away in callback 1359 $self->{tls} or return; # tls session might have gone away in callback
1336 } 1360 }
1337 1361
1338 my $err = Net::SSLeay::get_error ($self->{tls}, -1); 1362 $tmp = Net::SSLeay::get_error ($self->{tls}, -1);
1339 1363
1340 if ($err!= Net::SSLeay::ERROR_WANT_READ ()) { 1364 if ($tmp != Net::SSLeay::ERROR_WANT_READ ()) {
1341 if ($err == Net::SSLeay::ERROR_SYSCALL ()) { 1365 if ($tmp == Net::SSLeay::ERROR_SYSCALL ()) {
1342 return $self->_error ($!, 1); 1366 return $self->_error ($!, 1);
1343 } elsif ($err == Net::SSLeay::ERROR_SSL ()) { 1367 } elsif ($tmp == Net::SSLeay::ERROR_SSL ()) {
1344 return $self->_error (&Errno::EIO, 1); 1368 return $self->_error (&Errno::EIO, 1);
1345 } 1369 }
1346 1370
1347 # all others are fine for our purposes 1371 # all other errors are fine for our purposes
1348 } 1372 }
1349 1373
1350 if (length ($buf = Net::SSLeay::BIO_read ($self->{_wbio}))) { 1374 while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
1351 $self->{wbuf} .= $buf; 1375 $self->{wbuf} .= $tmp;
1352 $self->_drain_wbuf; 1376 $self->_drain_wbuf;
1353 } 1377 }
1354} 1378}
1355 1379
1356=item $handle->starttls ($tls[, $tls_ctx]) 1380=item $handle->starttls ($tls[, $tls_ctx])
1375=cut 1399=cut
1376 1400
1377sub starttls { 1401sub starttls {
1378 my ($self, $ssl, $ctx) = @_; 1402 my ($self, $ssl, $ctx) = @_;
1379 1403
1404 require Net::SSLeay;
1405
1380 Carp::croak "it is an error to call starttls more than once on an Anyevent::Handle object" 1406 Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object"
1381 if $self->{tls}; 1407 if $self->{tls};
1382 1408
1383 if ($ssl eq "accept") { 1409 if ($ssl eq "accept") {
1384 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ()); 1410 $ssl = Net::SSLeay::new ($ctx || TLS_CTX ());
1385 Net::SSLeay::set_accept_state ($ssl); 1411 Net::SSLeay::set_accept_state ($ssl);
1426 1452
1427sub stoptls { 1453sub stoptls {
1428 my ($self) = @_; 1454 my ($self) = @_;
1429 1455
1430 if ($self->{tls}) { 1456 if ($self->{tls}) {
1431 Net::SSLeay::shutdown $self->{tls}; 1457 Net::SSLeay::shutdown ($self->{tls});
1432 1458
1433 &_dotls; 1459 &_dotls;
1434 1460
1435 # we don't give a shit. no, we do, but we can't. no... 1461 # we don't give a shit. no, we do, but we can't. no...
1436 # we, we... have to use openssl :/ 1462 # we, we... have to use openssl :/
1447 1473
1448 delete @$self{qw(_rbio _wbio _tls_wbuf)}; 1474 delete @$self{qw(_rbio _wbio _tls_wbuf)};
1449} 1475}
1450 1476
1451sub DESTROY { 1477sub DESTROY {
1452 my $self = shift; 1478 my ($self) = @_;
1453 1479
1454 &_freetls; 1480 &_freetls;
1455 1481
1456 my $linger = exists $self->{linger} ? $self->{linger} : 3600; 1482 my $linger = exists $self->{linger} ? $self->{linger} : 3600;
1457 1483
1474 @linger = (); 1500 @linger = ();
1475 }); 1501 });
1476 } 1502 }
1477} 1503}
1478 1504
1505=item $handle->destroy
1506
1507Shuts down the handle object as much as possible - this call ensures that
1508no further callbacks will be invoked and resources will be freed as much
1509as possible. You must not call any methods on the object afterwards.
1510
1511Normally, you can just "forget" any references to an AnyEvent::Handle
1512object and it will simply shut down. This works in fatal error and EOF
1513callbacks, as well as code outside. It does I<NOT> work in a read or write
1514callback, so when you want to destroy the AnyEvent::Handle object from
1515within such an callback. You I<MUST> call C<< ->destroy >> explicitly in
1516that case.
1517
1518The handle might still linger in the background and write out remaining
1519data, as specified by the C<linger> option, however.
1520
1521=cut
1522
1523sub destroy {
1524 my ($self) = @_;
1525
1526 $self->DESTROY;
1527 %$self = ();
1528}
1529
1479=item AnyEvent::Handle::TLS_CTX 1530=item AnyEvent::Handle::TLS_CTX
1480 1531
1481This function creates and returns the Net::SSLeay::CTX object used by 1532This function creates and returns the Net::SSLeay::CTX object used by
1482default for TLS mode. 1533default for TLS mode.
1483 1534
1511 } 1562 }
1512} 1563}
1513 1564
1514=back 1565=back
1515 1566
1567
1568=head1 NONFREQUENTLY ASKED QUESTIONS
1569
1570=over 4
1571
1572=item I C<undef> the AnyEvent::Handle reference inside my callback and
1573still get further invocations!
1574
1575That's because AnyEvent::Handle keeps a reference to itself when handling
1576read or write callbacks.
1577
1578It is only safe to "forget" the reference inside EOF or error callbacks,
1579from within all other callbacks, you need to explicitly call the C<<
1580->destroy >> method.
1581
1582=item I get different callback invocations in TLS mode/Why can't I pause
1583reading?
1584
1585Unlike, say, TCP, TLS connections do not consist of two independent
1586communication channels, one for each direction. Or put differently. The
1587read and write directions are not independent of each other: you cannot
1588write data unless you are also prepared to read, and vice versa.
1589
1590This can mean than, in TLS mode, you might get C<on_error> or C<on_eof>
1591callback invocations when you are not expecting any read data - the reason
1592is that AnyEvent::Handle always reads in TLS mode.
1593
1594During the connection, you have to make sure that you always have a
1595non-empty read-queue, or an C<on_read> watcher. At the end of the
1596connection (or when you no longer want to use it) you can call the
1597C<destroy> method.
1598
1599=item How do I read data until the other side closes the connection?
1600
1601If you just want to read your data into a perl scalar, the easiest way
1602to achieve this is by setting an C<on_read> callback that does nothing,
1603clearing the C<on_eof> callback and in the C<on_error> callback, the data
1604will be in C<$_[0]{rbuf}>:
1605
1606 $handle->on_read (sub { });
1607 $handle->on_eof (undef);
1608 $handle->on_error (sub {
1609 my $data = delete $_[0]{rbuf};
1610 undef $handle;
1611 });
1612
1613The reason to use C<on_error> is that TCP connections, due to latencies
1614and packets loss, might get closed quite violently with an error, when in
1615fact, all data has been received.
1616
1617It is usually better to use acknowledgements when transferring data,
1618to make sure the other side hasn't just died and you got the data
1619intact. This is also one reason why so many internet protocols have an
1620explicit QUIT command.
1621
1622=item I don't want to destroy the handle too early - how do I wait until
1623all data has been written?
1624
1625After writing your last bits of data, set the C<on_drain> callback
1626and destroy the handle in there - with the default setting of
1627C<low_water_mark> this will be called precisely when all data has been
1628written to the socket:
1629
1630 $handle->push_write (...);
1631 $handle->on_drain (sub {
1632 warn "all data submitted to the kernel\n";
1633 undef $handle;
1634 });
1635
1636=back
1637
1638
1516=head1 SUBCLASSING AnyEvent::Handle 1639=head1 SUBCLASSING AnyEvent::Handle
1517 1640
1518In many cases, you might want to subclass AnyEvent::Handle. 1641In many cases, you might want to subclass AnyEvent::Handle.
1519 1642
1520To make this easier, a given version of AnyEvent::Handle uses these 1643To make this easier, a given version of AnyEvent::Handle uses these

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines