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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.16 by root, Sun Nov 5 01:08:16 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
…		…
157		205
158	$result_ready->wait;	206	$result_ready->wait;
159		207
160	=back	208	=back
161		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
162	=head1 GLOBALS	236	=head1 GLOBALS
163		237
164	=over 4	238	=over 4
165		239
166	=item $AnyEvent::MODEL	240	=item $AnyEvent::MODEL
…		…
171	C<AnyEvent::Impl:xxx> modules, but can be any other class in the case	245	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>).	246	AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
173		247
174	The known classes so far are:	248	The known classes so far are:
175		249
176	AnyEvent::Impl::Coro based on Coro::Event, best choise.	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.
177	AnyEvent::Impl::Event based on Event, also best choice :)	253	AnyEvent::Impl::Event based on Event, also second best choice :)
178	AnyEvent::Impl::Glib based on Glib, second-best choice.	254	AnyEvent::Impl::Glib based on Glib, second-best choice.
179	AnyEvent::Impl::Tk based on Tk, very bad choice.	255	AnyEvent::Impl::Tk based on Tk, very bad choice.
180	AnyEvent::Impl::Perl pure-perl implementation, inefficient.	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.
181		263
182	=back	264	=back
183		265
184	=head1 WHAT TO DO IN A MODULE	266	=head1 WHAT TO DO IN A MODULE
185		267
…		…
214	=cut	296	=cut
215		297
216	package AnyEvent;	298	package AnyEvent;
217		299
218	no warnings;	300	no warnings;
219	use strict 'vars';	301	use strict;
		302
220	use Carp;	303	use Carp;
221		304
222	our $VERSION = '2.0';	305	our $VERSION = '3.0';
223	our $MODEL;	306	our $MODEL;
224		307
225	our $AUTOLOAD;	308	our $AUTOLOAD;
226	our @ISA;	309	our @ISA;
227		310
228	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;	311	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
229		312
230	our @REGISTRY;	313	our @REGISTRY;
231		314
232	my @models = (	315	my @models = (
		316	[Coro::EV:: => AnyEvent::Impl::CoroEV::],
		317	[EV:: => AnyEvent::Impl::EV::],
233	[Coro::Event:: => AnyEvent::Impl::Coro::],	318	[Coro::Event:: => AnyEvent::Impl::CoroEvent::],
234	[Event:: => AnyEvent::Impl::Event::],	319	[Event:: => AnyEvent::Impl::Event::],
235	[Glib:: => AnyEvent::Impl::Glib::],	320	[Glib:: => AnyEvent::Impl::Glib::],
236	[Tk:: => AnyEvent::Impl::Tk::],	321	[Tk:: => AnyEvent::Impl::Tk::],
237	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],	322	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
238	);	323	);
239		324
240	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);
241		326
242	sub AUTOLOAD {	327	sub detect() {
243	$AUTOLOAD =~ s/.*://;
244
245	$method{$AUTOLOAD}
246	or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
247
248	unless ($MODEL) {	328	unless ($MODEL) {
		329	no strict 'refs';
		330
249	# check for already loaded models	331	# check for already loaded models
250	for (@REGISTRY, @models) {	332	for (@REGISTRY, @models) {
251	my ($package, $model) = @$_;	333	my ($package, $model) = @$_;
252	if (${"$package\::VERSION"} > 0) {	334	if (${"$package\::VERSION"} > 0) {
253	if (eval "require $model") {	335	if (eval "require $model") {
…		…
261	unless ($MODEL) {	343	unless ($MODEL) {
262	# try to load a model	344	# try to load a model
263		345
264	for (@REGISTRY, @models) {	346	for (@REGISTRY, @models) {
265	my ($package, $model) = @$_;	347	my ($package, $model) = @$_;
		348	if (eval "require $package"
		349	and ${"$package\::VERSION"} > 0
266	if (eval "require $model") {	350	and eval "require $model") {
267	$MODEL = $model;	351	$MODEL = $model;
268	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;
269	last;	353	last;
270	}	354	}
271	}	355	}
272		356
273	$MODEL	357	$MODEL
274	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.";
275	}	359	}
		360
		361	unshift @ISA, $MODEL;
		362	push @{"$MODEL\::ISA"}, "AnyEvent::Base";
276	}	363	}
277		364
278	@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;
279		375
280	my $class = shift;	376	my $class = shift;
281	$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;
282	}	475	}
283		476
284	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE	477	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
285		478
286	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
…		…
297	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>	490	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
298	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
299	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
300	first check for the presence of urxvt.	493	first check for the presence of urxvt.
301		494
302	The class should prove implementations for all watcher types (see	495	The class should provide implementations for all watcher types (see
303	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>	496	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
304	(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
305	AnyEvent::Impl::Glib> to see the sources).	498	AnyEvent::Impl::Glib> to see the sources).
306		499
307	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)
…		…
311	I<rxvt-unicode> distribution.	504	I<rxvt-unicode> distribution.
312		505
313	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
314	condition variables: code blocking while waiting for a condition will	507	condition variables: code blocking while waiting for a condition will
315	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
316	not be in an interactive appliation, so it makes sense.	509	not be in an interactive application, so it makes sense.
317		510
318	=head1 ENVIRONMENT VARIABLES	511	=head1 ENVIRONMENT VARIABLES
319		512
320	The following environment variables are used by this module:	513	The following environment variables are used by this module:
321		514

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.16 by root, Sun Nov 5 01:08:16 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.16 by root, Sun Nov 5 01:08:16 2006 UTC vs.
Revision 1.41 by root, Mon Apr 7 19:23:59 2008 UTC