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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.143 by root, Wed May 28 23:57:38 2008 UTC vs.
Revision 1.164 by root, Tue Jul 8 19:50:25 2008 UTC

…		…
1	=head1 => NAME	1	=head1 NAME
2		2
3	AnyEvent - provide framework for multiple event loops	3	AnyEvent - provide framework for multiple event loops
4		4
5	EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops	5	EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event loops
6		6
17	});	17	});
18		18
19	my $w = AnyEvent->condvar; # stores whether a condition was flagged	19	my $w = AnyEvent->condvar; # stores whether a condition was flagged
20	$w->send; # wake up current and all future recv's	20	$w->send; # wake up current and all future recv's
21	$w->recv; # enters "main loop" till $condvar gets ->send	21	$w->recv; # enters "main loop" till $condvar gets ->send
		22
		23	=head1 INTRODUCTION/TUTORIAL
		24
		25	This manpage is mainly a reference manual. If you are interested
		26	in a tutorial or some gentle introduction, have a look at the
		27	L<AnyEvent::Intro> manpage.
22		28
23	=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)	29	=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
24		30
25	Glib, POE, IO::Async, Event... CPAN offers event models by the dozen	31	Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
26	nowadays. So what is different about AnyEvent?	32	nowadays. So what is different about AnyEvent?
…		…
132	Many watchers either are used with "recursion" (repeating timers for	138	Many watchers either are used with "recursion" (repeating timers for
133	example), or need to refer to their watcher object in other ways.	139	example), or need to refer to their watcher object in other ways.
134		140
135	An any way to achieve that is this pattern:	141	An any way to achieve that is this pattern:
136		142
137	my $w; $w = AnyEvent->type (arg => value ..., cb => sub {	143	my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
138	# you can use $w here, for example to undef it	144	# you can use $w here, for example to undef it
139	undef $w;	145	undef $w;
140	});	146	});
141		147
142	Note that C<my $w; $w => combination. This is necessary because in Perl,	148	Note that C<my $w; $w => combination. This is necessary because in Perl,
143	my variables are only visible after the statement in which they are	149	my variables are only visible after the statement in which they are
144	declared.	150	declared.
145		151
…		…
164		170
165	Some event loops issue spurious readyness notifications, so you should	171	Some event loops issue spurious readyness notifications, so you should
166	always use non-blocking calls when reading/writing from/to your file	172	always use non-blocking calls when reading/writing from/to your file
167	handles.	173	handles.
168		174
169	Example:
170
171	# wait for readability of STDIN, then read a line and disable the watcher	175	Example: wait for readability of STDIN, then read a line and disable the
		176	watcher.
		177
172	my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {	178	my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
173	chomp (my $input = <STDIN>);	179	chomp (my $input = <STDIN>);
174	warn "read: $input\n";	180	warn "read: $input\n";
175	undef $w;	181	undef $w;
176	});	182	});
…		…
186		192
187	Although the callback might get passed parameters, their value and	193	Although the callback might get passed parameters, their value and
188	presence is undefined and you cannot rely on them. Portable AnyEvent	194	presence is undefined and you cannot rely on them. Portable AnyEvent
189	callbacks cannot use arguments passed to time watcher callbacks.	195	callbacks cannot use arguments passed to time watcher callbacks.
190		196
191	The timer callback will be invoked at most once: if you want a repeating	197	The callback will normally be invoked once only. If you specify another
192	timer you have to create a new watcher (this is a limitation by both Tk	198	parameter, C<interval>, as a positive number, then the callback will be
193	and Glib).	199	invoked regularly at that interval (in fractional seconds) after the first
		200	invocation.
194		201
195	Example:	202	The callback will be rescheduled before invoking the callback, but no
		203	attempt is done to avoid timer drift in most backends, so the interval is
		204	only approximate.
196		205
197	# fire an event after 7.7 seconds	206	Example: fire an event after 7.7 seconds.
		207
198	my $w = AnyEvent->timer (after => 7.7, cb => sub {	208	my $w = AnyEvent->timer (after => 7.7, cb => sub {
199	warn "timeout\n";	209	warn "timeout\n";
200	});	210	});
201		211
202	# to cancel the timer:	212	# to cancel the timer:
203	undef $w;	213	undef $w;
204		214
205	Example 2:
206
207	# fire an event after 0.5 seconds, then roughly every second	215	Example 2: fire an event after 0.5 seconds, then roughly every second.
208	my $w;
209		216
210	my $cb = sub {
211	# cancel the old timer while creating a new one
212	$w = AnyEvent->timer (after => 1, cb => $cb);	217	my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
		218	warn "timeout\n";
213	};	219	};
214
215	# start the "loop" by creating the first watcher
216	$w = AnyEvent->timer (after => 0.5, cb => $cb);
217		220
218	=head3 TIMING ISSUES	221	=head3 TIMING ISSUES
219		222
220	There are two ways to handle timers: based on real time (relative, "fire	223	There are two ways to handle timers: based on real time (relative, "fire
221	in 10 seconds") and based on wallclock time (absolute, "fire at 12	224	in 10 seconds") and based on wallclock time (absolute, "fire at 12
…		…
243		246
244	This returns the "current wallclock time" as a fractional number of	247	This returns the "current wallclock time" as a fractional number of
245	seconds since the Epoch (the same thing as C<time> or C<Time::HiRes::time>	248	seconds since the Epoch (the same thing as C<time> or C<Time::HiRes::time>
246	return, and the result is guaranteed to be compatible with those).	249	return, and the result is guaranteed to be compatible with those).
247		250
248	It progresses independently of any event loop processing.	251	It progresses independently of any event loop processing, i.e. each call
249		252	will check the system clock, which usually gets updated frequently.
250	In almost all cases (in all cases if you don't care), this is the function
251	to call when you want to know the current time.
252		253
253	=item AnyEvent->now	254	=item AnyEvent->now
254		255
255	This also returns the "current wallclock time", but unlike C<time>, above,	256	This also returns the "current wallclock time", but unlike C<time>, above,
256	this value might change only once per event loop iteration, depending on	257	this value might change only once per event loop iteration, depending on
257	the event loop (most return the same time as C<time>, above). This is the	258	the event loop (most return the same time as C<time>, above). This is the
258	time that AnyEvent timers get scheduled against.	259	time that AnyEvent's timers get scheduled against.
		260
		261	I<In almost all cases (in all cases if you don't care), this is the
		262	function to call when you want to know the current time.>
		263
		264	This function is also often faster then C<< AnyEvent->time >>, and
		265	thus the preferred method if you want some timestamp (for example,
		266	L<AnyEvent::Handle> uses this to update it's activity timeouts).
		267
		268	The rest of this section is only of relevance if you try to be very exact
		269	with your timing, you can skip it without bad conscience.
259		270
260	For a practical example of when these times differ, consider L<Event::Lib>	271	For a practical example of when these times differ, consider L<Event::Lib>
261	and L<EV> and the following set-up:	272	and L<EV> and the following set-up:
262		273
263	The event loop is running and has just invoked one of your callback at	274	The event loop is running and has just invoked one of your callback at
…		…
268		279
269	With L<Event::Lib>, C<< AnyEvent->time >> and C<< AnyEvent->now >> will	280	With L<Event::Lib>, C<< AnyEvent->time >> and C<< AnyEvent->now >> will
270	both return C<501>, because that is the current time, and the timer will	281	both return C<501>, because that is the current time, and the timer will
271	be scheduled to fire at time=504 (C<501> + C<3>).	282	be scheduled to fire at time=504 (C<501> + C<3>).
272		283
273	With L<EV>m C<< AnyEvent->time >> returns C<501> (as that is the current	284	With L<EV>, C<< AnyEvent->time >> returns C<501> (as that is the current
274	time), but C<< AnyEvent->now >> returns C<500>, as that is the time the	285	time), but C<< AnyEvent->now >> returns C<500>, as that is the time the
275	last event processing phase started. With L<EV>, your timer gets scheduled	286	last event processing phase started. With L<EV>, your timer gets scheduled
276	to run at time=503 (C<500> + C<3>).	287	to run at time=503 (C<500> + C<3>).
277		288
278	In one sense, L<Event::Lib> is more exact, as it uses the current time	289	In one sense, L<Event::Lib> is more exact, as it uses the current time
279	regardless of any delays introduced by event processing. However, most	290	regardless of any delays introduced by event processing. However, most
280	callbacks do not expect large delays in processing, so this causes a	291	callbacks do not expect large delays in processing, so this causes a
281	higher drift (and a lot more syscalls to get the current time).	292	higher drift (and a lot more system calls to get the current time).
282		293
283	In another sense, L<EV> is more exact, as your timer will be scheduled at	294	In another sense, L<EV> is more exact, as your timer will be scheduled at
284	the same time, regardless of how long event processing actually took.	295	the same time, regardless of how long event processing actually took.
285		296
286	In either case, if you care (and in most cases, you don't), then you	297	In either case, if you care (and in most cases, you don't), then you
…		…
338	AnyEvent program, you I<have> to create at least one watcher before you	349	AnyEvent program, you I<have> to create at least one watcher before you
339	C<fork> the child (alternatively, you can call C<AnyEvent::detect>).	350	C<fork> the child (alternatively, you can call C<AnyEvent::detect>).
340		351
341	Example: fork a process and wait for it	352	Example: fork a process and wait for it
342		353
343	my $done = AnyEvent->condvar;	354	my $done = AnyEvent->condvar;
344		355
345	my $pid = fork or exit 5;	356	my $pid = fork or exit 5;
346		357
347	my $w = AnyEvent->child (	358	my $w = AnyEvent->child (
348	pid => $pid,	359	pid => $pid,
349	cb => sub {	360	cb => sub {
350	my ($pid, $status) = @_;	361	my ($pid, $status) = @_;
351	warn "pid $pid exited with status $status";	362	warn "pid $pid exited with status $status";
352	$done->send;	363	$done->send;
353	},	364	},
354	);	365	);
355		366
356	# do something else, then wait for process exit	367	# do something else, then wait for process exit
357	$done->recv;	368	$done->recv;
358		369
359	=head2 CONDITION VARIABLES	370	=head2 CONDITION VARIABLES
360		371
361	If you are familiar with some event loops you will know that all of them	372	If you are familiar with some event loops you will know that all of them
362	require you to run some blocking "loop", "run" or similar function that	373	require you to run some blocking "loop", "run" or similar function that
…		…
583		594
584	This is a mutator function that returns the callback set and optionally	595	This is a mutator function that returns the callback set and optionally
585	replaces it before doing so.	596	replaces it before doing so.
586		597
587	The callback will be called when the condition becomes "true", i.e. when	598	The callback will be called when the condition becomes "true", i.e. when
588	C<send> or C<croak> are called. Calling C<recv> inside the callback	599	C<send> or C<croak> are called, with the only argument being the condition
589	or at any later time is guaranteed not to block.	600	variable itself. Calling C<recv> inside the callback or at any later time
		601	is guaranteed not to block.
590		602
591	=back	603	=back
592		604
593	=head1 GLOBAL VARIABLES AND FUNCTIONS	605	=head1 GLOBAL VARIABLES AND FUNCTIONS
594		606
…		…
723	=item L<AnyEvent::Util>	735	=item L<AnyEvent::Util>
724		736
725	Contains various utility functions that replace often-used but blocking	737	Contains various utility functions that replace often-used but blocking
726	functions such as C<inet_aton> by event-/callback-based versions.	738	functions such as C<inet_aton> by event-/callback-based versions.
727		739
728	=item L<AnyEvent::Handle>
729
730	Provide read and write buffers and manages watchers for reads and writes.
731
732	=item L<AnyEvent::Socket>	740	=item L<AnyEvent::Socket>
733		741
734	Provides various utility functions for (internet protocol) sockets,	742	Provides various utility functions for (internet protocol) sockets,
735	addresses and name resolution. Also functions to create non-blocking tcp	743	addresses and name resolution. Also functions to create non-blocking tcp
736	connections or tcp servers, with IPv6 and SRV record support and more.	744	connections or tcp servers, with IPv6 and SRV record support and more.
737		745
		746	=item L<AnyEvent::Handle>
		747
		748	Provide read and write buffers, manages watchers for reads and writes,
		749	supports raw and formatted I/O, I/O queued and fully transparent and
		750	non-blocking SSL/TLS.
		751
738	=item L<AnyEvent::DNS>	752	=item L<AnyEvent::DNS>
739		753
740	Provides rich asynchronous DNS resolver capabilities.	754	Provides rich asynchronous DNS resolver capabilities.
741		755
		756	=item L<AnyEvent::HTTP>
		757
		758	A simple-to-use HTTP library that is capable of making a lot of concurrent
		759	HTTP requests.
		760
742	=item L<AnyEvent::HTTPD>	761	=item L<AnyEvent::HTTPD>
743		762
744	Provides a simple web application server framework.	763	Provides a simple web application server framework.
745		764
746	=item L<AnyEvent::FastPing>	765	=item L<AnyEvent::FastPing>
747		766
748	The fastest ping in the west.	767	The fastest ping in the west.
		768
		769	=item L<AnyEvent::DBI>
		770
		771	Executes L<DBI> requests asynchronously in a proxy process.
		772
		773	=item L<AnyEvent::AIO>
		774
		775	Truly asynchronous I/O, should be in the toolbox of every event
		776	programmer. AnyEvent::AIO transparently fuses L<IO::AIO> and AnyEvent
		777	together.
		778
		779	=item L<AnyEvent::BDB>
		780
		781	Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently fuses
		782	L<BDB> and AnyEvent together.
		783
		784	=item L<AnyEvent::GPSD>
		785
		786	A non-blocking interface to gpsd, a daemon delivering GPS information.
		787
		788	=item L<AnyEvent::IGS>
		789
		790	A non-blocking interface to the Internet Go Server protocol (used by
		791	L<App::IGS>).
749		792
750	=item L<Net::IRC3>	793	=item L<Net::IRC3>
751		794
752	AnyEvent based IRC client module family.	795	AnyEvent based IRC client module family.
753		796
…		…
766		809
767	=item L<Coro>	810	=item L<Coro>
768		811
769	Has special support for AnyEvent via L<Coro::AnyEvent>.	812	Has special support for AnyEvent via L<Coro::AnyEvent>.
770		813
771	=item L<AnyEvent::AIO>, L<IO::AIO>
772
773	Truly asynchronous I/O, should be in the toolbox of every event
774	programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
775	together.
776
777	=item L<AnyEvent::BDB>, L<BDB>
778
779	Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently fuses
780	IO::AIO and AnyEvent together.
781
782	=item L<IO::Lambda>	814	=item L<IO::Lambda>
783		815
784	The lambda approach to I/O - don't ask, look there. Can use AnyEvent.	816	The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
785		817
786	=back	818	=back
…		…
792	no warnings;	824	no warnings;
793	use strict;	825	use strict;
794		826
795	use Carp;	827	use Carp;
796		828
797	our $VERSION = '4.05';	829	our $VERSION = 4.2;
798	our $MODEL;	830	our $MODEL;
799		831
800	our $AUTOLOAD;	832	our $AUTOLOAD;
801	our @ISA;	833	our @ISA;
802		834
…		…
964	sub AnyEvent::Base::Signal::DESTROY {	996	sub AnyEvent::Base::Signal::DESTROY {
965	my ($signal, $cb) = @{$_[0]};	997	my ($signal, $cb) = @{$_[0]};
966		998
967	delete $SIG_CB{$signal}{$cb};	999	delete $SIG_CB{$signal}{$cb};
968		1000
969	$SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };	1001	delete $SIG{$signal} unless keys %{ $SIG_CB{$signal} };
970	}	1002	}
971		1003
972	# default implementation for ->child	1004	# default implementation for ->child
973		1005
974	our %PID_CB;	1006	our %PID_CB;
…		…
1158	This functionality might change in future versions.	1190	This functionality might change in future versions.
1159		1191
1160	For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you	1192	For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1161	could start your program like this:	1193	could start your program like this:
1162		1194
1163	PERL_ANYEVENT_MODEL=Perl perl ...	1195	PERL_ANYEVENT_MODEL=Perl perl ...
1164		1196
1165	=item C<PERL_ANYEVENT_PROTOCOLS>	1197	=item C<PERL_ANYEVENT_PROTOCOLS>
1166		1198
1167	Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences	1199	Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
1168	for IPv4 or IPv6. The default is unspecified (and might change, or be the result	1200	for IPv4 or IPv6. The default is unspecified (and might change, or be the result
…		…
1643	specified in the variable.	1675	specified in the variable.
1644		1676
1645	You can make AnyEvent completely ignore this variable by deleting it	1677	You can make AnyEvent completely ignore this variable by deleting it
1646	before the first watcher gets created, e.g. with a C<BEGIN> block:	1678	before the first watcher gets created, e.g. with a C<BEGIN> block:
1647		1679
1648	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }	1680	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1649		1681
1650	use AnyEvent;	1682	use AnyEvent;
1651		1683
1652	Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can	1684	Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1653	be used to probe what backend is used and gain other information (which is	1685	be used to probe what backend is used and gain other information (which is
1654	probably even less useful to an attacker than PERL_ANYEVENT_MODEL).	1686	probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
		1687
		1688
		1689	=head1 BUGS
		1690
		1691	Perl 5.8 has numerous memleaks that sometimes hit this module and are hard
		1692	to work around. If you suffer from memleaks, first upgrade to Perl 5.10
		1693	and check wether the leaks still show up. (Perl 5.10.0 has other annoying
		1694	mamleaks, such as leaking on C<map> and C<grep> but it is usually not as
		1695	pronounced).
1655		1696
1656		1697
1657	=head1 SEE ALSO	1698	=head1 SEE ALSO
1658		1699
1659	Utility functions: L<AnyEvent::Util>.	1700	Utility functions: L<AnyEvent::Util>.
…		…
1676	Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.	1717	Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1677		1718
1678		1719
1679	=head1 AUTHOR	1720	=head1 AUTHOR
1680		1721
1681	Marc Lehmann <schmorp@schmorp.de>	1722	Marc Lehmann <schmorp@schmorp.de>
1682	http://home.schmorp.de/	1723	http://home.schmorp.de/
1683		1724
1684	=cut	1725	=cut
1685		1726
1686	1	1727	1
1687		1728

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.143 by root, Wed May 28 23:57:38 2008 UTC vs. Revision 1.164 by root, Tue Jul 8 19:50:25 2008 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.143 by root, Wed May 28 23:57:38 2008 UTC vs.
Revision 1.164 by root, Tue Jul 8 19:50:25 2008 UTC