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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.18 by root, Sun Dec 10 21:33:33 2006 UTC vs.
Revision 1.44 by root, Mon Apr 7 19:42:18 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 is arguably somewhat useful
		64	in many cases) and you want to force your users to the one and only event
		65	model your module forces on them, 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.
		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.
123		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
…		…
157		208
158	$result_ready->wait;	209	$result_ready->wait;
159		210
160	=back	211	=back
161		212
		213	=head2 SIGNAL WATCHERS
		214
		215	You can listen for signals using a signal watcher, C<signal> is the signal
		216	I<name> without any C<SIG> prefix. Multiple signals events can be clumped
		217	together into one callback invocation, and callback invocation might or
		218	might not be asynchronous.
		219
		220	These watchers might use C<%SIG>, so programs overwriting those signals
		221	directly will likely not work correctly.
		222
		223	Example: exit on SIGINT
		224
		225	my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
		226
		227	=head2 CHILD PROCESS WATCHERS
		228
		229	You can also listen for the status of a child process specified by the
		230	C<pid> argument (or any child if the pid argument is 0). The watcher will
		231	trigger as often as status change for the child are received. This works
		232	by installing a signal handler for C<SIGCHLD>. The callback will be called with
		233	the pid and exit status (as returned by waitpid).
		234
		235	Example: wait for pid 1333
		236
		237	my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
		238
162	=head1 GLOBALS	239	=head1 GLOBALS
163		240
164	=over 4	241	=over 4
165		242
166	=item $AnyEvent::MODEL	243	=item $AnyEvent::MODEL
…		…
171	C<AnyEvent::Impl:xxx> modules, but can be any other class in the case	248	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>).	249	AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
173		250
174	The known classes so far are:	251	The known classes so far are:
175		252
176	AnyEvent::Impl::Coro based on Coro::Event, best choise.	253	AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
		254	AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
		255	AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
177	AnyEvent::Impl::Event based on Event, also best choice :)	256	AnyEvent::Impl::Event based on Event, also second best choice :)
178	AnyEvent::Impl::Glib based on Glib, second-best choice.	257	AnyEvent::Impl::Glib based on Glib, second-best choice.
179	AnyEvent::Impl::Tk based on Tk, very bad choice.	258	AnyEvent::Impl::Tk based on Tk, very bad choice.
180	AnyEvent::Impl::Perl pure-perl implementation, inefficient.	259	AnyEvent::Impl::Perl pure-perl implementation, inefficient.
		260
		261	=item AnyEvent::detect
		262
		263	Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
		264	necessary. You should only call this function right before you would have
		265	created an AnyEvent watcher anyway, that is, very late at runtime.
181		266
182	=back	267	=back
183		268
184	=head1 WHAT TO DO IN A MODULE	269	=head1 WHAT TO DO IN A MODULE
185		270
…		…
214	=cut	299	=cut
215		300
216	package AnyEvent;	301	package AnyEvent;
217		302
218	no warnings;	303	no warnings;
219	use strict 'vars';	304	use strict;
		305
220	use Carp;	306	use Carp;
221		307
222	our $VERSION = '2.1';	308	our $VERSION = '3.0';
223	our $MODEL;	309	our $MODEL;
224		310
225	our $AUTOLOAD;	311	our $AUTOLOAD;
226	our @ISA;	312	our @ISA;
227		313
228	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;	314	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
229		315
230	our @REGISTRY;	316	our @REGISTRY;
231		317
232	my @models = (	318	my @models = (
		319	[Coro::EV:: => AnyEvent::Impl::CoroEV::],
		320	[EV:: => AnyEvent::Impl::EV::],
233	[Coro::Event:: => AnyEvent::Impl::Coro::],	321	[Coro::Event:: => AnyEvent::Impl::CoroEvent::],
234	[Event:: => AnyEvent::Impl::Event::],	322	[Event:: => AnyEvent::Impl::Event::],
235	[Glib:: => AnyEvent::Impl::Glib::],	323	[Glib:: => AnyEvent::Impl::Glib::],
236	[Tk:: => AnyEvent::Impl::Tk::],	324	[Tk:: => AnyEvent::Impl::Tk::],
237	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],	325	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
238	);	326	);
239		327
240	our %method = map +($_ => 1), qw(io timer condvar broadcast wait DESTROY);	328	our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY);
241		329
242	sub AUTOLOAD {	330	sub detect() {
243	(my $func = $AUTOLOAD) =~ s/.*://;
244
245	$method{$func}
246	or croak "$func: not a valid method for AnyEvent objects";
247
248	unless ($MODEL) {	331	unless ($MODEL) {
		332	no strict 'refs';
		333
249	# check for already loaded models	334	# check for already loaded models
250	for (@REGISTRY, @models) {	335	for (@REGISTRY, @models) {
251	my ($package, $model) = @$_;	336	my ($package, $model) = @$_;
252	if (${"$package\::VERSION"} > 0) {	337	if (${"$package\::VERSION"} > 0) {
253	if (eval "require $model") {	338	if (eval "require $model") {
…		…
261	unless ($MODEL) {	346	unless ($MODEL) {
262	# try to load a model	347	# try to load a model
263		348
264	for (@REGISTRY, @models) {	349	for (@REGISTRY, @models) {
265	my ($package, $model) = @$_;	350	my ($package, $model) = @$_;
		351	if (eval "require $package"
		352	and ${"$package\::VERSION"} > 0
266	if (eval "require $model") {	353	and eval "require $model") {
267	$MODEL = $model;	354	$MODEL = $model;
268	warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;	355	warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
269	last;	356	last;
270	}	357	}
271	}	358	}
272		359
273	$MODEL	360	$MODEL
274	or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Coro, Event, Glib or Tk.";	361	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	}	362	}
		363
		364	unshift @ISA, $MODEL;
		365	push @{"$MODEL\::ISA"}, "AnyEvent::Base";
276	}	366	}
277		367
278	@ISA = $MODEL;	368	$MODEL
		369	}
		370
		371	sub AUTOLOAD {
		372	(my $func = $AUTOLOAD) =~ s/.*://;
		373
		374	$method{$func}
		375	or croak "$func: not a valid method for AnyEvent objects";
		376
		377	detect unless $MODEL;
279		378
280	my $class = shift;	379	my $class = shift;
281	$class->$func (@_);	380	$class->$func (@_);
		381	}
		382
		383	package AnyEvent::Base;
		384
		385	# default implementation for ->condvar, ->wait, ->broadcast
		386
		387	sub condvar {
		388	bless \my $flag, "AnyEvent::Base::CondVar"
		389	}
		390
		391	sub AnyEvent::Base::CondVar::broadcast {
		392	${$_[0]}++;
		393	}
		394
		395	sub AnyEvent::Base::CondVar::wait {
		396	AnyEvent->one_event while !${$_[0]};
		397	}
		398
		399	# default implementation for ->signal
		400
		401	our %SIG_CB;
		402
		403	sub signal {
		404	my (undef, %arg) = @_;
		405
		406	my $signal = uc $arg{signal}
		407	or Carp::croak "required option 'signal' is missing";
		408
		409	$SIG_CB{$signal}{$arg{cb}} = $arg{cb};
		410	$SIG{$signal} \|\|= sub {
		411	$_->() for values %{ $SIG_CB{$signal} \|\| {} };
		412	};
		413
		414	bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
		415	}
		416
		417	sub AnyEvent::Base::Signal::DESTROY {
		418	my ($signal, $cb) = @{$_[0]};
		419
		420	delete $SIG_CB{$signal}{$cb};
		421
		422	$SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };
		423	}
		424
		425	# default implementation for ->child
		426
		427	our %PID_CB;
		428	our $CHLD_W;
		429	our $CHLD_DELAY_W;
		430	our $PID_IDLE;
		431	our $WNOHANG;
		432
		433	sub _child_wait {
		434	while (0 < (my $pid = waitpid -1, $WNOHANG)) {
		435	$_->($pid, $?) for (values %{ $PID_CB{$pid} \|\| {} }),
		436	(values %{ $PID_CB{0} \|\| {} });
		437	}
		438
		439	undef $PID_IDLE;
		440	}
		441
		442	sub _sigchld {
		443	# make sure we deliver these changes "synchronous" with the event loop.
		444	$CHLD_DELAY_W \|\|= AnyEvent->timer (after => 0, cb => sub {
		445	undef $CHLD_DELAY_W;
		446	&_child_wait;
		447	});
		448	}
		449
		450	sub child {
		451	my (undef, %arg) = @_;
		452
		453	defined (my $pid = $arg{pid} + 0)
		454	or Carp::croak "required option 'pid' is missing";
		455
		456	$PID_CB{$pid}{$arg{cb}} = $arg{cb};
		457
		458	unless ($WNOHANG) {
		459	$WNOHANG = eval { require POSIX; &POSIX::WNOHANG } \|\| 1;
		460	}
		461
		462	unless ($CHLD_W) {
		463	$CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
		464	# child could be a zombie already, so make at least one round
		465	&_sigchld;
		466	}
		467
		468	bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
		469	}
		470
		471	sub AnyEvent::Base::Child::DESTROY {
		472	my ($pid, $cb) = @{$_[0]};
		473
		474	delete $PID_CB{$pid}{$cb};
		475	delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
		476
		477	undef $CHLD_W unless keys %PID_CB;
282	}	478	}
283		479
284	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE	480	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
285		481
286	If you need to support another event library which isn't directly	482	If you need to support another event library which isn't directly
…		…
297	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>	493	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
298	package/class when it finds the C<urxvt> package/module is loaded. When	494	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	495	AnyEvent is loaded and asked to find a suitable event model, it will
300	first check for the presence of urxvt.	496	first check for the presence of urxvt.
301		497
302	The class should prove implementations for all watcher types (see	498	The class should provide implementations for all watcher types (see
303	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>	499	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
304	(Source code) and so on for actual examples, use C<perldoc -m	500	(Source code) and so on for actual examples, use C<perldoc -m
305	AnyEvent::Impl::Glib> to see the sources).	501	AnyEvent::Impl::Glib> to see the sources).
306		502
307	The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)	503	The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
…		…
311	I<rxvt-unicode> distribution.	507	I<rxvt-unicode> distribution.
312		508
313	I<rxvt-unicode> also cheats a bit by not providing blocking access to	509	I<rxvt-unicode> also cheats a bit by not providing blocking access to
314	condition variables: code blocking while waiting for a condition will	510	condition variables: code blocking while waiting for a condition will
315	C<die>. This still works with most modules/usages, and blocking calls must	511	C<die>. This still works with most modules/usages, and blocking calls must
316	not be in an interactive appliation, so it makes sense.	512	not be in an interactive application, so it makes sense.
317		513
318	=head1 ENVIRONMENT VARIABLES	514	=head1 ENVIRONMENT VARIABLES
319		515
320	The following environment variables are used by this module:	516	The following environment variables are used by this module:
321		517

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.18 by root, Sun Dec 10 21:33:33 2006 UTC vs. Revision 1.44 by root, Mon Apr 7 19:42:18 2008 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.18 by root, Sun Dec 10 21:33:33 2006 UTC vs.
Revision 1.44 by root, Mon Apr 7 19:42:18 2008 UTC