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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.13 by root, Thu Jul 20 08:26:00 2006 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 utilise an event loop without forcing module	71	allows module authors to utilise an event loop without forcing module
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 = '1.02';	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
81	our @REGISTRY;	320	our @REGISTRY;
82		321
83	my @models = (	322	my @models = (
		323	[Coro::EV:: => AnyEvent::Impl::CoroEV::],
84	[Coro::Event:: => AnyEvent::Impl::Coro::],	324	[Coro::Event:: => AnyEvent::Impl::CoroEvent::],
		325	[EV:: => AnyEvent::Impl::EV::],
85	[Event:: => AnyEvent::Impl::Event::],	326	[Event:: => AnyEvent::Impl::Event::],
86	[Glib:: => AnyEvent::Impl::Glib::],	327	[Glib:: => AnyEvent::Impl::Glib::],
87	[Tk:: => AnyEvent::Impl::Tk::],	328	[Tk:: => AnyEvent::Impl::Tk::],
		329	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
88	);	330	);
89		331
90	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);
91		333
92	sub AUTOLOAD {	334	sub detect() {
93	$AUTOLOAD =~ s/.*://;
94
95	$method{$AUTOLOAD}
96	or croak "$AUTOLOAD: not a valid method for AnyEvent objects";
97
98	unless ($MODEL) {	335	unless ($MODEL) {
		336	no strict 'refs';
		337
99	# check for already loaded models	338	# check for already loaded models
100	for (@REGISTRY, @models) {	339	for (@REGISTRY, @models) {
101	my ($package, $model) = @$_;	340	my ($package, $model) = @$_;
102	if (${"$package\::VERSION"} > 0) {	341	if (${"$package\::VERSION"} > 0) {
103	if (eval "require $model") {	342	if (eval "require $model") {
…		…
111	unless ($MODEL) {	350	unless ($MODEL) {
112	# try to load a model	351	# try to load a model
113		352
114	for (@REGISTRY, @models) {	353	for (@REGISTRY, @models) {
115	my ($package, $model) = @$_;	354	my ($package, $model) = @$_;
		355	if (eval "require $package"
		356	and ${"$package\::VERSION"} > 0
116	if (eval "require $model") {	357	and eval "require $model") {
117	$MODEL = $model;	358	$MODEL = $model;
118	warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;	359	warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
119	last;	360	last;
120	}	361	}
121	}	362	}
122		363
123	$MODEL	364	$MODEL
124	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.";
125	}	366	}
		367
		368	unshift @ISA, $MODEL;
		369	push @{"$MODEL\::ISA"}, "AnyEvent::Base";
126	}	370	}
127		371
128	@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;
129		382
130	my $class = shift;	383	my $class = shift;
131	$class->$AUTOLOAD (@_);	384	$class->$func (@_);
132	}	385	}
133		386
134	=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	}
135		483
136	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE	484	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
137		485
138	If you need to support another event library which isn't directly	486	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	487	supported by AnyEvent, you can supply your own interface to it by
…		…
149	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>	497	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
150	package/class when it finds the C<urxvt> package/module is loaded. When	498	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	499	AnyEvent is loaded and asked to find a suitable event model, it will
152	first check for the presence of urxvt.	500	first check for the presence of urxvt.
153		501
154	The class should prove implementations for all watcher types (see	502	The class should provide implementations for all watcher types (see
155	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>	503	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
156	(Source code) and so on for actual examples, use C<perldoc -m	504	(Source code) and so on for actual examples, use C<perldoc -m
157	AnyEvent::Impl::Glib> to see the sources).	505	AnyEvent::Impl::Glib> to see the sources).
158		506
159	The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)	507	The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
…		…
163	I<rxvt-unicode> distribution.	511	I<rxvt-unicode> distribution.
164		512
165	I<rxvt-unicode> also cheats a bit by not providing blocking access to	513	I<rxvt-unicode> also cheats a bit by not providing blocking access to
166	condition variables: code blocking while waiting for a condition will	514	condition variables: code blocking while waiting for a condition will
167	C<die>. This still works with most modules/usages, and blocking calls must	515	C<die>. This still works with most modules/usages, and blocking calls must
168	not be in an interactive appliation, so it makes sense.	516	not be in an interactive application, so it makes sense.
169		517
170	=head1 ENVIRONMENT VARIABLES	518	=head1 ENVIRONMENT VARIABLES
171		519
172	The following environment variables are used by this module:	520	The following environment variables are used by this module:
173		521
…		…
279	$txn->{finished}->wait;	627	$txn->{finished}->wait;
280	return $txn->{result};	628	return $txn->{result};
281		629
282	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)
283	that occured during request processing. The C<result> method detects	631	that occured during request processing. The C<result> method detects
284	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)
285	and just throws the exception, which means connection errors and other	633	and just throws the exception, which means connection errors and other
286	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
287	random callback.	635	random callback.
288		636
289	All of this enables the following usage styles:	637	All of this enables the following usage styles:
290		638
291	1. Blocking:	639	1. Blocking:
292		640
293	my $data = $fcp->client_get ($url);	641	my $data = $fcp->client_get ($url);
294		642
295	2. Blocking, but parallelizing:	643	2. Blocking, but running in parallel:
296		644
297	my @datas = map $_->result,	645	my @datas = map $_->result,
298	map $fcp->txn_client_get ($_),	646	map $fcp->txn_client_get ($_),
299	@urls;	647	@urls;
300		648
301	Both blocking examples work without the module user having to know	649	Both blocking examples work without the module user having to know
302	anything about events.	650	anything about events.
303		651
304	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:
305		653
306	use Event;	654	use EV;
307		655
308	$fcp->txn_client_get ($url)->cb (sub {	656	$fcp->txn_client_get ($url)->cb (sub {
309	my $txn = shift;	657	my $txn = shift;
310	my $data = $txn->result;	658	my $data = $txn->result;
311	...	659	...
312	});	660	});
313		661
314	Event::loop;	662	EV::loop;
315		663
316	3b. The module user could use AnyEvent, too:	664	3b. The module user could use AnyEvent, too:
317		665
318	use AnyEvent;	666	use AnyEvent;
319		667
…		…
326		674
327	$quit->wait;	675	$quit->wait;
328		676
329	=head1 SEE ALSO	677	=head1 SEE ALSO
330		678
331	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>.
332		681
333	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>.
334		685
335	Nontrivial usage example: L<Net::FCP>.	686	Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>.
336		687
337	=head1	688	=head1
338		689
339	=cut	690	=cut
340		691

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.13 by root, Thu Jul 20 08:26:00 2006 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.13 by root, Thu Jul 20 08:26:00 2006 UTC vs.
Revision 1.52 by root, Sat Apr 19 03:47:24 2008 UTC