[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.160 by root, Sun Jun 22 12:17:47 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
…		…
243		249
244	This returns the "current wallclock time" as a fractional number of	250	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>	251	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).	252	return, and the result is guaranteed to be compatible with those).
247		253
248	It progresses independently of any event loop processing.	254	It progresses independently of any event loop processing, i.e. each call
249		255	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		256
253	=item AnyEvent->now	257	=item AnyEvent->now
254		258
255	This also returns the "current wallclock time", but unlike C<time>, above,	259	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	260	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	261	the event loop (most return the same time as C<time>, above). This is the
258	time that AnyEvent timers get scheduled against.	262	time that AnyEvent's timers get scheduled against.
		263
		264	I<In almost all cases (in all cases if you don't care), this is the
		265	function to call when you want to know the current time.>
		266
		267	This function is also often faster then C<< AnyEvent->time >>, and
		268	thus the preferred method if you want some timestamp (for example,
		269	L<AnyEvent::Handle> uses this to update it's activity timeouts).
		270
		271	The rest of this section is only of relevance if you try to be very exact
		272	with your timing, you can skip it without bad conscience.
259		273
260	For a practical example of when these times differ, consider L<Event::Lib>	274	For a practical example of when these times differ, consider L<Event::Lib>
261	and L<EV> and the following set-up:	275	and L<EV> and the following set-up:
262		276
263	The event loop is running and has just invoked one of your callback at	277	The event loop is running and has just invoked one of your callback at
…		…
268		282
269	With L<Event::Lib>, C<< AnyEvent->time >> and C<< AnyEvent->now >> will	283	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	284	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>).	285	be scheduled to fire at time=504 (C<501> + C<3>).
272		286
273	With L<EV>m C<< AnyEvent->time >> returns C<501> (as that is the current	287	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	288	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	289	last event processing phase started. With L<EV>, your timer gets scheduled
276	to run at time=503 (C<500> + C<3>).	290	to run at time=503 (C<500> + C<3>).
277		291
278	In one sense, L<Event::Lib> is more exact, as it uses the current time	292	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	293	regardless of any delays introduced by event processing. However, most
280	callbacks do not expect large delays in processing, so this causes a	294	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).	295	higher drift (and a lot more system calls to get the current time).
282		296
283	In another sense, L<EV> is more exact, as your timer will be scheduled at	297	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.	298	the same time, regardless of how long event processing actually took.
285		299
286	In either case, if you care (and in most cases, you don't), then you	300	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	352	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>).	353	C<fork> the child (alternatively, you can call C<AnyEvent::detect>).
340		354
341	Example: fork a process and wait for it	355	Example: fork a process and wait for it
342		356
343	my $done = AnyEvent->condvar;	357	my $done = AnyEvent->condvar;
344		358
345	my $pid = fork or exit 5;	359	my $pid = fork or exit 5;
346		360
347	my $w = AnyEvent->child (	361	my $w = AnyEvent->child (
348	pid => $pid,	362	pid => $pid,
349	cb => sub {	363	cb => sub {
350	my ($pid, $status) = @_;	364	my ($pid, $status) = @_;
351	warn "pid $pid exited with status $status";	365	warn "pid $pid exited with status $status";
352	$done->send;	366	$done->send;
353	},	367	},
354	);	368	);
355		369
356	# do something else, then wait for process exit	370	# do something else, then wait for process exit
357	$done->recv;	371	$done->recv;
358		372
359	=head2 CONDITION VARIABLES	373	=head2 CONDITION VARIABLES
360		374
361	If you are familiar with some event loops you will know that all of them	375	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	376	require you to run some blocking "loop", "run" or similar function that
…		…
583		597
584	This is a mutator function that returns the callback set and optionally	598	This is a mutator function that returns the callback set and optionally
585	replaces it before doing so.	599	replaces it before doing so.
586		600
587	The callback will be called when the condition becomes "true", i.e. when	601	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	602	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.	603	variable itself. Calling C<recv> inside the callback or at any later time
		604	is guaranteed not to block.
590		605
591	=back	606	=back
592		607
593	=head1 GLOBAL VARIABLES AND FUNCTIONS	608	=head1 GLOBAL VARIABLES AND FUNCTIONS
594		609
…		…
737		752
738	=item L<AnyEvent::DNS>	753	=item L<AnyEvent::DNS>
739		754
740	Provides rich asynchronous DNS resolver capabilities.	755	Provides rich asynchronous DNS resolver capabilities.
741		756
		757	=item L<AnyEvent::HTTP>
		758
		759	A simple-to-use HTTP library that is capable of making a lot of concurrent
		760	HTTP requests.
		761
742	=item L<AnyEvent::HTTPD>	762	=item L<AnyEvent::HTTPD>
743		763
744	Provides a simple web application server framework.	764	Provides a simple web application server framework.
745		765
746	=item L<AnyEvent::FastPing>	766	=item L<AnyEvent::FastPing>
747		767
748	The fastest ping in the west.	768	The fastest ping in the west.
		769
		770	=item L<AnyEvent::DBI>
		771
		772	Executes DBI requests asynchronously in a proxy process.
749		773
750	=item L<Net::IRC3>	774	=item L<Net::IRC3>
751		775
752	AnyEvent based IRC client module family.	776	AnyEvent based IRC client module family.
753		777
…		…
792	no warnings;	816	no warnings;
793	use strict;	817	use strict;
794		818
795	use Carp;	819	use Carp;
796		820
797	our $VERSION = '4.05';	821	our $VERSION = 4.152;
798	our $MODEL;	822	our $MODEL;
799		823
800	our $AUTOLOAD;	824	our $AUTOLOAD;
801	our @ISA;	825	our @ISA;
802		826
…		…
1158	This functionality might change in future versions.	1182	This functionality might change in future versions.
1159		1183
1160	For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you	1184	For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1161	could start your program like this:	1185	could start your program like this:
1162		1186
1163	PERL_ANYEVENT_MODEL=Perl perl ...	1187	PERL_ANYEVENT_MODEL=Perl perl ...
1164		1188
1165	=item C<PERL_ANYEVENT_PROTOCOLS>	1189	=item C<PERL_ANYEVENT_PROTOCOLS>
1166		1190
1167	Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences	1191	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	1192	for IPv4 or IPv6. The default is unspecified (and might change, or be the result
…		…
1643	specified in the variable.	1667	specified in the variable.
1644		1668
1645	You can make AnyEvent completely ignore this variable by deleting it	1669	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:	1670	before the first watcher gets created, e.g. with a C<BEGIN> block:
1647		1671
1648	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }	1672	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1649		1673
1650	use AnyEvent;	1674	use AnyEvent;
1651		1675
1652	Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can	1676	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	1677	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).	1678	probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
		1679
		1680
		1681	=head1 BUGS
		1682
		1683	Perl 5.8 has numerous memleaks that sometimes hit this module and are hard
		1684	to work around. If you suffer from memleaks, first upgrade to Perl 5.10
		1685	and check wether the leaks still show up. (Perl 5.10.0 has other annoying
		1686	mamleaks, such as leaking on C<map> and C<grep> but it is usually not as
		1687	pronounced).
1655		1688
1656		1689
1657	=head1 SEE ALSO	1690	=head1 SEE ALSO
1658		1691
1659	Utility functions: L<AnyEvent::Util>.	1692	Utility functions: L<AnyEvent::Util>.
…		…
1676	Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.	1709	Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1677		1710
1678		1711
1679	=head1 AUTHOR	1712	=head1 AUTHOR
1680		1713
1681	Marc Lehmann <schmorp@schmorp.de>	1714	Marc Lehmann <schmorp@schmorp.de>
1682	http://home.schmorp.de/	1715	http://home.schmorp.de/
1683		1716
1684	=cut	1717	=cut
1685		1718
1686	1	1719	1
1687		1720

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.160 by root, Sun Jun 22 12:17:47 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.160 by root, Sun Jun 22 12:17:47 2008 UTC