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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.15 by root, Mon Oct 30 20:55:05 2006 UTC vs.
Revision 1.41 by root, Mon Apr 7 19:23:59 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
		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 (the latter of which is actually
		44	named confusingly, as it does neither do I/O nor does it do anything
		45	asynchronously...), using them in your module is like joining a
		46	cult: After you joined, you are dependent on them and you cannot use
		47	anything else, as it is simply incompatible to everything that isn't
		48	itself.
		49
		50	AnyEvent + POE works fine. AnyEvent + Glib works fine. AnyEvent + Tk
		51	works fine etc. etc. but none of these work together with the rest: POE
		52	+ IO::Async? no go. Tk + Event? no go. If your module uses one of
		53	those, every user of your module has to use it, too. If your module
		54	uses AnyEvent, it works transparently with all event models it supports
		55	(including stuff like POE and IO::Async).
		56
		57	In addition of being free of having to use I<the one and only true event
		58	model>, AnyEvent also is free of bloat and policy: with POE or similar
		59	modules, you get an enourmous amount of code and strict rules you have
		60	to follow. AnyEvent, on the other hand, is lean and to the point by only
		61	offering the functionality that is useful, in as thin as a wrapper as
		62	technically possible.
		63
22		64
23	=head1 DESCRIPTION	65	=head1 DESCRIPTION
24		66
25	L<AnyEvent> provides an identical interface to multiple event loops. This	67	L<AnyEvent> provides an identical interface to multiple event loops. This
26	allows module authors to utilise an event loop without forcing module	68	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	112	You can create I/O watcher by calling the C<< AnyEvent->io >> method with
71	the following mandatory arguments:	113	the following mandatory arguments:
72		114
73	C<fh> the Perl I<filehandle> (not filedescriptor) to watch for	115	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	116	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	117	a watcher waiting for "r"eadable or "w"ritable events. C<cb> the callback
76	to invoke everytime the filehandle becomes ready.	118	to invoke everytime the filehandle becomes ready.
77		119
78	Only one io watcher per C<fh> and C<poll> combination is allowed (i.e. on	120	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	121	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).	122	Tk - if you are sure you are not using Tk this limitation is gone).
…		…
89	chomp (my $input = <STDIN>);	131	chomp (my $input = <STDIN>);
90	warn "read: $input\n";	132	warn "read: $input\n";
91	undef $w;	133	undef $w;
92	});	134	});
93		135
94	=head2 TIMER WATCHERS	136	=head2 TIME WATCHERS
95		137
96	You can create a timer watcher by calling the C<< AnyEvent->timer >>	138	You can create a time watcher by calling the C<< AnyEvent->timer >>
97	method with the following mandatory arguments:	139	method with the following mandatory arguments:
98		140
99	C<after> after how many seconds (fractions are supported) should the timer	141	C<after> after how many seconds (fractions are supported) should the timer
100	activate. C<cb> the callback to invoke.	142	activate. C<cb> the callback to invoke.
101		143
…		…
109	my $w = AnyEvent->timer (after => 7.7, cb => sub {	151	my $w = AnyEvent->timer (after => 7.7, cb => sub {
110	warn "timeout\n";	152	warn "timeout\n";
111	});	153	});
112		154
113	# to cancel the timer:	155	# to cancel the timer:
114	undef $w	156	undef $w;
115		157
116	=head2 CONDITION WATCHERS	158	=head2 CONDITION WATCHERS
117		159
118	Condition watchers can be created by calling the C<< AnyEvent->condvar >>	160	Condition watchers can be created by calling the C<< AnyEvent->condvar >>
119	method without any arguments.	161	method without any arguments.
120		162
121	A condition watcher watches for a condition - precisely that the C<<	163	A condition watcher watches for a condition - precisely that the C<<
122	->broadcast >> method has been called.	164	->broadcast >> method has been called.
		165
		166	Note that condition watchers recurse into the event loop - if you have
		167	two watchers that call C<< ->wait >> in a round-robbin fashion, you
		168	lose. Therefore, condition watchers are good to export to your caller, but
		169	you should avoid making a blocking wait, at least in callbacks, as this
		170	usually asks for trouble.
123		171
124	The watcher has only two methods:	172	The watcher has only two methods:
125		173
126	=over 4	174	=over 4
127		175
…		…
154	# do something such as adding a timer	202	# do something such as adding a timer
155	# or socket watcher the calls $result_ready->broadcast	203	# or socket watcher the calls $result_ready->broadcast
156	# when the "result" is ready.	204	# when the "result" is ready.
157		205
158	$result_ready->wait;	206	$result_ready->wait;
		207
		208	=back
		209
		210	=head2 SIGNAL WATCHERS
		211
		212	You can listen for signals using a signal watcher, C<signal> is the signal
		213	I<name> without any C<SIG> prefix. Multiple signals events can be clumped
		214	together into one callback invocation, and callback invocation might or
		215	might not be asynchronous.
		216
		217	These watchers might use C<%SIG>, so programs overwriting those signals
		218	directly will likely not work correctly.
		219
		220	Example: exit on SIGINT
		221
		222	my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
		223
		224	=head2 CHILD PROCESS WATCHERS
		225
		226	You can also listen for the status of a child process specified by the
		227	C<pid> argument (or any child if the pid argument is 0). The watcher will
		228	trigger as often as status change for the child are received. This works
		229	by installing a signal handler for C<SIGCHLD>. The callback will be called with
		230	the pid and exit status (as returned by waitpid).
		231
		232	Example: wait for pid 1333
		233
		234	my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
		235
		236	=head1 GLOBALS
		237
		238	=over 4
		239
		240	=item $AnyEvent::MODEL
		241
		242	Contains C<undef> until the first watcher is being created. Then it
		243	contains the event model that is being used, which is the name of the
		244	Perl class implementing the model. This class is usually one of the
		245	C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
		246	AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
		247
		248	The known classes so far are:
		249
		250	AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
		251	AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
		252	AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
		253	AnyEvent::Impl::Event based on Event, also second best choice :)
		254	AnyEvent::Impl::Glib based on Glib, second-best choice.
		255	AnyEvent::Impl::Tk based on Tk, very bad choice.
		256	AnyEvent::Impl::Perl pure-perl implementation, inefficient.
		257
		258	=item AnyEvent::detect
		259
		260	Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
		261	necessary. You should only call this function right before you would have
		262	created an AnyEvent watcher anyway, that is, very late at runtime.
159		263
160	=back	264	=back
161		265
162	=head1 WHAT TO DO IN A MODULE	266	=head1 WHAT TO DO IN A MODULE
163		267
…		…
192	=cut	296	=cut
193		297
194	package AnyEvent;	298	package AnyEvent;
195		299
196	no warnings;	300	no warnings;
197	use strict 'vars';	301	use strict;
		302
198	use Carp;	303	use Carp;
199		304
200	our $VERSION = '2.0';	305	our $VERSION = '3.0';
201	our $MODEL;	306	our $MODEL;
202		307
203	our $AUTOLOAD;	308	our $AUTOLOAD;
204	our @ISA;	309	our @ISA;
205		310
206	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;	311	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
207		312
208	our @REGISTRY;	313	our @REGISTRY;
209		314
210	my @models = (	315	my @models = (
		316	[Coro::EV:: => AnyEvent::Impl::CoroEV::],
		317	[EV:: => AnyEvent::Impl::EV::],
211	[Coro::Event:: => AnyEvent::Impl::Coro::],	318	[Coro::Event:: => AnyEvent::Impl::CoroEvent::],
212	[Event:: => AnyEvent::Impl::Event::],	319	[Event:: => AnyEvent::Impl::Event::],
213	[Glib:: => AnyEvent::Impl::Glib::],	320	[Glib:: => AnyEvent::Impl::Glib::],
214	[Tk:: => AnyEvent::Impl::Tk::],	321	[Tk:: => AnyEvent::Impl::Tk::],
215	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],	322	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
216	);	323	);
217		324
218	our %method = map +($_ => 1), qw(io timer condvar broadcast wait DESTROY);	325	our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY);
219		326
220	sub AUTOLOAD {	327	sub detect() {
221	$AUTOLOAD =~ s/.*://;
222
223	$method{$AUTOLOAD}
224	or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
225
226	unless ($MODEL) {	328	unless ($MODEL) {
		329	no strict 'refs';
		330
227	# check for already loaded models	331	# check for already loaded models
228	for (@REGISTRY, @models) {	332	for (@REGISTRY, @models) {
229	my ($package, $model) = @$_;	333	my ($package, $model) = @$_;
230	if (${"$package\::VERSION"} > 0) {	334	if (${"$package\::VERSION"} > 0) {
231	if (eval "require $model") {	335	if (eval "require $model") {
…		…
239	unless ($MODEL) {	343	unless ($MODEL) {
240	# try to load a model	344	# try to load a model
241		345
242	for (@REGISTRY, @models) {	346	for (@REGISTRY, @models) {
243	my ($package, $model) = @$_;	347	my ($package, $model) = @$_;
		348	if (eval "require $package"
		349	and ${"$package\::VERSION"} > 0
244	if (eval "require $model") {	350	and eval "require $model") {
245	$MODEL = $model;	351	$MODEL = $model;
246	warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;	352	warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
247	last;	353	last;
248	}	354	}
249	}	355	}
250		356
251	$MODEL	357	$MODEL
252	or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Coro, Event, Glib or Tk.";	358	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.";
253	}	359	}
		360
		361	unshift @ISA, $MODEL;
		362	push @{"$MODEL\::ISA"}, "AnyEvent::Base";
254	}	363	}
255		364
256	@ISA = $MODEL;	365	$MODEL
		366	}
		367
		368	sub AUTOLOAD {
		369	(my $func = $AUTOLOAD) =~ s/.*://;
		370
		371	$method{$func}
		372	or croak "$func: not a valid method for AnyEvent objects";
		373
		374	detect unless $MODEL;
257		375
258	my $class = shift;	376	my $class = shift;
259	$class->$AUTOLOAD (@_);	377	$class->$func (@_);
		378	}
		379
		380	package AnyEvent::Base;
		381
		382	# default implementation for ->condvar, ->wait, ->broadcast
		383
		384	sub condvar {
		385	bless \my $flag, "AnyEvent::Base::CondVar"
		386	}
		387
		388	sub AnyEvent::Base::CondVar::broadcast {
		389	${$_[0]}++;
		390	}
		391
		392	sub AnyEvent::Base::CondVar::wait {
		393	AnyEvent->one_event while !${$_[0]};
		394	}
		395
		396	# default implementation for ->signal
		397
		398	our %SIG_CB;
		399
		400	sub signal {
		401	my (undef, %arg) = @_;
		402
		403	my $signal = uc $arg{signal}
		404	or Carp::croak "required option 'signal' is missing";
		405
		406	$SIG_CB{$signal}{$arg{cb}} = $arg{cb};
		407	$SIG{$signal} \|\|= sub {
		408	$_->() for values %{ $SIG_CB{$signal} \|\| {} };
		409	};
		410
		411	bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
		412	}
		413
		414	sub AnyEvent::Base::Signal::DESTROY {
		415	my ($signal, $cb) = @{$_[0]};
		416
		417	delete $SIG_CB{$signal}{$cb};
		418
		419	$SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };
		420	}
		421
		422	# default implementation for ->child
		423
		424	our %PID_CB;
		425	our $CHLD_W;
		426	our $CHLD_DELAY_W;
		427	our $PID_IDLE;
		428	our $WNOHANG;
		429
		430	sub _child_wait {
		431	while (0 < (my $pid = waitpid -1, $WNOHANG)) {
		432	$_->($pid, $?) for (values %{ $PID_CB{$pid} \|\| {} }),
		433	(values %{ $PID_CB{0} \|\| {} });
		434	}
		435
		436	undef $PID_IDLE;
		437	}
		438
		439	sub _sigchld {
		440	# make sure we deliver these changes "synchronous" with the event loop.
		441	$CHLD_DELAY_W \|\|= AnyEvent->timer (after => 0, cb => sub {
		442	undef $CHLD_DELAY_W;
		443	&_child_wait;
		444	});
		445	}
		446
		447	sub child {
		448	my (undef, %arg) = @_;
		449
		450	defined (my $pid = $arg{pid} + 0)
		451	or Carp::croak "required option 'pid' is missing";
		452
		453	$PID_CB{$pid}{$arg{cb}} = $arg{cb};
		454
		455	unless ($WNOHANG) {
		456	$WNOHANG = eval { require POSIX; &POSIX::WNOHANG } \|\| 1;
		457	}
		458
		459	unless ($CHLD_W) {
		460	$CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
		461	# child could be a zombie already, so make at least one round
		462	&_sigchld;
		463	}
		464
		465	bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
		466	}
		467
		468	sub AnyEvent::Base::Child::DESTROY {
		469	my ($pid, $cb) = @{$_[0]};
		470
		471	delete $PID_CB{$pid}{$cb};
		472	delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
		473
		474	undef $CHLD_W unless keys %PID_CB;
260	}	475	}
261		476
262	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE	477	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
263		478
264	If you need to support another event library which isn't directly	479	If you need to support another event library which isn't directly
…		…
275	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>	490	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
276	package/class when it finds the C<urxvt> package/module is loaded. When	491	package/class when it finds the C<urxvt> package/module is loaded. When
277	AnyEvent is loaded and asked to find a suitable event model, it will	492	AnyEvent is loaded and asked to find a suitable event model, it will
278	first check for the presence of urxvt.	493	first check for the presence of urxvt.
279		494
280	The class should prove implementations for all watcher types (see	495	The class should provide implementations for all watcher types (see
281	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>	496	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
282	(Source code) and so on for actual examples, use C<perldoc -m	497	(Source code) and so on for actual examples, use C<perldoc -m
283	AnyEvent::Impl::Glib> to see the sources).	498	AnyEvent::Impl::Glib> to see the sources).
284		499
285	The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)	500	The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
…		…
289	I<rxvt-unicode> distribution.	504	I<rxvt-unicode> distribution.
290		505
291	I<rxvt-unicode> also cheats a bit by not providing blocking access to	506	I<rxvt-unicode> also cheats a bit by not providing blocking access to
292	condition variables: code blocking while waiting for a condition will	507	condition variables: code blocking while waiting for a condition will
293	C<die>. This still works with most modules/usages, and blocking calls must	508	C<die>. This still works with most modules/usages, and blocking calls must
294	not be in an interactive appliation, so it makes sense.	509	not be in an interactive application, so it makes sense.
295		510
296	=head1 ENVIRONMENT VARIABLES	511	=head1 ENVIRONMENT VARIABLES
297		512
298	The following environment variables are used by this module:	513	The following environment variables are used by this module:
299		514

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.15 by root, Mon Oct 30 20:55:05 2006 UTC vs. Revision 1.41 by root, Mon Apr 7 19:23:59 2008 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.15 by root, Mon Oct 30 20:55:05 2006 UTC vs.
Revision 1.41 by root, Mon Apr 7 19:23:59 2008 UTC