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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.7 by root, Fri Dec 30 01:28:31 2005 UTC vs.
Revision 1.45 by root, Mon Apr 7 19:42:36 2008 UTC

…		…
1	=head1 NAME	1	=head1 NAME
2		2
3	AnyEvent - provide framework for multiple event loops	3	AnyEvent - provide framework for multiple event loops
4		4
5	Event, Coro, Glib, Tk - various supported event loops	5	Event, Coro, Glib, Tk, Perl - various supported event loops
6		6
7	=head1 SYNOPSIS	7	=head1 SYNOPSIS
8		8
9	use AnyEvent;	9	use AnyEvent;
10		10
11	my $w = AnyEvent->io (fh => ..., poll => "[rw]+", cb => sub {	11	my $w = AnyEvent->io (fh => $fh, poll => "r\|w", cb => sub {
12	my ($poll_got) = @_;
13	...	12	...
14	});	13	});
15
16	* only one io watcher per $fh and $poll type is allowed (i.e. on a socket
17	you can have one r + one w or one rw watcher, not any more (limitation by
18	Tk).
19
20	* the C<$poll_got> passed to the handler needs to be checked by looking
21	for single characters (e.g. with a regex), as it can contain more event
22	types than were requested (e.g. a 'w' watcher might generate 'rw' events,
23	limitation by Glib).
24
25	* AnyEvent will keep filehandles alive, so as long as the watcher exists,
26	the filehandle exists.
27		14
28	my $w = AnyEvent->timer (after => $seconds, cb => sub {	15	my $w = AnyEvent->timer (after => $seconds, cb => sub {
29	...	16	...
30	});	17	});
31		18
32	* io and time watchers get canceled whenever $w is destroyed, so keep a copy	19	my $w = AnyEvent->condvar; # stores wether a condition was flagged
33
34	* timers can only be used once and must be recreated for repeated
35	operation (limitation by Glib and Tk).
36
37	my $w = AnyEvent->condvar; # kind of main loop replacement
38	$w->wait; # enters main loop till $condvar gets ->broadcast	20	$w->wait; # enters "main loop" till $condvar gets ->broadcast
39	$w->broadcast; # wake up current and all future wait's	21	$w->broadcast; # wake up current and all future wait's
40		22
41	* condvars are used to give blocking behaviour when neccessary. Create	23	=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
42	a condvar for any "request" or "event" your module might create, C<<	24
43	->broadcast >> it when the event happens and provide a function that calls	25	Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
44	C<< ->wait >> for it. See the examples below.	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 can arguably be somewhat
		64	useful) and you want to force your users to the one and only event model
		65	your module forces on them, you should I<not> use this module.
		66
45		67
46	=head1 DESCRIPTION	68	=head1 DESCRIPTION
47		69
48	L<AnyEvent> provides an identical interface to multiple event loops. This	70	L<AnyEvent> provides an identical interface to multiple event loops. This
49	allows module authors to utilizy an event loop without forcing module	71	allows module authors to utilise an event loop without forcing module
50	users to use the same event loop (as only a single event loop can coexist	72	users to use the same event loop (as only a single event loop can coexist
51	peacefully at any one time).	73	peacefully at any one time).
52		74
53	The interface itself is vaguely similar but not identical to the Event	75	The interface itself is vaguely similar but not identical to the Event
54	module.	76	module.
56	On the first call of any method, the module tries to detect the currently	78	On the first call of any method, the module tries to detect the currently
57	loaded event loop by probing wether any of the following modules is	79	loaded event loop by probing wether any of the following modules is
58	loaded: L<Coro::Event>, L<Event>, L<Glib>, L<Tk>. The first one found is	80	loaded: L<Coro::Event>, L<Event>, L<Glib>, L<Tk>. The first one found is
59	used. If none is found, the module tries to load these modules in the	81	used. If none is found, the module tries to load these modules in the
60	order given. The first one that could be successfully loaded will be	82	order given. The first one that could be successfully loaded will be
61	used. If still none could be found, it will issue an error.	83	used. If still none could be found, AnyEvent will fall back to a pure-perl
		84	event loop, which is also not very efficient.
		85
		86	Because AnyEvent first checks for modules that are already loaded, loading
		87	an Event model explicitly before first using AnyEvent will likely make
		88	that model the default. For example:
		89
		90	use Tk;
		91	use AnyEvent;
		92
		93	# .. AnyEvent will likely default to Tk
		94
		95	The pure-perl implementation of AnyEvent is called
		96	C<AnyEvent::Impl::Perl>. Like other event modules you can load it
		97	explicitly.
		98
		99	=head1 WATCHERS
		100
		101	AnyEvent has the central concept of a I<watcher>, which is an object that
		102	stores relevant data for each kind of event you are waiting for, such as
		103	the callback to call, the filehandle to watch, etc.
		104
		105	These watchers are normal Perl objects with normal Perl lifetime. After
		106	creating a watcher it will immediately "watch" for events and invoke
		107	the callback. To disable the watcher you have to destroy it (e.g. by
		108	setting the variable that stores it to C<undef> or otherwise deleting all
		109	references to it).
		110
		111	All watchers are created by calling a method on the C<AnyEvent> class.
		112
		113	=head2 IO WATCHERS
		114
		115	You can create I/O watcher by calling the C<< AnyEvent->io >> method with
		116	the following mandatory arguments:
		117
		118	C<fh> the Perl I<filehandle> (not filedescriptor) to watch for
		119	events. C<poll> must be a string that is either C<r> or C<w>, that creates
		120	a watcher waiting for "r"eadable or "w"ritable events. C<cb> the callback
		121	to invoke everytime the filehandle becomes ready.
		122
		123	Only one io watcher per C<fh> and C<poll> combination is allowed (i.e. on
		124	a socket you can have one r + one w, not any more (limitation comes from
		125	Tk - if you are sure you are not using Tk this limitation is gone).
		126
		127	Filehandles will be kept alive, so as long as the watcher exists, the
		128	filehandle exists, too.
		129
		130	Example:
		131
		132	# wait for readability of STDIN, then read a line and disable the watcher
		133	my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
		134	chomp (my $input = <STDIN>);
		135	warn "read: $input\n";
		136	undef $w;
		137	});
		138
		139	=head2 TIME WATCHERS
		140
		141	You can create a time watcher by calling the C<< AnyEvent->timer >>
		142	method with the following mandatory arguments:
		143
		144	C<after> after how many seconds (fractions are supported) should the timer
		145	activate. C<cb> the callback to invoke.
		146
		147	The timer callback will be invoked at most once: if you want a repeating
		148	timer you have to create a new watcher (this is a limitation by both Tk
		149	and Glib).
		150
		151	Example:
		152
		153	# fire an event after 7.7 seconds
		154	my $w = AnyEvent->timer (after => 7.7, cb => sub {
		155	warn "timeout\n";
		156	});
		157
		158	# to cancel the timer:
		159	undef $w;
		160
		161	=head2 CONDITION WATCHERS
		162
		163	Condition watchers can be created by calling the C<< AnyEvent->condvar >>
		164	method without any arguments.
		165
		166	A condition watcher watches for a condition - precisely that the C<<
		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.
		174
		175	The watcher has only two methods:
62		176
63	=over 4	177	=over 4
64		178
		179	=item $cv->wait
		180
		181	Wait (blocking if necessary) until the C<< ->broadcast >> method has been
		182	called on c<$cv>, while servicing other watchers normally.
		183
		184	Not all event models support a blocking wait - some die in that case, so
		185	if you are using this from a module, never require a blocking wait, but
		186	let the caller decide wether the call will block or not (for example,
		187	by coupling condition variables with some kind of request results and
		188	supporting callbacks so the caller knows that getting the result will not
		189	block, while still suppporting blockign waits if the caller so desires).
		190
		191	You can only wait once on a condition - additional calls will return
		192	immediately.
		193
		194	=item $cv->broadcast
		195
		196	Flag the condition as ready - a running C<< ->wait >> and all further
		197	calls to C<wait> will return after this method has been called. If nobody
		198	is waiting the broadcast will be remembered..
		199
		200	Example:
		201
		202	# wait till the result is ready
		203	my $result_ready = AnyEvent->condvar;
		204
		205	# do something such as adding a timer
		206	# or socket watcher the calls $result_ready->broadcast
		207	# when the "result" is ready.
		208
		209	$result_ready->wait;
		210
		211	=back
		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
		239	=head1 GLOBALS
		240
		241	=over 4
		242
		243	=item $AnyEvent::MODEL
		244
		245	Contains C<undef> until the first watcher is being created. Then it
		246	contains the event model that is being used, which is the name of the
		247	Perl class implementing the model. This class is usually one of the
		248	C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
		249	AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
		250
		251	The known classes so far are:
		252
		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.
		256	AnyEvent::Impl::Event based on Event, also second best choice :)
		257	AnyEvent::Impl::Glib based on Glib, second-best choice.
		258	AnyEvent::Impl::Tk based on Tk, very bad choice.
		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.
		266
		267	=back
		268
		269	=head1 WHAT TO DO IN A MODULE
		270
		271	As a module author, you should "use AnyEvent" and call AnyEvent methods
		272	freely, but you should not load a specific event module or rely on it.
		273
		274	Be careful when you create watchers in the module body - Anyevent will
		275	decide which event module to use as soon as the first method is called, so
		276	by calling AnyEvent in your module body you force the user of your module
		277	to load the event module first.
		278
		279	=head1 WHAT TO DO IN THE MAIN PROGRAM
		280
		281	There will always be a single main program - the only place that should
		282	dictate which event model to use.
		283
		284	If it doesn't care, it can just "use AnyEvent" and use it itself, or not
		285	do anything special and let AnyEvent decide which implementation to chose.
		286
		287	If the main program relies on a specific event model (for example, in Gtk2
		288	programs you have to rely on either Glib or Glib::Event), you should load
		289	it before loading AnyEvent or any module that uses it, generally, as early
		290	as possible. The reason is that modules might create watchers when they
		291	are loaded, and AnyEvent will decide on the event model to use as soon as
		292	it creates watchers, and it might chose the wrong one unless you load the
		293	correct one yourself.
		294
		295	You can chose to use a rather inefficient pure-perl implementation by
		296	loading the C<AnyEvent::Impl::Perl> module, but letting AnyEvent chose is
		297	generally better.
		298
65	=cut	299	=cut
66		300
67	package AnyEvent;	301	package AnyEvent;
68		302
69	no warnings;	303	no warnings;
70	use strict 'vars';	304	use strict;
		305
71	use Carp;	306	use Carp;
72		307
73	our $VERSION = '0.4';	308	our $VERSION = '3.0';
74	our $MODEL;	309	our $MODEL;
75		310
76	our $AUTOLOAD;	311	our $AUTOLOAD;
77	our @ISA;	312	our @ISA;
78		313
79	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;	314	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
80		315
		316	our @REGISTRY;
		317
81	my @models = (	318	my @models = (
82	[Coro => Coro::Event::],	319	[Coro::EV:: => AnyEvent::Impl::CoroEV::],
83	[Event => Event::],	320	[EV:: => AnyEvent::Impl::EV::],
84	[Glib => Glib::],	321	[Coro::Event:: => AnyEvent::Impl::CoroEvent::],
85	[Tk => Tk::],	322	[Event:: => AnyEvent::Impl::Event::],
		323	[Glib:: => AnyEvent::Impl::Glib::],
		324	[Tk:: => AnyEvent::Impl::Tk::],
		325	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
86	);	326	);
87		327
88	our %method = map +($_ => 1), qw(io timer condvar broadcast wait cancel DESTROY);	328	our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY);
89		329
90	sub AUTOLOAD {	330	sub detect() {
91	$AUTOLOAD =~ s/.*://;
92
93	$method{$AUTOLOAD}
94	or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
95
96	unless ($MODEL) {	331	unless ($MODEL) {
		332	no strict 'refs';
		333
97	# check for already loaded models	334	# check for already loaded models
98	for (@models) {	335	for (@REGISTRY, @models) {
99	my ($model, $package) = @$_;	336	my ($package, $model) = @$_;
100	if (${"$package\::VERSION"} > 0) {	337	if (${"$package\::VERSION"} > 0) {
101	eval "require AnyEvent::Impl::$model";	338	if (eval "require $model") {
		339	$MODEL = $model;
102	warn "AnyEvent: found model '$model', using it.\n" if $MODEL && $verbose > 1;	340	warn "AnyEvent: found model '$model', using it.\n" if $verbose > 1;
103	last if $MODEL;	341	last;
		342	}
104	}	343	}
105	}	344	}
106		345
107	unless ($MODEL) {	346	unless ($MODEL) {
108	# try to load a model	347	# try to load a model
109		348
110	for (@models) {	349	for (@REGISTRY, @models) {
111	my ($model, $package) = @$_;	350	my ($package, $model) = @$_;
112	eval "require AnyEvent::Impl::$model";	351	if (eval "require $package"
		352	and ${"$package\::VERSION"} > 0
		353	and eval "require $model") {
		354	$MODEL = $model;
113	warn "AnyEvent: autprobed and loaded model '$model', using it.\n" if $MODEL && $verbose > 1;	355	warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
114	last if $MODEL;	356	last;
		357	}
115	}	358	}
116		359
117	$MODEL	360	$MODEL
118	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.";
119	}	362	}
		363
		364	unshift @ISA, $MODEL;
		365	push @{"$MODEL\::ISA"}, "AnyEvent::Base";
120	}	366	}
121		367
122	@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;
123		378
124	my $class = shift;	379	my $class = shift;
125	$class->$AUTOLOAD (@_);	380	$class->$func (@_);
126	}	381	}
127		382
128	=back	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;
		478	}
		479
		480	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
		481
		482	If you need to support another event library which isn't directly
		483	supported by AnyEvent, you can supply your own interface to it by
		484	pushing, before the first watcher gets created, the package name of
		485	the event module and the package name of the interface to use onto
		486	C<@AnyEvent::REGISTRY>. You can do that before and even without loading
		487	AnyEvent.
		488
		489	Example:
		490
		491	push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
		492
		493	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
		494	package/class when it finds the C<urxvt> package/module is loaded. When
		495	AnyEvent is loaded and asked to find a suitable event model, it will
		496	first check for the presence of urxvt.
		497
		498	The class should provide implementations for all watcher types (see
		499	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
		500	(Source code) and so on for actual examples, use C<perldoc -m
		501	AnyEvent::Impl::Glib> to see the sources).
		502
		503	The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
		504	uses the above line as-is. An interface isn't included in AnyEvent
		505	because it doesn't make sense outside the embedded interpreter inside
		506	I<rxvt-unicode>, and it is updated and maintained as part of the
		507	I<rxvt-unicode> distribution.
		508
		509	I<rxvt-unicode> also cheats a bit by not providing blocking access to
		510	condition variables: code blocking while waiting for a condition will
		511	C<die>. This still works with most modules/usages, and blocking calls must
		512	not be in an interactive application, so it makes sense.
129		513
130	=head1 ENVIRONMENT VARIABLES	514	=head1 ENVIRONMENT VARIABLES
131		515
132	The following environment variables are used by this module:	516	The following environment variables are used by this module:
133		517

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.7 by root, Fri Dec 30 01:28:31 2005 UTC vs. Revision 1.45 by root, Mon Apr 7 19:42:36 2008 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.7 by root, Fri Dec 30 01:28:31 2005 UTC vs.
Revision 1.45 by root, Mon Apr 7 19:42:36 2008 UTC