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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.12 by root, Thu Jul 20 01:39:40 2006 UTC vs.
Revision 1.32 by root, Sat Nov 3 09:29:51 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 (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
42	a condvar for any "request" or "event" your module might create, C<<
43	->broadcast >> it when the event happens and provide a function that calls
44	C<< ->wait >> for it. See the examples below.
45
46	=head1 DESCRIPTION	23	=head1 DESCRIPTION
47		24
48	L<AnyEvent> provides an identical interface to multiple event loops. This	25	L<AnyEvent> provides an identical interface to multiple event loops. This
49	allows module authors to utilizy an event loop without forcing module	26	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	27	users to use the same event loop (as only a single event loop can coexist
51	peacefully at any one time).	28	peacefully at any one time).
52		29
53	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
54	module.	31	module.
56	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
57	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
58	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
59	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
60	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
61	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:
62		125
63	=over 4	126	=over 4
64		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 (or any child if the pid argument is 0). The watcher will
		180	trigger as often as status change for the child are received. This works
		181	by installing a signal handler for C<SIGCHLD>. The callback will be called with
		182	the pid and exit status (as returned by waitpid).
		183
		184	Example: wait for pid 1333
		185
		186	my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
		187
		188	=head1 GLOBALS
		189
		190	=over 4
		191
		192	=item $AnyEvent::MODEL
		193
		194	Contains C<undef> until the first watcher is being created. Then it
		195	contains the event model that is being used, which is the name of the
		196	Perl class implementing the model. This class is usually one of the
		197	C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
		198	AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
		199
		200	The known classes so far are:
		201
		202	EV::AnyEvent based on EV (an interface to libev, best choice)
		203	AnyEvent::Impl::Coro based on Coro::Event, second best choice.
		204	AnyEvent::Impl::Event based on Event, also second best choice :)
		205	AnyEvent::Impl::Glib based on Glib, second-best choice.
		206	AnyEvent::Impl::Tk based on Tk, very bad choice.
		207	AnyEvent::Impl::Perl pure-perl implementation, inefficient.
		208
		209	=item AnyEvent::detect
		210
		211	Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
		212	necessary. You should only call this function right before you would have
		213	created an AnyEvent watcher anyway, that is, very late at runtime.
		214
		215	=back
		216
		217	=head1 WHAT TO DO IN A MODULE
		218
		219	As a module author, you should "use AnyEvent" and call AnyEvent methods
		220	freely, but you should not load a specific event module or rely on it.
		221
		222	Be careful when you create watchers in the module body - Anyevent will
		223	decide which event module to use as soon as the first method is called, so
		224	by calling AnyEvent in your module body you force the user of your module
		225	to load the event module first.
		226
		227	=head1 WHAT TO DO IN THE MAIN PROGRAM
		228
		229	There will always be a single main program - the only place that should
		230	dictate which event model to use.
		231
		232	If it doesn't care, it can just "use AnyEvent" and use it itself, or not
		233	do anything special and let AnyEvent decide which implementation to chose.
		234
		235	If the main program relies on a specific event model (for example, in Gtk2
		236	programs you have to rely on either Glib or Glib::Event), you should load
		237	it before loading AnyEvent or any module that uses it, generally, as early
		238	as possible. The reason is that modules might create watchers when they
		239	are loaded, and AnyEvent will decide on the event model to use as soon as
		240	it creates watchers, and it might chose the wrong one unless you load the
		241	correct one yourself.
		242
		243	You can chose to use a rather inefficient pure-perl implementation by
		244	loading the C<AnyEvent::Impl::Perl> module, but letting AnyEvent chose is
		245	generally better.
		246
65	=cut	247	=cut
66		248
67	package AnyEvent;	249	package AnyEvent;
68		250
69	no warnings;	251	no warnings;
70	use strict 'vars';	252	use strict;
		253
71	use Carp;	254	use Carp;
72		255
73	our $VERSION = '1.02';	256	our $VERSION = '2.55';
74	our $MODEL;	257	our $MODEL;
75		258
76	our $AUTOLOAD;	259	our $AUTOLOAD;
77	our @ISA;	260	our @ISA;
78		261
79	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;	262	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
80		263
81	our @REGISTRY;	264	our @REGISTRY;
82		265
83	my @models = (	266	my @models = (
84	[Coro::Event:: => AnyEvent::Impl::Coro::],	267	[Coro::Event:: => AnyEvent::Impl::Coro::],
		268	[EV:: => EV::AnyEvent::],
85	[Event:: => AnyEvent::Impl::Event::],	269	[Event:: => AnyEvent::Impl::Event::],
86	[Glib:: => AnyEvent::Impl::Glib::],	270	[Glib:: => AnyEvent::Impl::Glib::],
87	[Tk:: => AnyEvent::Impl::Tk::],	271	[Tk:: => AnyEvent::Impl::Tk::],
		272	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
88	);	273	);
89		274
90	our %method = map +($_ => 1), qw(io timer condvar broadcast wait cancel DESTROY);	275	our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY);
91		276
92	sub AUTOLOAD {	277	sub detect() {
93	$AUTOLOAD =~ s/.*://;
94
95	$method{$AUTOLOAD}
96	or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
97
98	unless ($MODEL) {	278	unless ($MODEL) {
		279	no strict 'refs';
		280
99	# check for already loaded models	281	# check for already loaded models
100	for (@REGISTRY, @models) {	282	for (@REGISTRY, @models) {
101	my ($package, $model) = @$_;	283	my ($package, $model) = @$_;
102	if (${"$package\::VERSION"} > 0) {	284	if (${"$package\::VERSION"} > 0) {
103	if (eval "require $model") {	285	if (eval "require $model") {
…		…
111	unless ($MODEL) {	293	unless ($MODEL) {
112	# try to load a model	294	# try to load a model
113		295
114	for (@REGISTRY, @models) {	296	for (@REGISTRY, @models) {
115	my ($package, $model) = @$_;	297	my ($package, $model) = @$_;
		298	if (eval "require $package"
		299	and ${"$package\::VERSION"} > 0
116	if (eval "require $model") {	300	and eval "require $model") {
117	$MODEL = $model;	301	$MODEL = $model;
118	warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;	302	warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
119	last;	303	last;
120	}	304	}
121	}	305	}
122		306
123	$MODEL	307	$MODEL
124	or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Coro, Event, Glib or Tk.";	308	or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Event (or Coro+Event), Glib or Tk.";
125	}	309	}
		310
		311	unshift @ISA, $MODEL;
		312	push @{"$MODEL\::ISA"}, "AnyEvent::Base";
126	}	313	}
127		314
128	@ISA = $MODEL;	315	$MODEL
		316	}
		317
		318	sub AUTOLOAD {
		319	(my $func = $AUTOLOAD) =~ s/.*://;
		320
		321	$method{$func}
		322	or croak "$func: not a valid method for AnyEvent objects";
		323
		324	detect unless $MODEL;
129		325
130	my $class = shift;	326	my $class = shift;
131	$class->$AUTOLOAD (@_);	327	$class->$func (@_);
132	}	328	}
133		329
134	=back	330	package AnyEvent::Base;
		331
		332	# default implementation for ->condvar, ->wait, ->broadcast
		333
		334	sub condvar {
		335	bless \my $flag, "AnyEvent::Base::CondVar"
		336	}
		337
		338	sub AnyEvent::Base::CondVar::broadcast {
		339	${$_[0]}++;
		340	}
		341
		342	sub AnyEvent::Base::CondVar::wait {
		343	AnyEvent->one_event while !${$_[0]};
		344	}
		345
		346	# default implementation for ->signal
		347
		348	our %SIG_CB;
		349
		350	sub signal {
		351	my (undef, %arg) = @_;
		352
		353	my $signal = uc $arg{signal}
		354	or Carp::croak "required option 'signal' is missing";
		355
		356	$SIG_CB{$signal}{$arg{cb}} = $arg{cb};
		357	$SIG{$signal} \|\|= sub {
		358	$_->() for values %{ $SIG_CB{$signal} \|\| {} };
		359	};
		360
		361	bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
		362	}
		363
		364	sub AnyEvent::Base::Signal::DESTROY {
		365	my ($signal, $cb) = @{$_[0]};
		366
		367	delete $SIG_CB{$signal}{$cb};
		368
		369	$SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };
		370	}
		371
		372	# default implementation for ->child
		373
		374	our %PID_CB;
		375	our $CHLD_W;
		376	our $PID_IDLE;
		377	our $WNOHANG;
		378
		379	sub _child_wait {
		380	while (0 <= (my $pid = waitpid -1, $WNOHANG)) {
		381	$_->($pid, $?) for (values %{ $PID_CB{$pid} \|\| {} }),
		382	(values %{ $PID_CB{0} \|\| {} });
		383	}
		384
		385	undef $PID_IDLE;
		386	}
		387
		388	sub child {
		389	my (undef, %arg) = @_;
		390
		391	defined (my $pid = $arg{pid} + 0)
		392	or Carp::croak "required option 'pid' is missing";
		393
		394	$PID_CB{$pid}{$arg{cb}} = $arg{cb};
		395
		396	unless ($WNOHANG) {
		397	$WNOHANG = eval { require POSIX; &POSIX::WNOHANG } \|\| 1;
		398	}
		399
		400	unless ($CHLD_W) {
		401	$CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_child_wait);
		402	# child could be a zombie already
		403	$PID_IDLE \|\|= AnyEvent->timer (after => 0, cb => \&_child_wait);
		404	}
		405
		406	bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
		407	}
		408
		409	sub AnyEvent::Base::Child::DESTROY {
		410	my ($pid, $cb) = @{$_[0]};
		411
		412	delete $PID_CB{$pid}{$cb};
		413	delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
		414
		415	undef $CHLD_W unless keys %PID_CB;
		416	}
135		417
136	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE	418	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
137		419
138	If you need to support another event library which isn't directly	420	If you need to support another event library which isn't directly
139	supported by AnyEvent, you can supply your own interface to it by	421	supported by AnyEvent, you can supply your own interface to it by
…		…
149	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>	431	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
150	package/class when it finds the C<urxvt> package/module is loaded. When	432	package/class when it finds the C<urxvt> package/module is loaded. When
151	AnyEvent is loaded and asked to find a suitable event model, it will	433	AnyEvent is loaded and asked to find a suitable event model, it will
152	first check for the presence of urxvt.	434	first check for the presence of urxvt.
153		435
154	The class should prove implementations for all watcher types (see	436	The class should provide implementations for all watcher types (see
155	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>	437	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
156	(Source code) and so on for actual examples, use C<perldoc -m	438	(Source code) and so on for actual examples, use C<perldoc -m
157	AnyEvent::Impl::Glib> to see the sources).	439	AnyEvent::Impl::Glib> to see the sources).
158		440
159	The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)	441	The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
…		…
163	I<rxvt-unicode> distribution.	445	I<rxvt-unicode> distribution.
164		446
165	I<rxvt-unicode> also cheats a bit by not providing blocking access to	447	I<rxvt-unicode> also cheats a bit by not providing blocking access to
166	condition variables: code blocking while waiting for a condition will	448	condition variables: code blocking while waiting for a condition will
167	C<die>. This still works with most modules/usages, and blocking calls must	449	C<die>. This still works with most modules/usages, and blocking calls must
168	not be in an interactive appliation, so it makes sense.	450	not be in an interactive application, so it makes sense.
169		451
170	=head1 ENVIRONMENT VARIABLES	452	=head1 ENVIRONMENT VARIABLES
171		453
172	The following environment variables are used by this module:	454	The following environment variables are used by this module:
173		455

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.12 by root, Thu Jul 20 01:39:40 2006 UTC vs. Revision 1.32 by root, Sat Nov 3 09:29:51 2007 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.12 by root, Thu Jul 20 01:39:40 2006 UTC vs.
Revision 1.32 by root, Sat Nov 3 09:29:51 2007 UTC