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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.5 by root, Sun Dec 4 09:44:32 2005 UTC vs.
Revision 1.28 by root, Sat Oct 27 15:10:09 2007 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
36	a condvar for any "request" or "event" your module might create, C<<
37	->broadcast >> it when the event happens and provide a function that calls
38	C<< ->wait >> for it. See the examples below.
39
40	=head1 DESCRIPTION	23	=head1 DESCRIPTION
41		24
42	L<AnyEvent> provides an identical interface to multiple event loops. This	25	L<AnyEvent> provides an identical interface to multiple event loops. This
43	allows module authors to utilizy an event loop without forcing module	26	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	27	users to use the same event loop (as only a single event loop can coexist
45	peacefully at any one time).	28	peacefully at any one time).
46		29
47	The interface itself is vaguely similar but not identical to the Event	30	The interface itself is vaguely similar but not identical to the Event
48	module.	31	module.
50	On the first call of any method, the module tries to detect the currently	33	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	34	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	35	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	36	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	37	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.	38	used. If still none could be found, AnyEvent will fall back to a pure-perl
		39	event loop, which is also not very efficient.
		40
		41	Because AnyEvent first checks for modules that are already loaded, loading
		42	an Event model explicitly before first using AnyEvent will likely make
		43	that model the default. For example:
		44
		45	use Tk;
		46	use AnyEvent;
		47
		48	# .. AnyEvent will likely default to Tk
		49
		50	The pure-perl implementation of AnyEvent is called
		51	C<AnyEvent::Impl::Perl>. Like other event modules you can load it
		52	explicitly.
		53
		54	=head1 WATCHERS
		55
		56	AnyEvent has the central concept of a I<watcher>, which is an object that
		57	stores relevant data for each kind of event you are waiting for, such as
		58	the callback to call, the filehandle to watch, etc.
		59
		60	These watchers are normal Perl objects with normal Perl lifetime. After
		61	creating a watcher it will immediately "watch" for events and invoke
		62	the callback. To disable the watcher you have to destroy it (e.g. by
		63	setting the variable that stores it to C<undef> or otherwise deleting all
		64	references to it).
		65
		66	All watchers are created by calling a method on the C<AnyEvent> class.
		67
		68	=head2 IO WATCHERS
		69
		70	You can create I/O watcher by calling the C<< AnyEvent->io >> method with
		71	the following mandatory arguments:
		72
		73	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
		75	a watcher waiting for "r"eadable or "w"ritable events. C<cb> teh callback
		76	to invoke everytime the filehandle becomes ready.
		77
		78	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
		80	Tk - if you are sure you are not using Tk this limitation is gone).
		81
		82	Filehandles will be kept alive, so as long as the watcher exists, the
		83	filehandle exists, too.
		84
		85	Example:
		86
		87	# wait for readability of STDIN, then read a line and disable the watcher
		88	my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
		89	chomp (my $input = <STDIN>);
		90	warn "read: $input\n";
		91	undef $w;
		92	});
		93
		94	=head2 TIME WATCHERS
		95
		96	You can create a time watcher by calling the C<< AnyEvent->timer >>
		97	method with the following mandatory arguments:
		98
		99	C<after> after how many seconds (fractions are supported) should the timer
		100	activate. C<cb> the callback to invoke.
		101
		102	The timer callback will be invoked at most once: if you want a repeating
		103	timer you have to create a new watcher (this is a limitation by both Tk
		104	and Glib).
		105
		106	Example:
		107
		108	# fire an event after 7.7 seconds
		109	my $w = AnyEvent->timer (after => 7.7, cb => sub {
		110	warn "timeout\n";
		111	});
		112
		113	# to cancel the timer:
		114	undef $w
		115
		116	=head2 CONDITION WATCHERS
		117
		118	Condition watchers can be created by calling the C<< AnyEvent->condvar >>
		119	method without any arguments.
		120
		121	A condition watcher watches for a condition - precisely that the C<<
		122	->broadcast >> method has been called.
		123
		124	The watcher has only two methods:
56		125
57	=over 4	126	=over 4
58		127
		128	=item $cv->wait
		129
		130	Wait (blocking if necessary) until the C<< ->broadcast >> method has been
		131	called on c<$cv>, while servicing other watchers normally.
		132
		133	Not all event models support a blocking wait - some die in that case, so
		134	if you are using this from a module, never require a blocking wait, but
		135	let the caller decide wether the call will block or not (for example,
		136	by coupling condition variables with some kind of request results and
		137	supporting callbacks so the caller knows that getting the result will not
		138	block, while still suppporting blockign waits if the caller so desires).
		139
		140	You can only wait once on a condition - additional calls will return
		141	immediately.
		142
		143	=item $cv->broadcast
		144
		145	Flag the condition as ready - a running C<< ->wait >> and all further
		146	calls to C<wait> will return after this method has been called. If nobody
		147	is waiting the broadcast will be remembered..
		148
		149	Example:
		150
		151	# wait till the result is ready
		152	my $result_ready = AnyEvent->condvar;
		153
		154	# do something such as adding a timer
		155	# or socket watcher the calls $result_ready->broadcast
		156	# when the "result" is ready.
		157
		158	$result_ready->wait;
		159
		160	=back
		161
		162	=head2 SIGNAL WATCHERS
		163
		164	You can listen for signals using a signal watcher, C<signal> is the signal
		165	I<name> without any C<SIG> prefix. Multiple signals events can be clumped
		166	together into one callback invocation, and callback invocation might or
		167	might not be asynchronous.
		168
		169	These watchers might use C<%SIG>, so programs overwriting those signals
		170	directly will likely not work correctly.
		171
		172	Example: exit on SIGINT
		173
		174	my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
		175
		176	=head2 CHILD PROCESS WATCHERS
		177
		178	You can also listen for the status of a child process specified by the
		179	C<pid> argument. The watcher will only trigger once. This works by
		180	installing a signal handler for C<SIGCHLD>.
		181
		182	Example: wait for pid 1333
		183
		184	my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
		185
		186	=head1 GLOBALS
		187
		188	=over 4
		189
		190	=item $AnyEvent::MODEL
		191
		192	Contains C<undef> until the first watcher is being created. Then it
		193	contains the event model that is being used, which is the name of the
		194	Perl class implementing the model. This class is usually one of the
		195	C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
		196	AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
		197
		198	The known classes so far are:
		199
		200	AnyEvent::Impl::Coro based on Coro::Event, best choice.
		201	EV::AnyEvent based on EV (an interface to libevent)
		202	AnyEvent::Impl::Event based on Event, also best choice :)
		203	AnyEvent::Impl::Glib based on Glib, second-best choice.
		204	AnyEvent::Impl::Tk based on Tk, very bad choice.
		205	AnyEvent::Impl::Perl pure-perl implementation, inefficient.
		206
		207	=item AnyEvent::detect
		208
		209	Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
		210	necessary. You should only call this function right before you would have
		211	created an AnyEvent watcher anyway, that is, very late at runtime.
		212
		213	=back
		214
		215	=head1 WHAT TO DO IN A MODULE
		216
		217	As a module author, you should "use AnyEvent" and call AnyEvent methods
		218	freely, but you should not load a specific event module or rely on it.
		219
		220	Be careful when you create watchers in the module body - Anyevent will
		221	decide which event module to use as soon as the first method is called, so
		222	by calling AnyEvent in your module body you force the user of your module
		223	to load the event module first.
		224
		225	=head1 WHAT TO DO IN THE MAIN PROGRAM
		226
		227	There will always be a single main program - the only place that should
		228	dictate which event model to use.
		229
		230	If it doesn't care, it can just "use AnyEvent" and use it itself, or not
		231	do anything special and let AnyEvent decide which implementation to chose.
		232
		233	If the main program relies on a specific event model (for example, in Gtk2
		234	programs you have to rely on either Glib or Glib::Event), you should load
		235	it before loading AnyEvent or any module that uses it, generally, as early
		236	as possible. The reason is that modules might create watchers when they
		237	are loaded, and AnyEvent will decide on the event model to use as soon as
		238	it creates watchers, and it might chose the wrong one unless you load the
		239	correct one yourself.
		240
		241	You can chose to use a rather inefficient pure-perl implementation by
		242	loading the C<AnyEvent::Impl::Perl> module, but letting AnyEvent chose is
		243	generally better.
		244
59	=cut	245	=cut
60		246
61	package AnyEvent;	247	package AnyEvent;
62		248
63	no warnings;	249	no warnings;
64	use strict 'vars';	250	use strict;
		251
65	use Carp;	252	use Carp;
66		253
67	our $VERSION = 0.3;	254	our $VERSION = '2.55';
68	our $MODEL;	255	our $MODEL;
69		256
70	our $AUTOLOAD;	257	our $AUTOLOAD;
71	our @ISA;	258	our @ISA;
72		259
		260	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
		261
		262	our @REGISTRY;
		263
73	my @models = (	264	my @models = (
74	[Coro => Coro::Event::],	265	[Coro::Event:: => AnyEvent::Impl::Coro::],
75	[Event => Event::],	266	[EV:: => EV::AnyEvent::],
76	[Glib => Glib::],	267	[Event:: => AnyEvent::Impl::Event::],
77	[Tk => Tk::],	268	[Glib:: => AnyEvent::Impl::Glib::],
		269	[Tk:: => AnyEvent::Impl::Tk::],
		270	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
78	);	271	);
79		272
80	our %method = map +($_ => 1), qw(io timer condvar broadcast wait cancel DESTROY);	273	our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY);
81		274
82	sub AUTOLOAD {	275	sub detect() {
83	$AUTOLOAD =~ s/.*://;
84
85	$method{$AUTOLOAD}
86	or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
87
88	unless ($MODEL) {	276	unless ($MODEL) {
		277	no strict 'refs';
		278
89	# check for already loaded models	279	# check for already loaded models
90	for (@models) {	280	for (@REGISTRY, @models) {
91	my ($model, $package) = @$_;	281	my ($package, $model) = @$_;
92	if (scalar keys %{ *{"$package\::"} }) {	282	if (${"$package\::VERSION"} > 0) {
93	eval "require AnyEvent::Impl::$model";	283	if (eval "require $model") {
94	last if $MODEL;	284	$MODEL = $model;
		285	warn "AnyEvent: found model '$model', using it.\n" if $verbose > 1;
		286	last;
		287	}
95	}	288	}
96	}	289	}
97		290
98	unless ($MODEL) {	291	unless ($MODEL) {
99	# try to load a model	292	# try to load a model
100		293
101	for (@models) {	294	for (@REGISTRY, @models) {
102	my ($model, $package) = @$_;	295	my ($package, $model) = @$_;
103	eval "require AnyEvent::Impl::$model";	296	if (eval "require $package"
104	last if $MODEL;	297	and ${"$package\::VERSION"} > 0
		298	and eval "require $model") {
		299	$MODEL = $model;
		300	warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
		301	last;
		302	}
105	}	303	}
106		304
107	$MODEL	305	$MODEL
108	or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Coro, Event, Glib or Tk.";	306	or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Event (or Coro+Event), Glib or Tk.";
109	}	307	}
		308
		309	unshift @ISA, $MODEL;
		310	push @{"$MODEL\::ISA"}, "AnyEvent::Base";
110	}	311	}
111		312
112	@ISA = $MODEL;	313	$MODEL
		314	}
		315
		316	sub AUTOLOAD {
		317	(my $func = $AUTOLOAD) =~ s/.*://;
		318
		319	$method{$func}
		320	or croak "$func: not a valid method for AnyEvent objects";
		321
		322	detect unless $MODEL;
113		323
114	my $class = shift;	324	my $class = shift;
115	$class->$AUTOLOAD (@_);	325	$class->$func (@_);
116	}	326	}
117		327
118	=back	328	package AnyEvent::Base;
		329
		330	# default implementation for ->condvar, ->wait, ->broadcast
		331
		332	sub condvar {
		333	bless \my $flag, "AnyEvent::Base::CondVar"
		334	}
		335
		336	sub AnyEvent::Base::CondVar::broadcast {
		337	${$_[0]}++;
		338	}
		339
		340	sub AnyEvent::Base::CondVar::wait {
		341	AnyEvent->one_event while !${$_[0]};
		342	}
		343
		344	# default implementation for ->signal
		345
		346	our %SIG_CB;
		347
		348	sub signal {
		349	my (undef, %arg) = @_;
		350
		351	my $signal = uc $arg{signal}
		352	or Carp::croak "required option 'signal' is missing";
		353
		354	$SIG_CB{$signal}{$arg{cb}} = $arg{cb};
		355	$SIG{$signal} \|\|= sub {
		356	$_->() for values %{ $SIG_CB{$signal} \|\| {} };
		357	};
		358
		359	bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
		360	}
		361
		362	sub AnyEvent::Base::Signal::DESTROY {
		363	my ($signal, $cb) = @{$_[0]};
		364
		365	delete $SIG_CB{$signal}{$cb};
		366
		367	$SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };
		368	}
		369
		370	# default implementation for ->child
		371
		372	our %PID_CB;
		373	our $CHLD_W;
		374	our $PID_IDLE;
		375	our $WNOHANG;
		376
		377	sub _child_wait {
		378	while (0 < (my $pid = waitpid -1, $WNOHANG)) {
		379	$_->() for values %{ (delete $PID_CB{$pid}) \|\| {} };
		380	}
		381
		382	undef $PID_IDLE;
		383	}
		384
		385	sub child {
		386	my (undef, %arg) = @_;
		387
		388	my $pid = uc $arg{pid}
		389	or Carp::croak "required option 'pid' is missing";
		390
		391	$PID_CB{$pid}{$arg{cb}} = $arg{cb};
		392
		393	unless ($WNOHANG) {
		394	$WNOHANG = eval { require POSIX; &POSIX::WNOHANG } \|\| 1;
		395	}
		396
		397	unless ($CHLD_W) {
		398	$CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_child_wait);
		399	# child could be a zombie already
		400	$PID_IDLE \|\|= AnyEvent->timer (after => 0, cb => \&_child_wait);
		401	}
		402
		403	bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
		404	}
		405
		406	sub AnyEvent::Base::Child::DESTROY {
		407	my ($pid, $cb) = @{$_[0]};
		408
		409	delete $PID_CB{$pid}{$cb};
		410	delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
		411
		412	undef $CHLD_W unless keys %PID_CB;
		413	}
		414
		415	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
		416
		417	If you need to support another event library which isn't directly
		418	supported by AnyEvent, you can supply your own interface to it by
		419	pushing, before the first watcher gets created, the package name of
		420	the event module and the package name of the interface to use onto
		421	C<@AnyEvent::REGISTRY>. You can do that before and even without loading
		422	AnyEvent.
		423
		424	Example:
		425
		426	push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
		427
		428	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
		429	package/class when it finds the C<urxvt> package/module is loaded. When
		430	AnyEvent is loaded and asked to find a suitable event model, it will
		431	first check for the presence of urxvt.
		432
		433	The class should provide implementations for all watcher types (see
		434	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
		435	(Source code) and so on for actual examples, use C<perldoc -m
		436	AnyEvent::Impl::Glib> to see the sources).
		437
		438	The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
		439	uses the above line as-is. An interface isn't included in AnyEvent
		440	because it doesn't make sense outside the embedded interpreter inside
		441	I<rxvt-unicode>, and it is updated and maintained as part of the
		442	I<rxvt-unicode> distribution.
		443
		444	I<rxvt-unicode> also cheats a bit by not providing blocking access to
		445	condition variables: code blocking while waiting for a condition will
		446	C<die>. This still works with most modules/usages, and blocking calls must
		447	not be in an interactive application, so it makes sense.
		448
		449	=head1 ENVIRONMENT VARIABLES
		450
		451	The following environment variables are used by this module:
		452
		453	C<PERL_ANYEVENT_VERBOSE> when set to C<2> or higher, reports which event
		454	model gets used.
119		455
120	=head1 EXAMPLE	456	=head1 EXAMPLE
121		457
122	The following program uses an io watcher to read data from stdin, a timer	458	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	459	to display a message once per second, and a condvar to exit the program
…		…
183	connect $txn->{fh}, ...	519	connect $txn->{fh}, ...
184	and !$!{EWOULDBLOCK}	520	and !$!{EWOULDBLOCK}
185	and !$!{EINPROGRESS}	521	and !$!{EINPROGRESS}
186	and Carp::croak "unable to connect: $!\n";	522	and Carp::croak "unable to connect: $!\n";
187		523
188	Then it creates a write-watcher which gets called wehnever an error occurs	524	Then it creates a write-watcher which gets called whenever an error occurs
189	or the connection succeeds:	525	or the connection succeeds:
190		526
191	$txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'w', cb => sub { $txn->fh_ready_w });	527	$txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'w', cb => sub { $txn->fh_ready_w });
192		528
193	And returns this transaction object. The C<fh_ready_w> callback gets	529	And returns this transaction object. The C<fh_ready_w> callback gets
…		…
210	sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};	546	sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
211		547
212	if (end-of-file or data complete) {	548	if (end-of-file or data complete) {
213	$txn->{result} = $txn->{buf};	549	$txn->{result} = $txn->{buf};
214	$txn->{finished}->broadcast;	550	$txn->{finished}->broadcast;
		551	$txb->{cb}->($txn) of $txn->{cb}; # also call callback
215	}	552	}
216		553
217	The C<result> method, finally, just waits for the finished signal (if the	554	The C<result> method, finally, just waits for the finished signal (if the
218	request was already finished, it doesn't wait, of course, and returns the	555	request was already finished, it doesn't wait, of course, and returns the
219	data:	556	data:
220		557
221	$txn->{finished}->wait;	558	$txn->{finished}->wait;
222	return $txn->{buf};	559	return $txn->{result};
223		560
224	The actual code goes further and collects all errors (C<die>s, exceptions)	561	The actual code goes further and collects all errors (C<die>s, exceptions)
225	that occured during request processing. The C<result> method detects	562	that occured during request processing. The C<result> method detects
226	wether an exception as thrown (it is stored inside the $txn object)	563	wether an exception as thrown (it is stored inside the $txn object)
227	and just throws the exception, which means connection errors and other	564	and just throws the exception, which means connection errors and other

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.5 by root, Sun Dec 4 09:44:32 2005 UTC vs. Revision 1.28 by root, Sat Oct 27 15:10:09 2007 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.5 by root, Sun Dec 4 09:44:32 2005 UTC vs.
Revision 1.28 by root, Sat Oct 27 15:10:09 2007 UTC