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

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

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.6 by root, Mon Dec 19 17:03:29 2005 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.6 by root, Mon Dec 19 17:03:29 2005 UTC vs.
Revision 1.42 by root, Mon Apr 7 19:40:12 2008 UTC