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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.17 by root, Fri Nov 24 14:40:13 2006 UTC vs.
Revision 1.47 by root, Mon Apr 14 16:09:33 2008 UTC

…		…
17	});	17	});
18		18
19	my $w = AnyEvent->condvar; # stores wether a condition was flagged	19	my $w = AnyEvent->condvar; # stores wether a condition was flagged
20	$w->wait; # enters "main loop" till $condvar gets ->broadcast	20	$w->wait; # enters "main loop" till $condvar gets ->broadcast
21	$w->broadcast; # wake up current and all future wait's	21	$w->broadcast; # wake up current and all future wait's
		22
		23	=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
		24
		25	Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
		26	nowadays. So what is different about AnyEvent?
		27
		28	Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of
		29	policy> and AnyEvent is I<small and efficient>.
		30
		31	First and foremost, I<AnyEvent is not an event model> itself, it only
		32	interfaces to whatever event model the main program happens to use in a
		33	pragmatic way. For event models and certain classes of immortals alike,
		34	the statement "there can only be one" is a bitter reality, and AnyEvent
		35	helps hiding the differences.
		36
		37	The goal of AnyEvent is to offer module authors the ability to do event
		38	programming (waiting for I/O or timer events) without subscribing to a
		39	religion, a way of living, and most importantly: without forcing your
		40	module users into the same thing by forcing them to use the same event
		41	model you use.
		42
		43	For modules like POE or IO::Async (which is actually doing all I/O
		44	I<synchronously>...), using them in your module is like joining a
		45	cult: After you joined, you are dependent on them and you cannot use
		46	anything else, as it is simply incompatible to everything that isn't
		47	itself.
		48
		49	AnyEvent + POE works fine. AnyEvent + Glib works fine. AnyEvent + Tk
		50	works fine etc. etc. but none of these work together with the rest: POE
		51	+ IO::Async? no go. Tk + Event? no go. If your module uses one of
		52	those, every user of your module has to use it, too. If your module
		53	uses AnyEvent, it works transparently with all event models it supports
		54	(including stuff like POE and IO::Async).
		55
		56	In addition of being free of having to use I<the one and only true event
		57	model>, AnyEvent also is free of bloat and policy: with POE or similar
		58	modules, you get an enourmous amount of code and strict rules you have
		59	to follow. AnyEvent, on the other hand, is lean and to the point by only
		60	offering the functionality that is useful, in as thin as a wrapper as
		61	technically possible.
		62
		63	Of course, if you want lots of policy (this can arguably be somewhat
		64	useful) and you want to force your users to use the one and only event
		65	model, you should I<not> use this module.
		66
22		67
23	=head1 DESCRIPTION	68	=head1 DESCRIPTION
24		69
25	L<AnyEvent> provides an identical interface to multiple event loops. This	70	L<AnyEvent> provides an identical interface to multiple event loops. This
26	allows module authors to utilise an event loop without forcing module	71	allows module authors to utilise an event loop without forcing module
…		…
70	You can create I/O watcher by calling the C<< AnyEvent->io >> method with	115	You can create I/O watcher by calling the C<< AnyEvent->io >> method with
71	the following mandatory arguments:	116	the following mandatory arguments:
72		117
73	C<fh> the Perl I<filehandle> (not filedescriptor) to watch for	118	C<fh> the Perl I<filehandle> (not filedescriptor) to watch for
74	events. C<poll> must be a string that is either C<r> or C<w>, that creates	119	events. C<poll> must be a string that is either C<r> or C<w>, that creates
75	a watcher waiting for "r"eadable or "w"ritable events. C<cb> teh callback	120	a watcher waiting for "r"eadable or "w"ritable events. C<cb> the callback
76	to invoke everytime the filehandle becomes ready.	121	to invoke everytime the filehandle becomes ready.
77		122
78	Only one io watcher per C<fh> and C<poll> combination is allowed (i.e. on	123	Only one io watcher per C<fh> and C<poll> combination is allowed (i.e. on
79	a socket you can have one r + one w, not any more (limitation comes from	124	a socket you can have one r + one w, not any more (limitation comes from
80	Tk - if you are sure you are not using Tk this limitation is gone).	125	Tk - if you are sure you are not using Tk this limitation is gone).
…		…
89	chomp (my $input = <STDIN>);	134	chomp (my $input = <STDIN>);
90	warn "read: $input\n";	135	warn "read: $input\n";
91	undef $w;	136	undef $w;
92	});	137	});
93		138
94	=head2 TIMER WATCHERS	139	=head2 TIME WATCHERS
95		140
96	You can create a timer watcher by calling the C<< AnyEvent->timer >>	141	You can create a time watcher by calling the C<< AnyEvent->timer >>
97	method with the following mandatory arguments:	142	method with the following mandatory arguments:
98		143
99	C<after> after how many seconds (fractions are supported) should the timer	144	C<after> after how many seconds (fractions are supported) should the timer
100	activate. C<cb> the callback to invoke.	145	activate. C<cb> the callback to invoke.
101		146
…		…
109	my $w = AnyEvent->timer (after => 7.7, cb => sub {	154	my $w = AnyEvent->timer (after => 7.7, cb => sub {
110	warn "timeout\n";	155	warn "timeout\n";
111	});	156	});
112		157
113	# to cancel the timer:	158	# to cancel the timer:
114	undef $w	159	undef $w;
115		160
116	=head2 CONDITION WATCHERS	161	=head2 CONDITION WATCHERS
117		162
118	Condition watchers can be created by calling the C<< AnyEvent->condvar >>	163	Condition watchers can be created by calling the C<< AnyEvent->condvar >>
119	method without any arguments.	164	method without any arguments.
120		165
121	A condition watcher watches for a condition - precisely that the C<<	166	A condition watcher watches for a condition - precisely that the C<<
122	->broadcast >> method has been called.	167	->broadcast >> method has been called.
123		168
		169	Note that condition watchers recurse into the event loop - if you have
		170	two watchers that call C<< ->wait >> in a round-robbin fashion, you
		171	lose. Therefore, condition watchers are good to export to your caller, but
		172	you should avoid making a blocking wait, at least in callbacks, as this
		173	usually asks for trouble.
		174
124	The watcher has only two methods:	175	The watcher has only two methods:
125		176
126	=over 4	177	=over 4
127		178
128	=item $cv->wait	179	=item $cv->wait
129		180
130	Wait (blocking if necessary) until the C<< ->broadcast >> method has been	181	Wait (blocking if necessary) until the C<< ->broadcast >> method has been
131	called on c<$cv>, while servicing other watchers normally.	182	called on c<$cv>, while servicing other watchers normally.
132		183
133	Not all event models support a blocking wait - some die in that case, so
134	if you are using this from a module, never require a blocking wait, but
135	let the caller decide wether the call will block or not (for example,
136	by coupling condition variables with some kind of request results and
137	supporting callbacks so the caller knows that getting the result will not
138	block, while still suppporting blockign waits if the caller so desires).
139
140	You can only wait once on a condition - additional calls will return	184	You can only wait once on a condition - additional calls will return
141	immediately.	185	immediately.
		186
		187	Not all event models support a blocking wait - some die in that case
		188	(programs might want to do that so they stay interactive), so I<if you
		189	are using this from a module, never require a blocking wait>, but let the
		190	caller decide wether the call will block or not (for example, by coupling
		191	condition variables with some kind of request results and supporting
		192	callbacks so the caller knows that getting the result will not block,
		193	while still suppporting blocking waits if the caller so desires).
		194
		195	Another reason I<never> to C<< ->wait >> in a module is that you cannot
		196	sensibly have two C<< ->wait >>'s in parallel, as that would require
		197	multiple interpreters or coroutines/threads, none of which C<AnyEvent>
		198	can supply (the coroutine-aware backends C<Coro::EV> and C<Coro::Event>
		199	explicitly support concurrent C<< ->wait >>'s from different coroutines,
		200	however).
142		201
143	=item $cv->broadcast	202	=item $cv->broadcast
144		203
145	Flag the condition as ready - a running C<< ->wait >> and all further	204	Flag the condition as ready - a running C<< ->wait >> and all further
146	calls to C<wait> will return after this method has been called. If nobody	205	calls to C<wait> will return after this method has been called. If nobody
…		…
156	# when the "result" is ready.	215	# when the "result" is ready.
157		216
158	$result_ready->wait;	217	$result_ready->wait;
159		218
160	=back	219	=back
		220
		221	=head2 SIGNAL WATCHERS
		222
		223	You can listen for signals using a signal watcher, C<signal> is the signal
		224	I<name> without any C<SIG> prefix. Multiple signals events can be clumped
		225	together into one callback invocation, and callback invocation might or
		226	might not be asynchronous.
		227
		228	These watchers might use C<%SIG>, so programs overwriting those signals
		229	directly will likely not work correctly.
		230
		231	Example: exit on SIGINT
		232
		233	my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
		234
		235	=head2 CHILD PROCESS WATCHERS
		236
		237	You can also listen for the status of a child process specified by the
		238	C<pid> argument (or any child if the pid argument is 0). The watcher will
		239	trigger as often as status change for the child are received. This works
		240	by installing a signal handler for C<SIGCHLD>. The callback will be called with
		241	the pid and exit status (as returned by waitpid).
		242
		243	Example: wait for pid 1333
		244
		245	my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
161		246
162	=head1 GLOBALS	247	=head1 GLOBALS
163		248
164	=over 4	249	=over 4
165		250
…		…
171	C<AnyEvent::Impl:xxx> modules, but can be any other class in the case	256	C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
172	AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).	257	AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
173		258
174	The known classes so far are:	259	The known classes so far are:
175		260
176	AnyEvent::Impl::Coro based on Coro::Event, best choise.	261	AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
		262	AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
		263	AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
177	AnyEvent::Impl::Event based on Event, also best choice :)	264	AnyEvent::Impl::Event based on Event, also second best choice :)
178	AnyEvent::Impl::Glib based on Glib, second-best choice.	265	AnyEvent::Impl::Glib based on Glib, second-best choice.
179	AnyEvent::Impl::Tk based on Tk, very bad choice.	266	AnyEvent::Impl::Tk based on Tk, very bad choice.
180	AnyEvent::Impl::Perl pure-perl implementation, inefficient.	267	AnyEvent::Impl::Perl pure-perl implementation, inefficient.
		268
		269	=item AnyEvent::detect
		270
		271	Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
		272	necessary. You should only call this function right before you would have
		273	created an AnyEvent watcher anyway, that is, very late at runtime.
181		274
182	=back	275	=back
183		276
184	=head1 WHAT TO DO IN A MODULE	277	=head1 WHAT TO DO IN A MODULE
185		278
…		…
214	=cut	307	=cut
215		308
216	package AnyEvent;	309	package AnyEvent;
217		310
218	no warnings;	311	no warnings;
219	use strict 'vars';	312	use strict;
		313
220	use Carp;	314	use Carp;
221		315
222	our $VERSION = '2.1';	316	our $VERSION = '3.0';
223	our $MODEL;	317	our $MODEL;
224		318
225	our $AUTOLOAD;	319	our $AUTOLOAD;
226	our @ISA;	320	our @ISA;
227		321
228	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;	322	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
229		323
230	our @REGISTRY;	324	our @REGISTRY;
231		325
232	my @models = (	326	my @models = (
		327	[Coro::EV:: => AnyEvent::Impl::CoroEV::],
		328	[EV:: => AnyEvent::Impl::EV::],
233	[Coro::Event:: => AnyEvent::Impl::Coro::],	329	[Coro::Event:: => AnyEvent::Impl::CoroEvent::],
234	[Event:: => AnyEvent::Impl::Event::],	330	[Event:: => AnyEvent::Impl::Event::],
235	[Glib:: => AnyEvent::Impl::Glib::],	331	[Glib:: => AnyEvent::Impl::Glib::],
236	[Tk:: => AnyEvent::Impl::Tk::],	332	[Tk:: => AnyEvent::Impl::Tk::],
237	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],	333	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
238	);	334	);
239		335
240	our %method = map +($_ => 1), qw(io timer condvar broadcast wait DESTROY);	336	our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY);
241		337
242	sub AUTOLOAD {	338	sub detect() {
243	$AUTOLOAD =~ s/.*://;
244
245	$method{$AUTOLOAD}
246	or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
247
248	unless ($MODEL) {	339	unless ($MODEL) {
		340	no strict 'refs';
		341
249	# check for already loaded models	342	# check for already loaded models
250	for (@REGISTRY, @models) {	343	for (@REGISTRY, @models) {
251	my ($package, $model) = @$_;	344	my ($package, $model) = @$_;
252	if (${"$package\::VERSION"} > 0) {	345	if (${"$package\::VERSION"} > 0) {
253	if (eval "require $model") {	346	if (eval "require $model") {
…		…
261	unless ($MODEL) {	354	unless ($MODEL) {
262	# try to load a model	355	# try to load a model
263		356
264	for (@REGISTRY, @models) {	357	for (@REGISTRY, @models) {
265	my ($package, $model) = @$_;	358	my ($package, $model) = @$_;
		359	if (eval "require $package"
		360	and ${"$package\::VERSION"} > 0
266	if (eval "require $model") {	361	and eval "require $model") {
267	$MODEL = $model;	362	$MODEL = $model;
268	warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;	363	warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
269	last;	364	last;
270	}	365	}
271	}	366	}
272		367
273	$MODEL	368	$MODEL
274	or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Coro, Event, Glib or Tk.";	369	or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV (or Coro+EV), Event (or Coro+Event), Glib or Tk.";
275	}	370	}
		371
		372	unshift @ISA, $MODEL;
		373	push @{"$MODEL\::ISA"}, "AnyEvent::Base";
276	}	374	}
277		375
278	@ISA = $MODEL;	376	$MODEL
		377	}
		378
		379	sub AUTOLOAD {
		380	(my $func = $AUTOLOAD) =~ s/.*://;
		381
		382	$method{$func}
		383	or croak "$func: not a valid method for AnyEvent objects";
		384
		385	detect unless $MODEL;
279		386
280	my $class = shift;	387	my $class = shift;
281	$class->$AUTOLOAD (@_);	388	$class->$func (@_);
		389	}
		390
		391	package AnyEvent::Base;
		392
		393	# default implementation for ->condvar, ->wait, ->broadcast
		394
		395	sub condvar {
		396	bless \my $flag, "AnyEvent::Base::CondVar"
		397	}
		398
		399	sub AnyEvent::Base::CondVar::broadcast {
		400	${$_[0]}++;
		401	}
		402
		403	sub AnyEvent::Base::CondVar::wait {
		404	AnyEvent->one_event while !${$_[0]};
		405	}
		406
		407	# default implementation for ->signal
		408
		409	our %SIG_CB;
		410
		411	sub signal {
		412	my (undef, %arg) = @_;
		413
		414	my $signal = uc $arg{signal}
		415	or Carp::croak "required option 'signal' is missing";
		416
		417	$SIG_CB{$signal}{$arg{cb}} = $arg{cb};
		418	$SIG{$signal} \|\|= sub {
		419	$_->() for values %{ $SIG_CB{$signal} \|\| {} };
		420	};
		421
		422	bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
		423	}
		424
		425	sub AnyEvent::Base::Signal::DESTROY {
		426	my ($signal, $cb) = @{$_[0]};
		427
		428	delete $SIG_CB{$signal}{$cb};
		429
		430	$SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };
		431	}
		432
		433	# default implementation for ->child
		434
		435	our %PID_CB;
		436	our $CHLD_W;
		437	our $CHLD_DELAY_W;
		438	our $PID_IDLE;
		439	our $WNOHANG;
		440
		441	sub _child_wait {
		442	while (0 < (my $pid = waitpid -1, $WNOHANG)) {
		443	$_->($pid, $?) for (values %{ $PID_CB{$pid} \|\| {} }),
		444	(values %{ $PID_CB{0} \|\| {} });
		445	}
		446
		447	undef $PID_IDLE;
		448	}
		449
		450	sub _sigchld {
		451	# make sure we deliver these changes "synchronous" with the event loop.
		452	$CHLD_DELAY_W \|\|= AnyEvent->timer (after => 0, cb => sub {
		453	undef $CHLD_DELAY_W;
		454	&_child_wait;
		455	});
		456	}
		457
		458	sub child {
		459	my (undef, %arg) = @_;
		460
		461	defined (my $pid = $arg{pid} + 0)
		462	or Carp::croak "required option 'pid' is missing";
		463
		464	$PID_CB{$pid}{$arg{cb}} = $arg{cb};
		465
		466	unless ($WNOHANG) {
		467	$WNOHANG = eval { require POSIX; &POSIX::WNOHANG } \|\| 1;
		468	}
		469
		470	unless ($CHLD_W) {
		471	$CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
		472	# child could be a zombie already, so make at least one round
		473	&_sigchld;
		474	}
		475
		476	bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
		477	}
		478
		479	sub AnyEvent::Base::Child::DESTROY {
		480	my ($pid, $cb) = @{$_[0]};
		481
		482	delete $PID_CB{$pid}{$cb};
		483	delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
		484
		485	undef $CHLD_W unless keys %PID_CB;
282	}	486	}
283		487
284	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE	488	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
285		489
286	If you need to support another event library which isn't directly	490	If you need to support another event library which isn't directly
…		…
297	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>	501	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
298	package/class when it finds the C<urxvt> package/module is loaded. When	502	package/class when it finds the C<urxvt> package/module is loaded. When
299	AnyEvent is loaded and asked to find a suitable event model, it will	503	AnyEvent is loaded and asked to find a suitable event model, it will
300	first check for the presence of urxvt.	504	first check for the presence of urxvt.
301		505
302	The class should prove implementations for all watcher types (see	506	The class should provide implementations for all watcher types (see
303	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>	507	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
304	(Source code) and so on for actual examples, use C<perldoc -m	508	(Source code) and so on for actual examples, use C<perldoc -m
305	AnyEvent::Impl::Glib> to see the sources).	509	AnyEvent::Impl::Glib> to see the sources).
306		510
307	The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)	511	The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
…		…
311	I<rxvt-unicode> distribution.	515	I<rxvt-unicode> distribution.
312		516
313	I<rxvt-unicode> also cheats a bit by not providing blocking access to	517	I<rxvt-unicode> also cheats a bit by not providing blocking access to
314	condition variables: code blocking while waiting for a condition will	518	condition variables: code blocking while waiting for a condition will
315	C<die>. This still works with most modules/usages, and blocking calls must	519	C<die>. This still works with most modules/usages, and blocking calls must
316	not be in an interactive appliation, so it makes sense.	520	not be in an interactive application, so it makes sense.
317		521
318	=head1 ENVIRONMENT VARIABLES	522	=head1 ENVIRONMENT VARIABLES
319		523
320	The following environment variables are used by this module:	524	The following environment variables are used by this module:
321		525

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.17 by root, Fri Nov 24 14:40:13 2006 UTC vs. Revision 1.47 by root, Mon Apr 14 16:09:33 2008 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.17 by root, Fri Nov 24 14:40:13 2006 UTC vs.
Revision 1.47 by root, Mon Apr 14 16:09:33 2008 UTC