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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.226 by root, Mon Jul 6 23:32:49 2009 UTC vs.
Revision 1.238 by root, Thu Jul 16 03:48:33 2009 UTC

…		…
176	=head2 I/O WATCHERS	176	=head2 I/O WATCHERS
177		177
178	You can create an I/O watcher by calling the C<< AnyEvent->io >> method	178	You can create an I/O watcher by calling the C<< AnyEvent->io >> method
179	with the following mandatory key-value pairs as arguments:	179	with the following mandatory key-value pairs as arguments:
180		180
181	C<fh> is the Perl I<file handle> (I<not> file descriptor) to watch	181	C<fh> is the Perl I<file handle> (or a naked file descriptor) to watch
182	for events (AnyEvent might or might not keep a reference to this file	182	for events (AnyEvent might or might not keep a reference to this file
183	handle). Note that only file handles pointing to things for which	183	handle). Note that only file handles pointing to things for which
184	non-blocking operation makes sense are allowed. This includes sockets,	184	non-blocking operation makes sense are allowed. This includes sockets,
185	most character devices, pipes, fifos and so on, but not for example files	185	most character devices, pipes, fifos and so on, but not for example files
186	or block devices.	186	or block devices.
…		…
740	variable itself. Calling C<recv> inside the callback or at any later time	740	variable itself. Calling C<recv> inside the callback or at any later time
741	is guaranteed not to block.	741	is guaranteed not to block.
742		742
743	=back	743	=back
744		744
		745	=head1 SUPPORTED EVENT LOOPS/BACKENDS
		746
		747	The available backend classes are (every class has its own manpage):
		748
		749	=over 4
		750
		751	=item Backends that are autoprobed when no other event loop can be found.
		752
		753	EV is the preferred backend when no other event loop seems to be in
		754	use. If EV is not installed, then AnyEvent will try Event, and, failing
		755	that, will fall back to its own pure-perl implementation, which is
		756	available everywhere as it comes with AnyEvent itself.
		757
		758	AnyEvent::Impl::EV based on EV (interface to libev, best choice).
		759	AnyEvent::Impl::Event based on Event, very stable, few glitches.
		760	AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
		761
		762	=item Backends that are transparently being picked up when they are used.
		763
		764	These will be used when they are currently loaded when the first watcher
		765	is created, in which case it is assumed that the application is using
		766	them. This means that AnyEvent will automatically pick the right backend
		767	when the main program loads an event module before anything starts to
		768	create watchers. Nothing special needs to be done by the main program.
		769
		770	AnyEvent::Impl::Glib based on Glib, slow but very stable.
		771	AnyEvent::Impl::Tk based on Tk, very broken.
		772	AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
		773	AnyEvent::Impl::POE based on POE, very slow, some limitations.
		774
		775	=item Backends with special needs.
		776
		777	Qt requires the Qt::Application to be instantiated first, but will
		778	otherwise be picked up automatically. As long as the main program
		779	instantiates the application before any AnyEvent watchers are created,
		780	everything should just work.
		781
		782	AnyEvent::Impl::Qt based on Qt.
		783
		784	Support for IO::Async can only be partial, as it is too broken and
		785	architecturally limited to even support the AnyEvent API. It also
		786	is the only event loop that needs the loop to be set explicitly, so
		787	it can only be used by a main program knowing about AnyEvent. See
		788	L<AnyEvent::Impl::Async> for the gory details.
		789
		790	AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
		791
		792	=item Event loops that are indirectly supported via other backends.
		793
		794	Some event loops can be supported via other modules:
		795
		796	There is no direct support for WxWidgets (L<Wx>) or L<Prima>.
		797
		798	B<WxWidgets> has no support for watching file handles. However, you can
		799	use WxWidgets through the POE adaptor, as POE has a Wx backend that simply
		800	polls 20 times per second, which was considered to be too horrible to even
		801	consider for AnyEvent.
		802
		803	B<Prima> is not supported as nobody seems to be using it, but it has a POE
		804	backend, so it can be supported through POE.
		805
		806	AnyEvent knows about both L<Prima> and L<Wx>, however, and will try to
		807	load L<POE> when detecting them, in the hope that POE will pick them up,
		808	in which case everything will be automatic.
		809
		810	=back
		811
745	=head1 GLOBAL VARIABLES AND FUNCTIONS	812	=head1 GLOBAL VARIABLES AND FUNCTIONS
746		813
		814	These are not normally required to use AnyEvent, but can be useful to
		815	write AnyEvent extension modules.
		816
747	=over 4	817	=over 4
748		818
749	=item $AnyEvent::MODEL	819	=item $AnyEvent::MODEL
750		820
751	Contains C<undef> until the first watcher is being created. Then it	821	Contains C<undef> until the first watcher is being created, before the
		822	backend has been autodetected.
		823
752	contains the event model that is being used, which is the name of the	824	Afterwards it contains the event model that is being used, which is the
753	Perl class implementing the model. This class is usually one of the	825	name of the Perl class implementing the model. This class is usually one
754	C<AnyEvent::Impl:xxx> modules, but can be any other class in the case	826	of the C<AnyEvent::Impl:xxx> modules, but can be any other class in the
755	AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).	827	case AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode> it
756		828	will be C<urxvt::anyevent>).
757	The known classes so far are:
758
759	AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
760	AnyEvent::Impl::Event based on Event, second best choice.
761	AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
762	AnyEvent::Impl::Glib based on Glib, third-best choice.
763	AnyEvent::Impl::Tk based on Tk, very bad choice.
764	AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
765	AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
766	AnyEvent::Impl::POE based on POE, not generic enough for full support.
767
768	# warning, support for IO::Async is only partial, as it is too broken
769	# and limited toe ven support the AnyEvent API. See AnyEvent::Impl::Async.
770	AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed (see its docs).
771
772	There is no support for WxWidgets, as WxWidgets has no support for
773	watching file handles. However, you can use WxWidgets through the
774	POE Adaptor, as POE has a Wx backend that simply polls 20 times per
775	second, which was considered to be too horrible to even consider for
776	AnyEvent. Likewise, other POE backends can be used by AnyEvent by using
777	it's adaptor.
778
779	AnyEvent knows about L<Prima> and L<Wx> and will try to use L<POE> when
780	autodetecting them.
781		829
782	=item AnyEvent::detect	830	=item AnyEvent::detect
783		831
784	Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model	832	Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
785	if necessary. You should only call this function right before you would	833	if necessary. You should only call this function right before you would
786	have created an AnyEvent watcher anyway, that is, as late as possible at	834	have created an AnyEvent watcher anyway, that is, as late as possible at
787	runtime.	835	runtime, and not e.g. while initialising of your module.
		836
		837	If you need to do some initialisation before AnyEvent watchers are
		838	created, use C<post_detect>.
788		839
789	=item $guard = AnyEvent::post_detect { BLOCK }	840	=item $guard = AnyEvent::post_detect { BLOCK }
790		841
791	Arranges for the code block to be executed as soon as the event model is	842	Arranges for the code block to be executed as soon as the event model is
792	autodetected (or immediately if this has already happened).	843	autodetected (or immediately if this has already happened).
		844
		845	The block will be executed I<after> the actual backend has been detected
		846	(C<$AnyEvent::MODEL> is set), but I<before> any watchers have been
		847	created, so it is possible to e.g. patch C<@AnyEvent::ISA> or do
		848	other initialisations - see the sources of L<AnyEvent::Strict> or
		849	L<AnyEvent::AIO> to see how this is used.
		850
		851	The most common usage is to create some global watchers, without forcing
		852	event module detection too early, for example, L<AnyEvent::AIO> creates
		853	and installs the global L<IO::AIO> watcher in a C<post_detect> block to
		854	avoid autodetecting the event module at load time.
793		855
794	If called in scalar or list context, then it creates and returns an object	856	If called in scalar or list context, then it creates and returns an object
795	that automatically removes the callback again when it is destroyed. See	857	that automatically removes the callback again when it is destroyed. See
796	L<Coro::BDB> for a case where this is useful.	858	L<Coro::BDB> for a case where this is useful.
797		859
…		…
800	If there are any code references in this array (you can C<push> to it	862	If there are any code references in this array (you can C<push> to it
801	before or after loading AnyEvent), then they will called directly after	863	before or after loading AnyEvent), then they will called directly after
802	the event loop has been chosen.	864	the event loop has been chosen.
803		865
804	You should check C<$AnyEvent::MODEL> before adding to this array, though:	866	You should check C<$AnyEvent::MODEL> before adding to this array, though:
805	if it contains a true value then the event loop has already been detected,	867	if it is defined then the event loop has already been detected, and the
806	and the array will be ignored.	868	array will be ignored.
807		869
808	Best use C<AnyEvent::post_detect { BLOCK }> instead.	870	Best use C<AnyEvent::post_detect { BLOCK }> when your application allows
		871	it,as it takes care of these details.
		872
		873	This variable is mainly useful for modules that can do something useful
		874	when AnyEvent is used and thus want to know when it is initialised, but do
		875	not need to even load it by default. This array provides the means to hook
		876	into AnyEvent passively, without loading it.
809		877
810	=back	878	=back
811		879
812	=head1 WHAT TO DO IN A MODULE	880	=head1 WHAT TO DO IN A MODULE
813		881
…		…
868		936
869		937
870	=head1 OTHER MODULES	938	=head1 OTHER MODULES
871		939
872	The following is a non-exhaustive list of additional modules that use	940	The following is a non-exhaustive list of additional modules that use
873	AnyEvent and can therefore be mixed easily with other AnyEvent modules	941	AnyEvent as a client and can therefore be mixed easily with other AnyEvent
874	in the same program. Some of the modules come with AnyEvent, some are	942	modules and other event loops in the same program. Some of the modules
875	available via CPAN.	943	come with AnyEvent, most are available via CPAN.
876		944
877	=over 4	945	=over 4
878		946
879	=item L<AnyEvent::Util>	947	=item L<AnyEvent::Util>
880		948
…		…
889		957
890	=item L<AnyEvent::Handle>	958	=item L<AnyEvent::Handle>
891		959
892	Provide read and write buffers, manages watchers for reads and writes,	960	Provide read and write buffers, manages watchers for reads and writes,
893	supports raw and formatted I/O, I/O queued and fully transparent and	961	supports raw and formatted I/O, I/O queued and fully transparent and
894	non-blocking SSL/TLS.	962	non-blocking SSL/TLS (via L<AnyEvent::TLS>.
895		963
896	=item L<AnyEvent::DNS>	964	=item L<AnyEvent::DNS>
897		965
898	Provides rich asynchronous DNS resolver capabilities.	966	Provides rich asynchronous DNS resolver capabilities.
899		967
…		…
927		995
928	=item L<AnyEvent::GPSD>	996	=item L<AnyEvent::GPSD>
929		997
930	A non-blocking interface to gpsd, a daemon delivering GPS information.	998	A non-blocking interface to gpsd, a daemon delivering GPS information.
931		999
		1000	=item L<AnyEvent::IRC>
		1001
		1002	AnyEvent based IRC client module family (replacing the older Net::IRC3).
		1003
		1004	=item L<AnyEvent::XMPP>
		1005
		1006	AnyEvent based XMPP (Jabber protocol) module family (replacing the older
		1007	Net::XMPP2>.
		1008
932	=item L<AnyEvent::IGS>	1009	=item L<AnyEvent::IGS>
933		1010
934	A non-blocking interface to the Internet Go Server protocol (used by	1011	A non-blocking interface to the Internet Go Server protocol (used by
935	L<App::IGS>).	1012	L<App::IGS>).
936		1013
937	=item L<AnyEvent::IRC>
938
939	AnyEvent based IRC client module family (replacing the older Net::IRC3).
940
941	=item L<Net::XMPP2>
942
943	AnyEvent based XMPP (Jabber protocol) module family.
944
945	=item L<Net::FCP>	1014	=item L<Net::FCP>
946		1015
947	AnyEvent-based implementation of the Freenet Client Protocol, birthplace	1016	AnyEvent-based implementation of the Freenet Client Protocol, birthplace
948	of AnyEvent.	1017	of AnyEvent.
949		1018
…		…
953		1022
954	=item L<Coro>	1023	=item L<Coro>
955		1024
956	Has special support for AnyEvent via L<Coro::AnyEvent>.	1025	Has special support for AnyEvent via L<Coro::AnyEvent>.
957		1026
958	=item L<IO::Lambda>
959
960	The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
961
962	=back	1027	=back
963		1028
964	=cut	1029	=cut
965		1030
966	package AnyEvent;	1031	package AnyEvent;
…		…
968	no warnings;	1033	no warnings;
969	use strict qw(vars subs);	1034	use strict qw(vars subs);
970		1035
971	use Carp;	1036	use Carp;
972		1037
973	our $VERSION = 4.8;	1038	our $VERSION = 4.82;
974	our $MODEL;	1039	our $MODEL;
975		1040
976	our $AUTOLOAD;	1041	our $AUTOLOAD;
977	our @ISA;	1042	our @ISA;
978		1043
…		…
1004	[Event:: => AnyEvent::Impl::Event::],	1069	[Event:: => AnyEvent::Impl::Event::],
1005	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],	1070	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
1006	# everything below here will not be autoprobed	1071	# everything below here will not be autoprobed
1007	# as the pureperl backend should work everywhere	1072	# as the pureperl backend should work everywhere
1008	# and is usually faster	1073	# and is usually faster
1009	[Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1010	[Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers	1074	[Glib:: => AnyEvent::Impl::Glib::], # becomes extremely slow with many watchers
1011	[Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy	1075	[Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy
		1076	[Tk:: => AnyEvent::Impl::Tk::], # crashes with many handles
1012	[Qt:: => AnyEvent::Impl::Qt::], # requires special main program	1077	[Qt:: => AnyEvent::Impl::Qt::], # requires special main program
1013	[POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza	1078	[POE::Kernel:: => AnyEvent::Impl::POE::], # lasciate ogni speranza
1014	[Wx:: => AnyEvent::Impl::POE::],	1079	[Wx:: => AnyEvent::Impl::POE::],
1015	[Prima:: => AnyEvent::Impl::POE::],	1080	[Prima:: => AnyEvent::Impl::POE::],
1016	# IO::Async is just too broken - we would need workaorunds for its	1081	# IO::Async is just too broken - we would need workarounds for its
1017	# byzantine signal and broken child handling, among others.	1082	# byzantine signal and broken child handling, among others.
1018	# IO::Async is rather hard to detect, as it doesn't have any	1083	# IO::Async is rather hard to detect, as it doesn't have any
1019	# obvious default class.	1084	# obvious default class.
1020	# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program	1085	# [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program
1021	# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program	1086	# [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program
…		…
1054		1119
1055	if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {	1120	if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z]+)$/) {
1056	my $model = "AnyEvent::Impl::$1";	1121	my $model = "AnyEvent::Impl::$1";
1057	if (eval "require $model") {	1122	if (eval "require $model") {
1058	$MODEL = $model;	1123	$MODEL = $model;
1059	warn "AnyEvent: loaded model '$model' (forced by \$PERL_ANYEVENT_MODEL), using it.\n" if $verbose > 1;	1124	warn "AnyEvent: loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.\n" if $verbose > 1;
1060	} else {	1125	} else {
1061	warn "AnyEvent: unable to load model '$model' (from \$PERL_ANYEVENT_MODEL):\n$@" if $verbose;	1126	warn "AnyEvent: unable to load model '$model' (from \$ENV{PERL_ANYEVENT_MODEL}):\n$@" if $verbose;
1062	}	1127	}
1063	}	1128	}
1064		1129
1065	# check for already loaded models	1130	# check for already loaded models
1066	unless ($MODEL) {	1131	unless ($MODEL) {
…		…
1123	# allow only one watcher per fd, so we dup it to get a different one).	1188	# allow only one watcher per fd, so we dup it to get a different one).
1124	sub _dupfh($$;$$) {	1189	sub _dupfh($$;$$) {
1125	my ($poll, $fh, $r, $w) = @_;	1190	my ($poll, $fh, $r, $w) = @_;
1126		1191
1127	# cygwin requires the fh mode to be matching, unix doesn't	1192	# cygwin requires the fh mode to be matching, unix doesn't
1128	my ($rw, $mode) = $poll eq "r" ? ($r, "<")	1193	my ($rw, $mode) = $poll eq "r" ? ($r, "<") : ($w, ">");
1129	: $poll eq "w" ? ($w, ">")
1130	: Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'";
1131		1194
1132	open my $fh2, "$mode&" . fileno $fh	1195	open my $fh2, "$mode&", $fh
1133	or die "cannot dup() filehandle: $!,";	1196	or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";
1134		1197
1135	# we assume CLOEXEC is already set by perl in all important cases	1198	# we assume CLOEXEC is already set by perl in all important cases
1136		1199
1137	($fh2, $rw)	1200	($fh2, $rw)
1138	}	1201	}
…		…
1482	=item C<PERL_ANYEVENT_RESOLV_CONF>	1545	=item C<PERL_ANYEVENT_RESOLV_CONF>
1483		1546
1484	The file to use instead of F</etc/resolv.conf> (or OS-specific	1547	The file to use instead of F</etc/resolv.conf> (or OS-specific
1485	configuration) in the default resolver. When set to the empty string, no	1548	configuration) in the default resolver. When set to the empty string, no
1486	default config will be used.	1549	default config will be used.
		1550
		1551	=item C<PERL_ANYEVENT_CA_FILE>, C<PERL_ANYEVENT_CA_PATH>.
		1552
		1553	When neither C<ca_file> nor C<ca_path> was specified during
		1554	L<AnyEvent::TLS> context creation, and either of these environment
		1555	variables exist, they will be used to specify CA certificate locations
		1556	instead of a system-dependent default.
1487		1557
1488	=back	1558	=back
1489		1559
1490	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE	1560	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1491		1561
…		…
2030		2100
2031	A handler for C<SIGCHLD> is installed by AnyEvent's child watcher	2101	A handler for C<SIGCHLD> is installed by AnyEvent's child watcher
2032	emulation for event loops that do not support them natively. Also, some	2102	emulation for event loops that do not support them natively. Also, some
2033	event loops install a similar handler.	2103	event loops install a similar handler.
2034		2104
2035	If, when AnyEvent is loaded, SIGCHLD is set to IGNORE, then AnyEvent will	2105	Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE, then
2036	reset it to default, to avoid losing child exit statuses.	2106	AnyEvent will reset it to default, to avoid losing child exit statuses.
2037		2107
2038	=item SIGPIPE	2108	=item SIGPIPE
2039		2109
2040	A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef>	2110	A no-op handler is installed for C<SIGPIPE> when C<$SIG{PIPE}> is C<undef>
2041	when AnyEvent gets loaded.	2111	when AnyEvent gets loaded.
…		…
2114	L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.	2184	L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
2115		2185
2116	Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,	2186	Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2117	L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,	2187	L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2118	L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,	2188	L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2119	L<AnyEvent::Impl::POE>.	2189	L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>.
2120		2190
2121	Non-blocking file handles, sockets, TCP clients and	2191	Non-blocking file handles, sockets, TCP clients and
2122	servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>.	2192	servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2123		2193
2124	Asynchronous DNS: L<AnyEvent::DNS>.	2194	Asynchronous DNS: L<AnyEvent::DNS>.
2125		2195
2126	Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>,	2196	Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>,
		2197	L<Coro::Event>,
2127		2198
2128	Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.	2199	Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::XMPP>,
		2200	L<AnyEvent::HTTP>.
2129		2201
2130		2202
2131	=head1 AUTHOR	2203	=head1 AUTHOR
2132		2204
2133	Marc Lehmann <schmorp@schmorp.de>	2205	Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.226 by root, Mon Jul 6 23:32:49 2009 UTC vs. Revision 1.238 by root, Thu Jul 16 03:48:33 2009 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.226 by root, Mon Jul 6 23:32:49 2009 UTC vs.
Revision 1.238 by root, Thu Jul 16 03:48:33 2009 UTC