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

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.42 by root, Mon Apr 7 19:40:12 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.42 by root, Mon Apr 7 19:40:12 2008 UTC