[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.151 by root, Sat May 31 13:38:01 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
…		…
792	no warnings;	807	no warnings;
793	use strict;	808	use strict;
794		809
795	use Carp;	810	use Carp;
796		811
797	our $VERSION = '4.05';	812	our $VERSION = 4.11;
798	our $MODEL;	813	our $MODEL;
799		814
800	our $AUTOLOAD;	815	our $AUTOLOAD;
801	our @ISA;	816	our @ISA;
802		817
…		…
1158	This functionality might change in future versions.	1173	This functionality might change in future versions.
1159		1174
1160	For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you	1175	For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1161	could start your program like this:	1176	could start your program like this:
1162		1177
1163	PERL_ANYEVENT_MODEL=Perl perl ...	1178	PERL_ANYEVENT_MODEL=Perl perl ...
1164		1179
1165	=item C<PERL_ANYEVENT_PROTOCOLS>	1180	=item C<PERL_ANYEVENT_PROTOCOLS>
1166		1181
1167	Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences	1182	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	1183	for IPv4 or IPv6. The default is unspecified (and might change, or be the result
…		…
1643	specified in the variable.	1658	specified in the variable.
1644		1659
1645	You can make AnyEvent completely ignore this variable by deleting it	1660	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:	1661	before the first watcher gets created, e.g. with a C<BEGIN> block:
1647		1662
1648	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }	1663	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1649		1664
1650	use AnyEvent;	1665	use AnyEvent;
1651		1666
1652	Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can	1667	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	1668	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).	1669	probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
1655		1670
…		…
1676	Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.	1691	Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1677		1692
1678		1693
1679	=head1 AUTHOR	1694	=head1 AUTHOR
1680		1695
1681	Marc Lehmann <schmorp@schmorp.de>	1696	Marc Lehmann <schmorp@schmorp.de>
1682	http://home.schmorp.de/	1697	http://home.schmorp.de/
1683		1698
1684	=cut	1699	=cut
1685		1700
1686	1	1701	1
1687		1702

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.151 by root, Sat May 31 13:38:01 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.151 by root, Sat May 31 13:38:01 2008 UTC