[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.165 by root, Tue Jul 8 23:07:26 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 strictly positive number (> 0), then the
193	and Glib).	199	callback will be invoked regularly at that interval (in fractional
		200	seconds) after the first invocation. If C<interval> is specified with a
		201	false value, then it is treated as if it were missing.
194		202
195	Example:	203	The callback will be rescheduled before invoking the callback, but no
		204	attempt is done to avoid timer drift in most backends, so the interval is
		205	only approximate.
196		206
197	# fire an event after 7.7 seconds	207	Example: fire an event after 7.7 seconds.
		208
198	my $w = AnyEvent->timer (after => 7.7, cb => sub {	209	my $w = AnyEvent->timer (after => 7.7, cb => sub {
199	warn "timeout\n";	210	warn "timeout\n";
200	});	211	});
201		212
202	# to cancel the timer:	213	# to cancel the timer:
203	undef $w;	214	undef $w;
204		215
205	Example 2:
206
207	# fire an event after 0.5 seconds, then roughly every second	216	Example 2: fire an event after 0.5 seconds, then roughly every second.
208	my $w;
209		217
210	my $cb = sub {
211	# cancel the old timer while creating a new one
212	$w = AnyEvent->timer (after => 1, cb => $cb);	218	my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
		219	warn "timeout\n";
213	};	220	};
214
215	# start the "loop" by creating the first watcher
216	$w = AnyEvent->timer (after => 0.5, cb => $cb);
217		221
218	=head3 TIMING ISSUES	222	=head3 TIMING ISSUES
219		223
220	There are two ways to handle timers: based on real time (relative, "fire	224	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	225	in 10 seconds") and based on wallclock time (absolute, "fire at 12
…		…
243		247
244	This returns the "current wallclock time" as a fractional number of	248	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>	249	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).	250	return, and the result is guaranteed to be compatible with those).
247		251
248	It progresses independently of any event loop processing.	252	It progresses independently of any event loop processing, i.e. each call
249		253	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		254
253	=item AnyEvent->now	255	=item AnyEvent->now
254		256
255	This also returns the "current wallclock time", but unlike C<time>, above,	257	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	258	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	259	the event loop (most return the same time as C<time>, above). This is the
258	time that AnyEvent timers get scheduled against.	260	time that AnyEvent's timers get scheduled against.
		261
		262	I<In almost all cases (in all cases if you don't care), this is the
		263	function to call when you want to know the current time.>
		264
		265	This function is also often faster then C<< AnyEvent->time >>, and
		266	thus the preferred method if you want some timestamp (for example,
		267	L<AnyEvent::Handle> uses this to update it's activity timeouts).
		268
		269	The rest of this section is only of relevance if you try to be very exact
		270	with your timing, you can skip it without bad conscience.
259		271
260	For a practical example of when these times differ, consider L<Event::Lib>	272	For a practical example of when these times differ, consider L<Event::Lib>
261	and L<EV> and the following set-up:	273	and L<EV> and the following set-up:
262		274
263	The event loop is running and has just invoked one of your callback at	275	The event loop is running and has just invoked one of your callback at
…		…
268		280
269	With L<Event::Lib>, C<< AnyEvent->time >> and C<< AnyEvent->now >> will	281	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	282	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>).	283	be scheduled to fire at time=504 (C<501> + C<3>).
272		284
273	With L<EV>m C<< AnyEvent->time >> returns C<501> (as that is the current	285	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	286	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	287	last event processing phase started. With L<EV>, your timer gets scheduled
276	to run at time=503 (C<500> + C<3>).	288	to run at time=503 (C<500> + C<3>).
277		289
278	In one sense, L<Event::Lib> is more exact, as it uses the current time	290	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	291	regardless of any delays introduced by event processing. However, most
280	callbacks do not expect large delays in processing, so this causes a	292	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).	293	higher drift (and a lot more system calls to get the current time).
282		294
283	In another sense, L<EV> is more exact, as your timer will be scheduled at	295	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.	296	the same time, regardless of how long event processing actually took.
285		297
286	In either case, if you care (and in most cases, you don't), then you	298	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	350	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>).	351	C<fork> the child (alternatively, you can call C<AnyEvent::detect>).
340		352
341	Example: fork a process and wait for it	353	Example: fork a process and wait for it
342		354
343	my $done = AnyEvent->condvar;	355	my $done = AnyEvent->condvar;
344		356
345	my $pid = fork or exit 5;	357	my $pid = fork or exit 5;
346		358
347	my $w = AnyEvent->child (	359	my $w = AnyEvent->child (
348	pid => $pid,	360	pid => $pid,
349	cb => sub {	361	cb => sub {
350	my ($pid, $status) = @_;	362	my ($pid, $status) = @_;
351	warn "pid $pid exited with status $status";	363	warn "pid $pid exited with status $status";
352	$done->send;	364	$done->send;
353	},	365	},
354	);	366	);
355		367
356	# do something else, then wait for process exit	368	# do something else, then wait for process exit
357	$done->recv;	369	$done->recv;
358		370
359	=head2 CONDITION VARIABLES	371	=head2 CONDITION VARIABLES
360		372
361	If you are familiar with some event loops you will know that all of them	373	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	374	require you to run some blocking "loop", "run" or similar function that
…		…
583		595
584	This is a mutator function that returns the callback set and optionally	596	This is a mutator function that returns the callback set and optionally
585	replaces it before doing so.	597	replaces it before doing so.
586		598
587	The callback will be called when the condition becomes "true", i.e. when	599	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	600	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.	601	variable itself. Calling C<recv> inside the callback or at any later time
		602	is guaranteed not to block.
590		603
591	=back	604	=back
592		605
593	=head1 GLOBAL VARIABLES AND FUNCTIONS	606	=head1 GLOBAL VARIABLES AND FUNCTIONS
594		607
…		…
723	=item L<AnyEvent::Util>	736	=item L<AnyEvent::Util>
724		737
725	Contains various utility functions that replace often-used but blocking	738	Contains various utility functions that replace often-used but blocking
726	functions such as C<inet_aton> by event-/callback-based versions.	739	functions such as C<inet_aton> by event-/callback-based versions.
727		740
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>	741	=item L<AnyEvent::Socket>
733		742
734	Provides various utility functions for (internet protocol) sockets,	743	Provides various utility functions for (internet protocol) sockets,
735	addresses and name resolution. Also functions to create non-blocking tcp	744	addresses and name resolution. Also functions to create non-blocking tcp
736	connections or tcp servers, with IPv6 and SRV record support and more.	745	connections or tcp servers, with IPv6 and SRV record support and more.
737		746
		747	=item L<AnyEvent::Handle>
		748
		749	Provide read and write buffers, manages watchers for reads and writes,
		750	supports raw and formatted I/O, I/O queued and fully transparent and
		751	non-blocking SSL/TLS.
		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 L<DBI> requests asynchronously in a proxy process.
		773
		774	=item L<AnyEvent::AIO>
		775
		776	Truly asynchronous I/O, should be in the toolbox of every event
		777	programmer. AnyEvent::AIO transparently fuses L<IO::AIO> and AnyEvent
		778	together.
		779
		780	=item L<AnyEvent::BDB>
		781
		782	Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently fuses
		783	L<BDB> and AnyEvent together.
		784
		785	=item L<AnyEvent::GPSD>
		786
		787	A non-blocking interface to gpsd, a daemon delivering GPS information.
		788
		789	=item L<AnyEvent::IGS>
		790
		791	A non-blocking interface to the Internet Go Server protocol (used by
		792	L<App::IGS>).
749		793
750	=item L<Net::IRC3>	794	=item L<Net::IRC3>
751		795
752	AnyEvent based IRC client module family.	796	AnyEvent based IRC client module family.
753		797
…		…
766		810
767	=item L<Coro>	811	=item L<Coro>
768		812
769	Has special support for AnyEvent via L<Coro::AnyEvent>.	813	Has special support for AnyEvent via L<Coro::AnyEvent>.
770		814
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>	815	=item L<IO::Lambda>
783		816
784	The lambda approach to I/O - don't ask, look there. Can use AnyEvent.	817	The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
785		818
786	=back	819	=back
…		…
792	no warnings;	825	no warnings;
793	use strict;	826	use strict;
794		827
795	use Carp;	828	use Carp;
796		829
797	our $VERSION = '4.05';	830	our $VERSION = 4.2;
798	our $MODEL;	831	our $MODEL;
799		832
800	our $AUTOLOAD;	833	our $AUTOLOAD;
801	our @ISA;	834	our @ISA;
802		835
…		…
964	sub AnyEvent::Base::Signal::DESTROY {	997	sub AnyEvent::Base::Signal::DESTROY {
965	my ($signal, $cb) = @{$_[0]};	998	my ($signal, $cb) = @{$_[0]};
966		999
967	delete $SIG_CB{$signal}{$cb};	1000	delete $SIG_CB{$signal}{$cb};
968		1001
969	$SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };	1002	delete $SIG{$signal} unless keys %{ $SIG_CB{$signal} };
970	}	1003	}
971		1004
972	# default implementation for ->child	1005	# default implementation for ->child
973		1006
974	our %PID_CB;	1007	our %PID_CB;
…		…
1158	This functionality might change in future versions.	1191	This functionality might change in future versions.
1159		1192
1160	For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you	1193	For example, to force the pure perl model (L<AnyEvent::Impl::Perl>) you
1161	could start your program like this:	1194	could start your program like this:
1162		1195
1163	PERL_ANYEVENT_MODEL=Perl perl ...	1196	PERL_ANYEVENT_MODEL=Perl perl ...
1164		1197
1165	=item C<PERL_ANYEVENT_PROTOCOLS>	1198	=item C<PERL_ANYEVENT_PROTOCOLS>
1166		1199
1167	Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences	1200	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	1201	for IPv4 or IPv6. The default is unspecified (and might change, or be the result
…		…
1643	specified in the variable.	1676	specified in the variable.
1644		1677
1645	You can make AnyEvent completely ignore this variable by deleting it	1678	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:	1679	before the first watcher gets created, e.g. with a C<BEGIN> block:
1647		1680
1648	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }	1681	BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1649		1682
1650	use AnyEvent;	1683	use AnyEvent;
1651		1684
1652	Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can	1685	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	1686	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).	1687	probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
		1688
		1689
		1690	=head1 BUGS
		1691
		1692	Perl 5.8 has numerous memleaks that sometimes hit this module and are hard
		1693	to work around. If you suffer from memleaks, first upgrade to Perl 5.10
		1694	and check wether the leaks still show up. (Perl 5.10.0 has other annoying
		1695	mamleaks, such as leaking on C<map> and C<grep> but it is usually not as
		1696	pronounced).
1655		1697
1656		1698
1657	=head1 SEE ALSO	1699	=head1 SEE ALSO
1658		1700
1659	Utility functions: L<AnyEvent::Util>.	1701	Utility functions: L<AnyEvent::Util>.
…		…
1676	Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.	1718	Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>.
1677		1719
1678		1720
1679	=head1 AUTHOR	1721	=head1 AUTHOR
1680		1722
1681	Marc Lehmann <schmorp@schmorp.de>	1723	Marc Lehmann <schmorp@schmorp.de>
1682	http://home.schmorp.de/	1724	http://home.schmorp.de/
1683		1725
1684	=cut	1726	=cut
1685		1727
1686	1	1728	1
1687		1729

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.165 by root, Tue Jul 8 23:07:26 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.165 by root, Tue Jul 8 23:07:26 2008 UTC