[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent/Handle.pm

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.135 by root, Fri Jul 3 08:51:48 2009 UTC vs.
Revision 1.149 by root, Thu Jul 16 03:48:33 2009 UTC

…		…
14		14
15	AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent	15	AnyEvent::Handle - non-blocking I/O on file handles via AnyEvent
16		16
17	=cut	17	=cut
18		18
19	our $VERSION = 4.45;	19	our $VERSION = 4.82;
20		20
21	=head1 SYNOPSIS	21	=head1 SYNOPSIS
22		22
23	use AnyEvent;	23	use AnyEvent;
24	use AnyEvent::Handle;	24	use AnyEvent::Handle;
25		25
26	my $cv = AnyEvent->condvar;	26	my $cv = AnyEvent->condvar;
27		27
28	my $handle =	28	my $hdl; $hdl = new AnyEvent::Handle
29	AnyEvent::Handle->new (
30	fh => \*STDIN,	29	fh => \*STDIN,
31	on_eof => sub {	30	on_error => sub {
		31	warn "got error $_[2]\n";
32	$cv->send;	32	$cv->send;
33	},
34	);	33	);
35		34
36	# send some request line	35	# send some request line
37	$handle->push_write ("getinfo\015\012");	36	$hdl->push_write ("getinfo\015\012");
38		37
39	# read the response line	38	# read the response line
40	$handle->push_read (line => sub {	39	$hdl->push_read (line => sub {
41	my ($handle, $line) = @_;	40	my ($hdl, $line) = @_;
42	warn "read line <$line>\n";	41	warn "got line <$line>\n";
43	$cv->send;	42	$cv->send;
44	});	43	});
45		44
46	$cv->recv;	45	$cv->recv;
47		46
…		…
102	This is the error callback, which is called when, well, some error	101	This is the error callback, which is called when, well, some error
103	occured, such as not being able to resolve the hostname, failure to	102	occured, such as not being able to resolve the hostname, failure to
104	connect or a read error.	103	connect or a read error.
105		104
106	Some errors are fatal (which is indicated by C<$fatal> being true). On	105	Some errors are fatal (which is indicated by C<$fatal> being true). On
107	fatal errors the handle object will be shut down and will not be usable	106	fatal errors the handle object will be destroyed (by a call to C<< ->
108	(but you are free to look at the current C<< ->rbuf >>). Examples of fatal	107	destroy >>) after invoking the error callback (which means you are free to
109	errors are an EOF condition with active (but unsatisifable) read watchers	108	examine the handle object). Examples of fatal errors are an EOF condition
110	(C<EPIPE>) or I/O errors.	109	with active (but unsatisifable) read watchers (C<EPIPE>) or I/O errors.
111		110
112	AnyEvent::Handle tries to find an appropriate error code for you to check	111	AnyEvent::Handle tries to find an appropriate error code for you to check
113	against, but in some cases (TLS errors), this does not work well. It is	112	against, but in some cases (TLS errors), this does not work well. It is
114	recommended to always output the C<$message> argument in human-readable	113	recommended to always output the C<$message> argument in human-readable
115	error messages (it's usually the same as C<"$!">).	114	error messages (it's usually the same as C<"$!">).
…		…
133	and no read request is in the queue (unlike read queue callbacks, this	132	and no read request is in the queue (unlike read queue callbacks, this
134	callback will only be called when at least one octet of data is in the	133	callback will only be called when at least one octet of data is in the
135	read buffer).	134	read buffer).
136		135
137	To access (and remove data from) the read buffer, use the C<< ->rbuf >>	136	To access (and remove data from) the read buffer, use the C<< ->rbuf >>
138	method or access the C<$handle->{rbuf}> member directly. Note that you	137	method or access the C<< $handle->{rbuf} >> member directly. Note that you
139	must not enlarge or modify the read buffer, you can only remove data at	138	must not enlarge or modify the read buffer, you can only remove data at
140	the beginning from it.	139	the beginning from it.
141		140
142	When an EOF condition is detected then AnyEvent::Handle will first try to	141	When an EOF condition is detected then AnyEvent::Handle will first try to
143	feed all the remaining data to the queued callbacks and C<on_read> before	142	feed all the remaining data to the queued callbacks and C<on_read> before
…		…
249		248
250	A string used to identify the remote site - usually the DNS hostname	249	A string used to identify the remote site - usually the DNS hostname
251	(I<not> IDN!) used to create the connection, rarely the IP address.	250	(I<not> IDN!) used to create the connection, rarely the IP address.
252		251
253	Apart from being useful in error messages, this string is also used in TLS	252	Apart from being useful in error messages, this string is also used in TLS
254	common name verification (see C<verify_cn> in L<AnyEvent::TLS>).	253	peername verification (see C<verify_peername> in L<AnyEvent::TLS>). This
		254	verification will be skipped when C<peername> is not specified or
		255	C<undef>.
255		256
256	=item tls => "accept" \| "connect" \| Net::SSLeay::SSL object	257	=item tls => "accept" \| "connect" \| Net::SSLeay::SSL object
257		258
258	When this parameter is given, it enables TLS (SSL) mode, that means	259	When this parameter is given, it enables TLS (SSL) mode, that means
259	AnyEvent will start a TLS handshake as soon as the conenction has been	260	AnyEvent will start a TLS handshake as soon as the conenction has been
…		…
296		297
297	Instead of an object, you can also specify a hash reference with C<< key	298	Instead of an object, you can also specify a hash reference with C<< key
298	=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a	299	=> value >> pairs. Those will be passed to L<AnyEvent::TLS> to create a
299	new TLS context object.	300	new TLS context object.
300		301
		302	=item on_starttls => $cb->($handle, $success[, $error_message])
		303
		304	This callback will be invoked when the TLS/SSL handshake has finished. If
		305	C<$success> is true, then the TLS handshake succeeded, otherwise it failed
		306	(C<on_stoptls> will not be called in this case).
		307
		308	The session in C<< $handle->{tls} >> can still be examined in this
		309	callback, even when the handshake was not successful.
		310
		311	TLS handshake failures will not cause C<on_error> to be invoked when this
		312	callback is in effect, instead, the error message will be passed to C<on_starttls>.
		313
		314	Without this callback, handshake failures lead to C<on_error> being
		315	called, as normal.
		316
		317	Note that you cannot call C<starttls> right again in this callback. If you
		318	need to do that, start an zero-second timer instead whose callback can
		319	then call C<< ->starttls >> again.
		320
		321	=item on_stoptls => $cb->($handle)
		322
		323	When a SSLv3/TLS shutdown/close notify/EOF is detected and this callback is
		324	set, then it will be invoked after freeing the TLS session. If it is not,
		325	then a TLS shutdown condition will be treated like a normal EOF condition
		326	on the handle.
		327
		328	The session in C<< $handle->{tls} >> can still be examined in this
		329	callback.
		330
		331	This callback will only be called on TLS shutdowns, not when the
		332	underlying handle signals EOF.
		333
301	=item json => JSON or JSON::XS object	334	=item json => JSON or JSON::XS object
302		335
303	This is the json coder object used by the C<json> read and write types.	336	This is the json coder object used by the C<json> read and write types.
304		337
305	If you don't supply it, then AnyEvent::Handle will create and use a	338	If you don't supply it, then AnyEvent::Handle will create and use a
…		…
327	$self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};	360	$self->no_delay (delete $self->{no_delay}) if exists $self->{no_delay};
328		361
329	$self->starttls (delete $self->{tls}, delete $self->{tls_ctx})	362	$self->starttls (delete $self->{tls}, delete $self->{tls_ctx})
330	if $self->{tls};	363	if $self->{tls};
331		364
332	$self->on_drain (delete $self->{on_drain}) if exists $self->{on_drain};	365	$self->on_drain (delete $self->{on_drain}) if $self->{on_drain};
333		366
334	$self->start_read	367	$self->start_read
335	if $self->{on_read};	368	if $self->{on_read};
336		369
337	$self->{fh} && $self	370	$self->{fh} && $self
338	}	371	}
339		372
340	sub _shutdown {	373	#sub _shutdown {
341	my ($self) = @_;	374	# my ($self) = @_;
342		375	#
343	delete @$self{qw(_tw _rw _ww fh wbuf on_read _queue)};	376	# delete @$self{qw(_tw _rw _ww fh wbuf on_read _queue)};
344	$self->{_eof} = 1; # tell starttls et. al to stop trying	377	# $self->{_eof} = 1; # tell starttls et. al to stop trying
345		378	#
346	&_freetls;	379	# &_freetls;
347	}	380	#}
348		381
349	sub _error {	382	sub _error {
350	my ($self, $errno, $fatal, $message) = @_;	383	my ($self, $errno, $fatal, $message) = @_;
351		384
352	$self->_shutdown
353	if $fatal;
354
355	$! = $errno;	385	$! = $errno;
356	$message \|\|= "$!";	386	$message \|\|= "$!";
357		387
358	if ($self->{on_error}) {	388	if ($self->{on_error}) {
359	$self->{on_error}($self, $fatal, $message);	389	$self->{on_error}($self, $fatal, $message);
		390	$self->destroy;
360	} elsif ($self->{fh}) {	391	} elsif ($self->{fh}) {
		392	$self->destroy;
361	Carp::croak "AnyEvent::Handle uncaught error: $message";	393	Carp::croak "AnyEvent::Handle uncaught error: $message";
362	}	394	}
363	}	395	}
364		396
365	=item $fh = $handle->fh	397	=item $fh = $handle->fh
…		…
425		457
426	eval {	458	eval {
427	local $SIG{__DIE__};	459	local $SIG{__DIE__};
428	setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1];	460	setsockopt $_[0]{fh}, &Socket::IPPROTO_TCP, &Socket::TCP_NODELAY, int $_[1];
429	};	461	};
		462	}
		463
		464	=item $handle->on_starttls ($cb)
		465
		466	Replace the current C<on_starttls> callback (see the C<on_starttls> constructor argument).
		467
		468	=cut
		469
		470	sub on_starttls {
		471	$_[0]{on_starttls} = $_[1];
		472	}
		473
		474	=item $handle->on_stoptls ($cb)
		475
		476	Replace the current C<on_stoptls> callback (see the C<on_stoptls> constructor argument).
		477
		478	=cut
		479
		480	sub on_starttls {
		481	$_[0]{on_stoptls} = $_[1];
430	}	482	}
431		483
432	#############################################################################	484	#############################################################################
433		485
434	=item $handle->timeout ($seconds)	486	=item $handle->timeout ($seconds)
…		…
533	Scalar::Util::weaken $self;	585	Scalar::Util::weaken $self;
534		586
535	my $cb = sub {	587	my $cb = sub {
536	my $len = syswrite $self->{fh}, $self->{wbuf};	588	my $len = syswrite $self->{fh}, $self->{wbuf};
537		589
538	if ($len >= 0) {	590	if (defined $len) {
539	substr $self->{wbuf}, 0, $len, "";	591	substr $self->{wbuf}, 0, $len, "";
540		592
541	$self->{_activity} = AnyEvent->now;	593	$self->{_activity} = AnyEvent->now;
542		594
543	$self->{on_drain}($self)	595	$self->{on_drain}($self)
…		…
683		735
684	=item $handle->push_shutdown	736	=item $handle->push_shutdown
685		737
686	Sometimes you know you want to close the socket after writing your data	738	Sometimes you know you want to close the socket after writing your data
687	before it was actually written. One way to do that is to replace your	739	before it was actually written. One way to do that is to replace your
688	C<on_drain> handler by a callback that shuts down the socket. This method	740	C<on_drain> handler by a callback that shuts down the socket (and set
689	is a shorthand for just that, and replaces the C<on_drain> callback with:	741	C<low_water_mark> to C<0>). This method is a shorthand for just that, and
		742	replaces the C<on_drain> callback with:
690		743
691	sub { shutdown $_[0]{fh}, 1 } # for push_shutdown	744	sub { shutdown $_[0]{fh}, 1 } # for push_shutdown
692		745
693	This simply shuts down the write side and signals an EOF condition to the	746	This simply shuts down the write side and signals an EOF condition to the
694	the peer.	747	the peer.
…		…
697	afterwards. This is the cleanest way to close a connection.	750	afterwards. This is the cleanest way to close a connection.
698		751
699	=cut	752	=cut
700		753
701	sub push_shutdown {	754	sub push_shutdown {
		755	my ($self) = @_;
		756
		757	delete $self->{low_water_mark};
702	$_[0]->{on_drain} = sub { shutdown $_[0]{fh}, 1 };	758	$self->on_drain (sub { shutdown $_[0]{fh}, 1 });
703	}	759	}
704		760
705	=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args)	761	=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args)
706		762
707	This function (not method) lets you add your own types to C<push_write>.	763	This function (not method) lets you add your own types to C<push_write>.
…		…
856		912
857	if ($self->{_eof}) {	913	if ($self->{_eof}) {
858	if ($self->{on_eof}) {	914	if ($self->{on_eof}) {
859	$self->{on_eof}($self)	915	$self->{on_eof}($self)
860	} else {	916	} else {
861	$self->_error (0, 1);	917	$self->_error (0, 1, "Unexpected end-of-file");
862	}	918	}
863	}	919	}
864		920
865	# may need to restart read watcher	921	# may need to restart read watcher
866	unless ($self->{_rw}) {	922	unless ($self->{_rw}) {
…		…
1377	}	1433	}
1378	}	1434	}
1379		1435
1380	our $ERROR_SYSCALL;	1436	our $ERROR_SYSCALL;
1381	our $ERROR_WANT_READ;	1437	our $ERROR_WANT_READ;
1382	our $ERROR_ZERO_RETURN;
1383		1438
1384	sub _tls_error {	1439	sub _tls_error {
1385	my ($self, $err) = @_;	1440	my ($self, $err) = @_;
1386	warn "$err,$!\n";#d#
1387		1441
1388	return $self->_error ($!, 1)	1442	return $self->_error ($!, 1)
1389	if $err == Net::SSLeay::ERROR_SYSCALL ();	1443	if $err == Net::SSLeay::ERROR_SYSCALL ();
1390		1444
		1445	my $err =Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ());
		1446
		1447	# reduce error string to look less scary
		1448	$err =~ s/^error:[0-9a-fA-F]{8}:[^:]+:([^:]+):/\L$1: /;
		1449
		1450	if ($self->{_on_starttls}) {
		1451	(delete $self->{_on_starttls})->($self, undef, $err);
		1452	&_freetls;
		1453	} else {
		1454	&_freetls;
1391	$self->_error (&Errno::EPROTO, 1,	1455	$self->_error (&Errno::EPROTO, 1, $err);
1392	Net::SSLeay::ERR_error_string (Net::SSLeay::ERR_get_error ()));	1456	}
1393	}	1457	}
1394		1458
1395	# poll the write BIO and send the data if applicable	1459	# poll the write BIO and send the data if applicable
1396	# also decode read data if possible	1460	# also decode read data if possible
1397	# this is basiclaly our TLS state machine	1461	# this is basiclaly our TLS state machine
…		…
1408	}	1472	}
1409		1473
1410	$tmp = Net::SSLeay::get_error ($self->{tls}, $tmp);	1474	$tmp = Net::SSLeay::get_error ($self->{tls}, $tmp);
1411	return $self->_tls_error ($tmp)	1475	return $self->_tls_error ($tmp)
1412	if $tmp != $ERROR_WANT_READ	1476	if $tmp != $ERROR_WANT_READ
1413	&& ($tmp != $ERROR_SYSCALL \|\| $!)	1477	&& ($tmp != $ERROR_SYSCALL \|\| $!);
1414	&& $tmp != $ERROR_ZERO_RETURN;
1415	}	1478	}
1416		1479
1417	while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {	1480	while (defined ($tmp = Net::SSLeay::read ($self->{tls}))) {
1418	unless (length $tmp) {	1481	unless (length $tmp) {
1419	# let's treat SSL-eof as we treat normal EOF	1482	$self->{_on_starttls}
1420	delete $self->{_rw};	1483	and (delete $self->{_on_starttls})->($self, undef, "EOF during handshake"); # ???
1421	$self->{_eof} = 1;
1422	&_freetls;	1484	&_freetls;
		1485
		1486	if ($self->{on_stoptls}) {
		1487	$self->{on_stoptls}($self);
		1488	return;
		1489	} else {
		1490	# let's treat SSL-eof as we treat normal EOF
		1491	delete $self->{_rw};
		1492	$self->{_eof} = 1;
		1493	}
1423	}	1494	}
1424		1495
1425	$self->{_tls_rbuf} .= $tmp;	1496	$self->{_tls_rbuf} .= $tmp;
1426	$self->_drain_rbuf unless $self->{_in_drain};	1497	$self->_drain_rbuf unless $self->{_in_drain};
1427	$self->{tls} or return; # tls session might have gone away in callback	1498	$self->{tls} or return; # tls session might have gone away in callback
1428	}	1499	}
1429		1500
1430	$tmp = Net::SSLeay::get_error ($self->{tls}, -1);	1501	$tmp = Net::SSLeay::get_error ($self->{tls}, -1);
1431	return $self->_tls_error ($tmp)	1502	return $self->_tls_error ($tmp)
1432	if $tmp != $ERROR_WANT_READ	1503	if $tmp != $ERROR_WANT_READ
1433	&& ($tmp != $ERROR_SYSCALL \|\| $!)	1504	&& ($tmp != $ERROR_SYSCALL \|\| $!);
1434	&& $tmp != $ERROR_ZERO_RETURN;
1435		1505
1436	while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {	1506	while (length ($tmp = Net::SSLeay::BIO_read ($self->{_wbio}))) {
1437	$self->{wbuf} .= $tmp;	1507	$self->{wbuf} .= $tmp;
1438	$self->_drain_wbuf;	1508	$self->_drain_wbuf;
1439	}	1509	}
		1510
		1511	$self->{_on_starttls}
		1512	and Net::SSLeay::state ($self->{tls}) == Net::SSLeay::ST_OK ()
		1513	and (delete $self->{_on_starttls})->($self, 1, "TLS/SSL connection established");
1440	}	1514	}
1441		1515
1442	=item $handle->starttls ($tls[, $tls_ctx])	1516	=item $handle->starttls ($tls[, $tls_ctx])
1443		1517
1444	Instead of starting TLS negotiation immediately when the AnyEvent::Handle	1518	Instead of starting TLS negotiation immediately when the AnyEvent::Handle
…		…
1461	If it an error to start a TLS handshake more than once per	1535	If it an error to start a TLS handshake more than once per
1462	AnyEvent::Handle object (this is due to bugs in OpenSSL).	1536	AnyEvent::Handle object (this is due to bugs in OpenSSL).
1463		1537
1464	=cut	1538	=cut
1465		1539
		1540	our %TLS_CACHE; #TODO not yet documented, should we?
		1541
1466	sub starttls {	1542	sub starttls {
1467	my ($self, $ssl, $ctx) = @_;	1543	my ($self, $ssl, $ctx) = @_;
1468		1544
1469	require Net::SSLeay;	1545	require Net::SSLeay;
1470		1546
1471	Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object"	1547	Carp::croak "it is an error to call starttls more than once on an AnyEvent::Handle object"
1472	if $self->{tls};	1548	if $self->{tls};
1473		1549
1474	$ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL ();	1550	$ERROR_SYSCALL = Net::SSLeay::ERROR_SYSCALL ();
1475	$ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ ();	1551	$ERROR_WANT_READ = Net::SSLeay::ERROR_WANT_READ ();
1476	$ERROR_ZERO_RETURN = Net::SSLeay::ERROR_ZERO_RETURN ();
1477		1552
1478	$ctx \|\|= $self->{tls_ctx};	1553	$ctx \|\|= $self->{tls_ctx};
1479		1554
1480	if ("HASH" eq ref $ctx) {	1555	if ("HASH" eq ref $ctx) {
1481	require AnyEvent::TLS;	1556	require AnyEvent::TLS;
1482		1557
1483	local $Carp::CarpLevel = 1; # skip ourselves when creating a new context	1558	local $Carp::CarpLevel = 1; # skip ourselves when creating a new context
		1559
		1560	if ($ctx->{cache}) {
		1561	my $key = $ctx+0;
		1562	$ctx = $TLS_CACHE{$key} \|\|= new AnyEvent::TLS %$ctx;
		1563	} else {
1484	$ctx = new AnyEvent::TLS %$ctx;	1564	$ctx = new AnyEvent::TLS %$ctx;
		1565	}
1485	}	1566	}
1486		1567
1487	$self->{tls_ctx} = $ctx \|\| TLS_CTX ();	1568	$self->{tls_ctx} = $ctx \|\| TLS_CTX ();
1488	$self->{tls} = $ssl = $self->{tls_ctx}->_get_session ($ssl, $self, $self->{peername});	1569	$self->{tls} = $ssl = $self->{tls_ctx}->_get_session ($ssl, $self, $self->{peername});
1489		1570
…		…
1507	$self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());	1588	$self->{_rbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1508	$self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());	1589	$self->{_wbio} = Net::SSLeay::BIO_new (Net::SSLeay::BIO_s_mem ());
1509		1590
1510	Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});	1591	Net::SSLeay::set_bio ($ssl, $self->{_rbio}, $self->{_wbio});
1511		1592
		1593	$self->{_on_starttls} = sub { $_[0]{on_starttls}(@_) }
		1594	if $self->{on_starttls};
		1595
1512	&_dotls; # need to trigger the initial handshake	1596	&_dotls; # need to trigger the initial handshake
1513	$self->start_read; # make sure we actually do read	1597	$self->start_read; # make sure we actually do read
1514	}	1598	}
1515		1599
1516	=item $handle->stoptls	1600	=item $handle->stoptls
…		…
1528	if ($self->{tls}) {	1612	if ($self->{tls}) {
1529	Net::SSLeay::shutdown ($self->{tls});	1613	Net::SSLeay::shutdown ($self->{tls});
1530		1614
1531	&_dotls;	1615	&_dotls;
1532		1616
1533	# we don't give a shit. no, we do, but we can't. no...	1617	# # we don't give a shit. no, we do, but we can't. no...#d#
1534	# we, we... have to use openssl :/	1618	# # we, we... have to use openssl :/#d#
1535	&_freetls;	1619	# &_freetls;#d#
1536	}	1620	}
1537	}	1621	}
1538		1622
1539	sub _freetls {	1623	sub _freetls {
1540	my ($self) = @_;	1624	my ($self) = @_;
1541		1625
1542	return unless $self->{tls};	1626	return unless $self->{tls};
1543		1627
1544	$self->{tls_ctx}->_put_session (delete $self->{tls});	1628	$self->{tls_ctx}->_put_session (delete $self->{tls});
1545		1629
1546	delete @$self{qw(_rbio _wbio _tls_wbuf)};	1630	delete @$self{qw(_rbio _wbio _tls_wbuf _on_starttls)};
1547	}	1631	}
1548		1632
1549	sub DESTROY {	1633	sub DESTROY {
1550	my ($self) = @_;	1634	my ($self) = @_;
1551		1635
…		…
1575	}	1659	}
1576		1660
1577	=item $handle->destroy	1661	=item $handle->destroy
1578		1662
1579	Shuts down the handle object as much as possible - this call ensures that	1663	Shuts down the handle object as much as possible - this call ensures that
1580	no further callbacks will be invoked and resources will be freed as much	1664	no further callbacks will be invoked and as many resources as possible
1581	as possible. You must not call any methods on the object afterwards.	1665	will be freed. You must not call any methods on the object afterwards.
1582		1666
1583	Normally, you can just "forget" any references to an AnyEvent::Handle	1667	Normally, you can just "forget" any references to an AnyEvent::Handle
1584	object and it will simply shut down. This works in fatal error and EOF	1668	object and it will simply shut down. This works in fatal error and EOF
1585	callbacks, as well as code outside. It does I<NOT> work in a read or write	1669	callbacks, as well as code outside. It does I<NOT> work in a read or write
1586	callback, so when you want to destroy the AnyEvent::Handle object from	1670	callback, so when you want to destroy the AnyEvent::Handle object from
1587	within such an callback. You I<MUST> call C<< ->destroy >> explicitly in	1671	within such an callback. You I<MUST> call C<< ->destroy >> explicitly in
1588	that case.	1672	that case.
1589		1673
		1674	Destroying the handle object in this way has the advantage that callbacks
		1675	will be removed as well, so if those are the only reference holders (as
		1676	is common), then one doesn't need to do anything special to break any
		1677	reference cycles.
		1678
1590	The handle might still linger in the background and write out remaining	1679	The handle might still linger in the background and write out remaining
1591	data, as specified by the C<linger> option, however.	1680	data, as specified by the C<linger> option, however.
1592		1681
1593	=cut	1682	=cut
1594		1683
…		…
1661		1750
1662	$handle->on_read (sub { });	1751	$handle->on_read (sub { });
1663	$handle->on_eof (undef);	1752	$handle->on_eof (undef);
1664	$handle->on_error (sub {	1753	$handle->on_error (sub {
1665	my $data = delete $_[0]{rbuf};	1754	my $data = delete $_[0]{rbuf};
1666	undef $handle;
1667	});	1755	});
1668		1756
1669	The reason to use C<on_error> is that TCP connections, due to latencies	1757	The reason to use C<on_error> is that TCP connections, due to latencies
1670	and packets loss, might get closed quite violently with an error, when in	1758	and packets loss, might get closed quite violently with an error, when in
1671	fact, all data has been received.	1759	fact, all data has been received.
…		…
1687	$handle->on_drain (sub {	1775	$handle->on_drain (sub {
1688	warn "all data submitted to the kernel\n";	1776	warn "all data submitted to the kernel\n";
1689	undef $handle;	1777	undef $handle;
1690	});	1778	});
1691		1779
		1780	If you just want to queue some data and then signal EOF to the other side,
		1781	consider using C<< ->push_shutdown >> instead.
		1782
		1783	=item I want to contact a TLS/SSL server, I don't care about security.
		1784
		1785	If your TLS server is a pure TLS server (e.g. HTTPS) that only speaks TLS,
		1786	simply connect to it and then create the AnyEvent::Handle with the C<tls>
		1787	parameter:
		1788
		1789	tcp_connect $host, $port, sub {
		1790	my ($fh) = @_;
		1791
		1792	my $handle = new AnyEvent::Handle
		1793	fh => $fh,
		1794	tls => "connect",
		1795	on_error => sub { ... };
		1796
		1797	$handle->push_write (...);
		1798	};
		1799
		1800	=item I want to contact a TLS/SSL server, I do care about security.
		1801
		1802	Then you should additionally enable certificate verification, including
		1803	peername verification, if the protocol you use supports it (see
		1804	L<AnyEvent::TLS>, C<verify_peername>).
		1805
		1806	E.g. for HTTPS:
		1807
		1808	tcp_connect $host, $port, sub {
		1809	my ($fh) = @_;
		1810
		1811	my $handle = new AnyEvent::Handle
		1812	fh => $fh,
		1813	peername => $host,
		1814	tls => "connect",
		1815	tls_ctx => { verify => 1, verify_peername => "https" },
		1816	...
		1817
		1818	Note that you must specify the hostname you connected to (or whatever
		1819	"peername" the protocol needs) as the C<peername> argument, otherwise no
		1820	peername verification will be done.
		1821
		1822	The above will use the system-dependent default set of trusted CA
		1823	certificates. If you want to check against a specific CA, add the
		1824	C<ca_file> (or C<ca_cert>) arguments to C<tls_ctx>:
		1825
		1826	tls_ctx => {
		1827	verify => 1,
		1828	verify_peername => "https",
		1829	ca_file => "my-ca-cert.pem",
		1830	},
		1831
		1832	=item I want to create a TLS/SSL server, how do I do that?
		1833
		1834	Well, you first need to get a server certificate and key. You have
		1835	three options: a) ask a CA (buy one, use cacert.org etc.) b) create a
		1836	self-signed certificate (cheap. check the search engine of your choice,
		1837	there are many tutorials on the net) or c) make your own CA (tinyca2 is a
		1838	nice program for that purpose).
		1839
		1840	Then create a file with your private key (in PEM format, see
		1841	L<AnyEvent::TLS>), followed by the certificate (also in PEM format). The
		1842	file should then look like this:
		1843
		1844	-----BEGIN RSA PRIVATE KEY-----
		1845	...header data
		1846	... lots of base64'y-stuff
		1847	-----END RSA PRIVATE KEY-----
		1848
		1849	-----BEGIN CERTIFICATE-----
		1850	... lots of base64'y-stuff
		1851	-----END CERTIFICATE-----
		1852
		1853	The important bits are the "PRIVATE KEY" and "CERTIFICATE" parts. Then
		1854	specify this file as C<cert_file>:
		1855
		1856	tcp_server undef, $port, sub {
		1857	my ($fh) = @_;
		1858
		1859	my $handle = new AnyEvent::Handle
		1860	fh => $fh,
		1861	tls => "accept",
		1862	tls_ctx => { cert_file => "my-server-keycert.pem" },
		1863	...
		1864
		1865	When you have intermediate CA certificates that your clients might not
		1866	know about, just append them to the C<cert_file>.
		1867
1692	=back	1868	=back
1693		1869
1694		1870
1695	=head1 SUBCLASSING AnyEvent::Handle	1871	=head1 SUBCLASSING AnyEvent::Handle
1696		1872

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents): Revision 1.135 by root, Fri Jul 3 08:51:48 2009 UTC vs. Revision 1.149 by root, Thu Jul 16 03:48:33 2009 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.135 by root, Fri Jul 3 08:51:48 2009 UTC vs.
Revision 1.149 by root, Thu Jul 16 03:48:33 2009 UTC