[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.52 by root, Sat Apr 19 03:47:24 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	EV, Event, Coro::EV, Coro::Event, 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 whether 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 use the one and only event
		65	model, 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.
55		77
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 whether 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::EV>, L<Coro::Event>, L<EV>, L<Event>, L<Glib>, L<Tk>. The
59	used. If none is found, the module tries to load these modules in the	81	first one found is used. If none are found, the module tries to load these
60	order given. The first one that could be successfully loaded will be	82	modules in the order given. The first one that could be successfully
61	used. If still none could be found, it will issue an error.	83	loaded will be used. If still none could be found, AnyEvent will fall back
		84	to a pure-perl 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	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:
62		172
63	=over 4	173	=over 4
64		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	You can only wait once on a condition - additional calls will return
		181	immediately.
		182
		183	Not all event models support a blocking wait - some die in that case
		184	(programs might want to do that so they stay interactive), so I<if you
		185	are using this from a module, never require a blocking wait>, but let the
		186	caller decide whether the call will block or not (for example, by coupling
		187	condition variables with some kind of request results and supporting
		188	callbacks so the caller knows that getting the result will not block,
		189	while still suppporting blocking waits if the caller so desires).
		190
		191	Another reason I<never> to C<< ->wait >> in a module is that you cannot
		192	sensibly have two C<< ->wait >>'s in parallel, as that would require
		193	multiple interpreters or coroutines/threads, none of which C<AnyEvent>
		194	can supply (the coroutine-aware backends C<Coro::EV> and C<Coro::Event>
		195	explicitly support concurrent C<< ->wait >>'s from different coroutines,
		196	however).
		197
		198	=item $cv->broadcast
		199
		200	Flag the condition as ready - a running C<< ->wait >> and all further
		201	calls to C<wait> will return after this method has been called. If nobody
		202	is waiting the broadcast will be remembered..
		203
		204	Example:
		205
		206	# wait till the result is ready
		207	my $result_ready = AnyEvent->condvar;
		208
		209	# do something such as adding a timer
		210	# or socket watcher the calls $result_ready->broadcast
		211	# when the "result" is ready.
		212
		213	$result_ready->wait;
		214
		215	=back
		216
		217	=head2 SIGNAL WATCHERS
		218
		219	You can listen for signals using a signal watcher, C<signal> is the signal
		220	I<name> without any C<SIG> prefix. Multiple signals events can be clumped
		221	together into one callback invocation, and callback invocation might or
		222	might not be asynchronous.
		223
		224	These watchers might use C<%SIG>, so programs overwriting those signals
		225	directly will likely not work correctly.
		226
		227	Example: exit on SIGINT
		228
		229	my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
		230
		231	=head2 CHILD PROCESS WATCHERS
		232
		233	You can also listen for the status of a child process specified by the
		234	C<pid> argument (or any child if the pid argument is 0). The watcher will
		235	trigger as often as status change for the child are received. This works
		236	by installing a signal handler for C<SIGCHLD>. The callback will be called with
		237	the pid and exit status (as returned by waitpid).
		238
		239	Example: wait for pid 1333
		240
		241	my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
		242
		243	=head1 GLOBALS
		244
		245	=over 4
		246
		247	=item $AnyEvent::MODEL
		248
		249	Contains C<undef> until the first watcher is being created. Then it
		250	contains the event model that is being used, which is the name of the
		251	Perl class implementing the model. This class is usually one of the
		252	C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
		253	AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
		254
		255	The known classes so far are:
		256
		257	AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
		258	AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
		259	AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
		260	AnyEvent::Impl::Event based on Event, also second best choice :)
		261	AnyEvent::Impl::Glib based on Glib, third-best choice.
		262	AnyEvent::Impl::Tk based on Tk, very bad choice.
		263	AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
		264
		265	=item AnyEvent::detect
		266
		267	Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
		268	necessary. You should only call this function right before you would have
		269	created an AnyEvent watcher anyway, that is, very late at runtime.
		270
		271	=back
		272
		273	=head1 WHAT TO DO IN A MODULE
		274
		275	As a module author, you should "use AnyEvent" and call AnyEvent methods
		276	freely, but you should not load a specific event module or rely on it.
		277
		278	Be careful when you create watchers in the module body - Anyevent will
		279	decide which event module to use as soon as the first method is called, so
		280	by calling AnyEvent in your module body you force the user of your module
		281	to load the event module first.
		282
		283	=head1 WHAT TO DO IN THE MAIN PROGRAM
		284
		285	There will always be a single main program - the only place that should
		286	dictate which event model to use.
		287
		288	If it doesn't care, it can just "use AnyEvent" and use it itself, or not
		289	do anything special and let AnyEvent decide which implementation to chose.
		290
		291	If the main program relies on a specific event model (for example, in Gtk2
		292	programs you have to rely on either Glib or Glib::Event), you should load
		293	it before loading AnyEvent or any module that uses it, generally, as early
		294	as possible. The reason is that modules might create watchers when they
		295	are loaded, and AnyEvent will decide on the event model to use as soon as
		296	it creates watchers, and it might chose the wrong one unless you load the
		297	correct one yourself.
		298
		299	You can chose to use a rather inefficient pure-perl implementation by
		300	loading the C<AnyEvent::Impl::Perl> module, but letting AnyEvent chose is
		301	generally better.
		302
65	=cut	303	=cut
66		304
67	package AnyEvent;	305	package AnyEvent;
68		306
69	no warnings;	307	no warnings;
70	use strict 'vars';	308	use strict;
		309
71	use Carp;	310	use Carp;
72		311
73	our $VERSION = '0.4';	312	our $VERSION = '3.1';
74	our $MODEL;	313	our $MODEL;
75		314
76	our $AUTOLOAD;	315	our $AUTOLOAD;
77	our @ISA;	316	our @ISA;
78		317
79	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;	318	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
80		319
		320	our @REGISTRY;
		321
81	my @models = (	322	my @models = (
82	[Coro => Coro::Event::],	323	[Coro::EV:: => AnyEvent::Impl::CoroEV::],
83	[Event => Event::],	324	[Coro::Event:: => AnyEvent::Impl::CoroEvent::],
84	[Glib => Glib::],	325	[EV:: => AnyEvent::Impl::EV::],
85	[Tk => Tk::],	326	[Event:: => AnyEvent::Impl::Event::],
		327	[Glib:: => AnyEvent::Impl::Glib::],
		328	[Tk:: => AnyEvent::Impl::Tk::],
		329	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
86	);	330	);
87		331
88	our %method = map +($_ => 1), qw(io timer condvar broadcast wait cancel DESTROY);	332	our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY);
89		333
90	sub AUTOLOAD {	334	sub detect() {
91	$AUTOLOAD =~ s/.*://;
92
93	$method{$AUTOLOAD}
94	or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
95
96	unless ($MODEL) {	335	unless ($MODEL) {
		336	no strict 'refs';
		337
97	# check for already loaded models	338	# check for already loaded models
98	for (@models) {	339	for (@REGISTRY, @models) {
99	my ($model, $package) = @$_;	340	my ($package, $model) = @$_;
100	if (${"$package\::VERSION"} > 0) {	341	if (${"$package\::VERSION"} > 0) {
101	eval "require AnyEvent::Impl::$model";	342	if (eval "require $model") {
		343	$MODEL = $model;
102	warn "AnyEvent: found model '$model', using it.\n" if $MODEL && $verbose > 1;	344	warn "AnyEvent: found model '$model', using it.\n" if $verbose > 1;
103	last if $MODEL;	345	last;
		346	}
104	}	347	}
105	}	348	}
106		349
107	unless ($MODEL) {	350	unless ($MODEL) {
108	# try to load a model	351	# try to load a model
109		352
110	for (@models) {	353	for (@REGISTRY, @models) {
111	my ($model, $package) = @$_;	354	my ($package, $model) = @$_;
112	eval "require AnyEvent::Impl::$model";	355	if (eval "require $package"
		356	and ${"$package\::VERSION"} > 0
		357	and eval "require $model") {
		358	$MODEL = $model;
113	warn "AnyEvent: autprobed and loaded model '$model', using it.\n" if $MODEL && $verbose > 1;	359	warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
114	last if $MODEL;	360	last;
		361	}
115	}	362	}
116		363
117	$MODEL	364	$MODEL
118	or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Coro, Event, Glib or Tk.";	365	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	}	366	}
		367
		368	unshift @ISA, $MODEL;
		369	push @{"$MODEL\::ISA"}, "AnyEvent::Base";
120	}	370	}
121		371
122	@ISA = $MODEL;	372	$MODEL
		373	}
		374
		375	sub AUTOLOAD {
		376	(my $func = $AUTOLOAD) =~ s/.*://;
		377
		378	$method{$func}
		379	or croak "$func: not a valid method for AnyEvent objects";
		380
		381	detect unless $MODEL;
123		382
124	my $class = shift;	383	my $class = shift;
125	$class->$AUTOLOAD (@_);	384	$class->$func (@_);
126	}	385	}
127		386
128	=back	387	package AnyEvent::Base;
		388
		389	# default implementation for ->condvar, ->wait, ->broadcast
		390
		391	sub condvar {
		392	bless \my $flag, "AnyEvent::Base::CondVar"
		393	}
		394
		395	sub AnyEvent::Base::CondVar::broadcast {
		396	${$_[0]}++;
		397	}
		398
		399	sub AnyEvent::Base::CondVar::wait {
		400	AnyEvent->one_event while !${$_[0]};
		401	}
		402
		403	# default implementation for ->signal
		404
		405	our %SIG_CB;
		406
		407	sub signal {
		408	my (undef, %arg) = @_;
		409
		410	my $signal = uc $arg{signal}
		411	or Carp::croak "required option 'signal' is missing";
		412
		413	$SIG_CB{$signal}{$arg{cb}} = $arg{cb};
		414	$SIG{$signal} \|\|= sub {
		415	$_->() for values %{ $SIG_CB{$signal} \|\| {} };
		416	};
		417
		418	bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
		419	}
		420
		421	sub AnyEvent::Base::Signal::DESTROY {
		422	my ($signal, $cb) = @{$_[0]};
		423
		424	delete $SIG_CB{$signal}{$cb};
		425
		426	$SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };
		427	}
		428
		429	# default implementation for ->child
		430
		431	our %PID_CB;
		432	our $CHLD_W;
		433	our $CHLD_DELAY_W;
		434	our $PID_IDLE;
		435	our $WNOHANG;
		436
		437	sub _child_wait {
		438	while (0 < (my $pid = waitpid -1, $WNOHANG)) {
		439	$_->($pid, $?) for (values %{ $PID_CB{$pid} \|\| {} }),
		440	(values %{ $PID_CB{0} \|\| {} });
		441	}
		442
		443	undef $PID_IDLE;
		444	}
		445
		446	sub _sigchld {
		447	# make sure we deliver these changes "synchronous" with the event loop.
		448	$CHLD_DELAY_W \|\|= AnyEvent->timer (after => 0, cb => sub {
		449	undef $CHLD_DELAY_W;
		450	&_child_wait;
		451	});
		452	}
		453
		454	sub child {
		455	my (undef, %arg) = @_;
		456
		457	defined (my $pid = $arg{pid} + 0)
		458	or Carp::croak "required option 'pid' is missing";
		459
		460	$PID_CB{$pid}{$arg{cb}} = $arg{cb};
		461
		462	unless ($WNOHANG) {
		463	$WNOHANG = eval { require POSIX; &POSIX::WNOHANG } \|\| 1;
		464	}
		465
		466	unless ($CHLD_W) {
		467	$CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
		468	# child could be a zombie already, so make at least one round
		469	&_sigchld;
		470	}
		471
		472	bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
		473	}
		474
		475	sub AnyEvent::Base::Child::DESTROY {
		476	my ($pid, $cb) = @{$_[0]};
		477
		478	delete $PID_CB{$pid}{$cb};
		479	delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
		480
		481	undef $CHLD_W unless keys %PID_CB;
		482	}
		483
		484	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
		485
		486	If you need to support another event library which isn't directly
		487	supported by AnyEvent, you can supply your own interface to it by
		488	pushing, before the first watcher gets created, the package name of
		489	the event module and the package name of the interface to use onto
		490	C<@AnyEvent::REGISTRY>. You can do that before and even without loading
		491	AnyEvent.
		492
		493	Example:
		494
		495	push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
		496
		497	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
		498	package/class when it finds the C<urxvt> package/module is loaded. When
		499	AnyEvent is loaded and asked to find a suitable event model, it will
		500	first check for the presence of urxvt.
		501
		502	The class should provide implementations for all watcher types (see
		503	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
		504	(Source code) and so on for actual examples, use C<perldoc -m
		505	AnyEvent::Impl::Glib> to see the sources).
		506
		507	The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
		508	uses the above line as-is. An interface isn't included in AnyEvent
		509	because it doesn't make sense outside the embedded interpreter inside
		510	I<rxvt-unicode>, and it is updated and maintained as part of the
		511	I<rxvt-unicode> distribution.
		512
		513	I<rxvt-unicode> also cheats a bit by not providing blocking access to
		514	condition variables: code blocking while waiting for a condition will
		515	C<die>. This still works with most modules/usages, and blocking calls must
		516	not be in an interactive application, so it makes sense.
129		517
130	=head1 ENVIRONMENT VARIABLES	518	=head1 ENVIRONMENT VARIABLES
131		519
132	The following environment variables are used by this module:	520	The following environment variables are used by this module:
133		521
239	$txn->{finished}->wait;	627	$txn->{finished}->wait;
240	return $txn->{result};	628	return $txn->{result};
241		629
242	The actual code goes further and collects all errors (C<die>s, exceptions)	630	The actual code goes further and collects all errors (C<die>s, exceptions)
243	that occured during request processing. The C<result> method detects	631	that occured during request processing. The C<result> method detects
244	wether an exception as thrown (it is stored inside the $txn object)	632	whether an exception as thrown (it is stored inside the $txn object)
245	and just throws the exception, which means connection errors and other	633	and just throws the exception, which means connection errors and other
246	problems get reported tot he code that tries to use the result, not in a	634	problems get reported tot he code that tries to use the result, not in a
247	random callback.	635	random callback.
248		636
249	All of this enables the following usage styles:	637	All of this enables the following usage styles:
250		638
251	1. Blocking:	639	1. Blocking:
252		640
253	my $data = $fcp->client_get ($url);	641	my $data = $fcp->client_get ($url);
254		642
255	2. Blocking, but parallelizing:	643	2. Blocking, but running in parallel:
256		644
257	my @datas = map $_->result,	645	my @datas = map $_->result,
258	map $fcp->txn_client_get ($_),	646	map $fcp->txn_client_get ($_),
259	@urls;	647	@urls;
260		648
261	Both blocking examples work without the module user having to know	649	Both blocking examples work without the module user having to know
262	anything about events.	650	anything about events.
263		651
264	3a. Event-based in a main program, using any support Event module:	652	3a. Event-based in a main program, using any supported event module:
265		653
266	use Event;	654	use EV;
267		655
268	$fcp->txn_client_get ($url)->cb (sub {	656	$fcp->txn_client_get ($url)->cb (sub {
269	my $txn = shift;	657	my $txn = shift;
270	my $data = $txn->result;	658	my $data = $txn->result;
271	...	659	...
272	});	660	});
273		661
274	Event::loop;	662	EV::loop;
275		663
276	3b. The module user could use AnyEvent, too:	664	3b. The module user could use AnyEvent, too:
277		665
278	use AnyEvent;	666	use AnyEvent;
279		667
…		…
286		674
287	$quit->wait;	675	$quit->wait;
288		676
289	=head1 SEE ALSO	677	=head1 SEE ALSO
290		678
291	Event modules: L<Coro::Event>, L<Coro>, L<Event>, L<Glib::Event>, L<Glib>.	679	Event modules: L<Coro::EV>, L<EV>, L<EV::Glib>, L<Glib::EV>,
		680	L<Coro::Event>, L<Event>, L<Glib::Event>, L<Glib>, L<Coro>, L<Tk>.
292		681
293	Implementations: L<AnyEvent::Impl::Coro>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>.	682	Implementations: L<AnyEvent::Impl::CoroEV>, L<AnyEvent::Impl::EV>,
		683	L<AnyEvent::Impl::CoroEvent>, L<AnyEvent::Impl::Event>,
		684	L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>.
294		685
295	Nontrivial usage example: L<Net::FCP>.	686	Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
296		687
297	=head1	688	=head1
298		689
299	=cut	690	=cut
300		691

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.52 by root, Sat Apr 19 03:47:24 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.52 by root, Sat Apr 19 03:47:24 2008 UTC