[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.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
…		…
154	# do something such as adding a timer	201	# do something such as adding a timer
155	# or socket watcher the calls $result_ready->broadcast	202	# or socket watcher the calls $result_ready->broadcast
156	# when the "result" is ready.	203	# when the "result" is ready.
157		204
158	$result_ready->wait;	205	$result_ready->wait;
		206
		207	=back
		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
		235	=head1 GLOBALS
		236
		237	=over 4
		238
		239	=item $AnyEvent::MODEL
		240
		241	Contains C<undef> until the first watcher is being created. Then it
		242	contains the event model that is being used, which is the name of the
		243	Perl class implementing the model. This class is usually one of the
		244	C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
		245	AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
		246
		247	The known classes so far are:
		248
		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.
		252	AnyEvent::Impl::Event based on Event, also second best choice :)
		253	AnyEvent::Impl::Glib based on Glib, second-best choice.
		254	AnyEvent::Impl::Tk based on Tk, very bad choice.
		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.
159		262
160	=back	263	=back
161		264
162	=head1 WHAT TO DO IN A MODULE	265	=head1 WHAT TO DO IN A MODULE
163		266
…		…
192	=cut	295	=cut
193		296
194	package AnyEvent;	297	package AnyEvent;
195		298
196	no warnings;	299	no warnings;
197	use strict 'vars';	300	use strict;
		301
198	use Carp;	302	use Carp;
199		303
200	our $VERSION = '2.0';	304	our $VERSION = '3.0';
201	our $MODEL;	305	our $MODEL;
202		306
203	our $AUTOLOAD;	307	our $AUTOLOAD;
204	our @ISA;	308	our @ISA;
205		309
206	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;	310	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
207		311
208	our @REGISTRY;	312	our @REGISTRY;
209		313
210	my @models = (	314	my @models = (
		315	[Coro::EV:: => AnyEvent::Impl::CoroEV::],
		316	[EV:: => AnyEvent::Impl::EV::],
211	[Coro::Event:: => AnyEvent::Impl::Coro::],	317	[Coro::Event:: => AnyEvent::Impl::CoroEvent::],
212	[Event:: => AnyEvent::Impl::Event::],	318	[Event:: => AnyEvent::Impl::Event::],
213	[Glib:: => AnyEvent::Impl::Glib::],	319	[Glib:: => AnyEvent::Impl::Glib::],
214	[Tk:: => AnyEvent::Impl::Tk::],	320	[Tk:: => AnyEvent::Impl::Tk::],
215	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],	321	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
216	);	322	);
217		323
218	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);
219		325
220	sub AUTOLOAD {	326	sub detect() {
221	$AUTOLOAD =~ s/.*://;
222
223	$method{$AUTOLOAD}
224	or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
225
226	unless ($MODEL) {	327	unless ($MODEL) {
		328	no strict 'refs';
		329
227	# check for already loaded models	330	# check for already loaded models
228	for (@REGISTRY, @models) {	331	for (@REGISTRY, @models) {
229	my ($package, $model) = @$_;	332	my ($package, $model) = @$_;
230	if (${"$package\::VERSION"} > 0) {	333	if (${"$package\::VERSION"} > 0) {
231	if (eval "require $model") {	334	if (eval "require $model") {
…		…
239	unless ($MODEL) {	342	unless ($MODEL) {
240	# try to load a model	343	# try to load a model
241		344
242	for (@REGISTRY, @models) {	345	for (@REGISTRY, @models) {
243	my ($package, $model) = @$_;	346	my ($package, $model) = @$_;
		347	if (eval "require $package"
		348	and ${"$package\::VERSION"} > 0
244	if (eval "require $model") {	349	and eval "require $model") {
245	$MODEL = $model;	350	$MODEL = $model;
246	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;
247	last;	352	last;
248	}	353	}
249	}	354	}
250		355
251	$MODEL	356	$MODEL
252	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.";
253	}	358	}
		359
		360	unshift @ISA, $MODEL;
		361	push @{"$MODEL\::ISA"}, "AnyEvent::Base";
254	}	362	}
255		363
256	@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;
257		374
258	my $class = shift;	375	my $class = shift;
259	$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;
260	}	474	}
261		475
262	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE	476	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
263		477
264	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
…		…
275	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>	489	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
276	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
277	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
278	first check for the presence of urxvt.	492	first check for the presence of urxvt.
279		493
280	The class should prove implementations for all watcher types (see	494	The class should provide implementations for all watcher types (see
281	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>	495	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
282	(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
283	AnyEvent::Impl::Glib> to see the sources).	497	AnyEvent::Impl::Glib> to see the sources).
284		498
285	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)
…		…
289	I<rxvt-unicode> distribution.	503	I<rxvt-unicode> distribution.
290		504
291	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
292	condition variables: code blocking while waiting for a condition will	506	condition variables: code blocking while waiting for a condition will
293	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
294	not be in an interactive appliation, so it makes sense.	508	not be in an interactive application, so it makes sense.
295		509
296	=head1 ENVIRONMENT VARIABLES	510	=head1 ENVIRONMENT VARIABLES
297		511
298	The following environment variables are used by this module:	512	The following environment variables are used by this module:
299		513

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