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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.1 by root, Wed Apr 27 01:26:44 2005 UTC vs.
Revision 1.48 by root, Mon Apr 14 19:00:23 2008 UTC

1	=head1 NAME	1	=head1 NAME
2		2
3	AnyEvent - ???	3	AnyEvent - provide framework for multiple event loops
		4
		5	Event, Coro, Glib, Tk, Perl - various supported event loops
4		6
5	=head1 SYNOPSIS	7	=head1 SYNOPSIS
6		8
		9	use AnyEvent;
		10
		11	my $w = AnyEvent->io (fh => $fh, poll => "r\|w", cb => sub {
		12	...
		13	});
		14
		15	my $w = AnyEvent->timer (after => $seconds, cb => sub {
		16	...
		17	});
		18
		19	my $w = AnyEvent->condvar; # stores wether a condition was flagged
		20	$w->wait; # enters "main loop" till $condvar gets ->broadcast
		21	$w->broadcast; # wake up current and all future wait's
		22
		23	=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
		24
		25	Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
		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
		67
7	=head1 DESCRIPTION	68	=head1 DESCRIPTION
8		69
		70	L<AnyEvent> provides an identical interface to multiple event loops. This
		71	allows module authors to utilise an event loop without forcing module
		72	users to use the same event loop (as only a single event loop can coexist
		73	peacefully at any one time).
		74
		75	The interface itself is vaguely similar but not identical to the Event
		76	module.
		77
		78	On the first call of any method, the module tries to detect the currently
		79	loaded event loop by probing wether any of the following modules is
		80	loaded: L<Coro::Event>, L<Event>, L<Glib>, L<Tk>. The first one found is
		81	used. If none is found, the module tries to load these modules in the
		82	order given. The first one that could be successfully loaded will be
		83	used. If still none could be found, AnyEvent will fall back to a pure-perl
		84	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	Only one io watcher per C<fh> and C<poll> combination is allowed (i.e. on
		124	a socket you can have one r + one w, not any more (limitation comes from
		125	Tk - if you are sure you are not using Tk this limitation is gone).
		126
		127	Filehandles will be kept alive, so as long as the watcher exists, the
		128	filehandle exists, too.
		129
		130	Example:
		131
		132	# wait for readability of STDIN, then read a line and disable the watcher
		133	my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
		134	chomp (my $input = <STDIN>);
		135	warn "read: $input\n";
		136	undef $w;
		137	});
		138
		139	=head2 TIME WATCHERS
		140
		141	You can create a time watcher by calling the C<< AnyEvent->timer >>
		142	method with the following mandatory arguments:
		143
		144	C<after> after how many seconds (fractions are supported) should the timer
		145	activate. C<cb> the callback to invoke.
		146
		147	The timer callback will be invoked at most once: if you want a repeating
		148	timer you have to create a new watcher (this is a limitation by both Tk
		149	and Glib).
		150
		151	Example:
		152
		153	# fire an event after 7.7 seconds
		154	my $w = AnyEvent->timer (after => 7.7, cb => sub {
		155	warn "timeout\n";
		156	});
		157
		158	# to cancel the timer:
		159	undef $w;
		160
		161	=head2 CONDITION WATCHERS
		162
		163	Condition watchers can be created by calling the C<< AnyEvent->condvar >>
		164	method without any arguments.
		165
		166	A condition watcher watches for a condition - precisely that the C<<
		167	->broadcast >> method has been called.
		168
		169	Note that condition watchers recurse into the event loop - if you have
		170	two watchers that call C<< ->wait >> in a round-robbin fashion, you
		171	lose. Therefore, condition watchers are good to export to your caller, but
		172	you should avoid making a blocking wait, at least in callbacks, as this
		173	usually asks for trouble.
		174
		175	The watcher has only two methods:
		176
9	=over 4	177	=over 4
10		178
		179	=item $cv->wait
		180
		181	Wait (blocking if necessary) until the C<< ->broadcast >> method has been
		182	called on c<$cv>, while servicing other watchers normally.
		183
		184	You can only wait once on a condition - additional calls will return
		185	immediately.
		186
		187	Not all event models support a blocking wait - some die in that case
		188	(programs might want to do that so they stay interactive), so I<if you
		189	are using this from a module, never require a blocking wait>, but let the
		190	caller decide wether the call will block or not (for example, by coupling
		191	condition variables with some kind of request results and supporting
		192	callbacks so the caller knows that getting the result will not block,
		193	while still suppporting blocking waits if the caller so desires).
		194
		195	Another reason I<never> to C<< ->wait >> in a module is that you cannot
		196	sensibly have two C<< ->wait >>'s in parallel, as that would require
		197	multiple interpreters or coroutines/threads, none of which C<AnyEvent>
		198	can supply (the coroutine-aware backends C<Coro::EV> and C<Coro::Event>
		199	explicitly support concurrent C<< ->wait >>'s from different coroutines,
		200	however).
		201
		202	=item $cv->broadcast
		203
		204	Flag the condition as ready - a running C<< ->wait >> and all further
		205	calls to C<wait> will return after this method has been called. If nobody
		206	is waiting the broadcast will be remembered..
		207
		208	Example:
		209
		210	# wait till the result is ready
		211	my $result_ready = AnyEvent->condvar;
		212
		213	# do something such as adding a timer
		214	# or socket watcher the calls $result_ready->broadcast
		215	# when the "result" is ready.
		216
		217	$result_ready->wait;
		218
		219	=back
		220
		221	=head2 SIGNAL WATCHERS
		222
		223	You can listen for signals using a signal watcher, C<signal> is the signal
		224	I<name> without any C<SIG> prefix. Multiple signals events can be clumped
		225	together into one callback invocation, and callback invocation might or
		226	might not be asynchronous.
		227
		228	These watchers might use C<%SIG>, so programs overwriting those signals
		229	directly will likely not work correctly.
		230
		231	Example: exit on SIGINT
		232
		233	my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
		234
		235	=head2 CHILD PROCESS WATCHERS
		236
		237	You can also listen for the status of a child process specified by the
		238	C<pid> argument (or any child if the pid argument is 0). The watcher will
		239	trigger as often as status change for the child are received. This works
		240	by installing a signal handler for C<SIGCHLD>. The callback will be called with
		241	the pid and exit status (as returned by waitpid).
		242
		243	Example: wait for pid 1333
		244
		245	my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
		246
		247	=head1 GLOBALS
		248
		249	=over 4
		250
		251	=item $AnyEvent::MODEL
		252
		253	Contains C<undef> until the first watcher is being created. Then it
		254	contains the event model that is being used, which is the name of the
		255	Perl class implementing the model. This class is usually one of the
		256	C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
		257	AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
		258
		259	The known classes so far are:
		260
		261	AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
		262	AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
		263	AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
		264	AnyEvent::Impl::Event based on Event, also second best choice :)
		265	AnyEvent::Impl::Glib based on Glib, third-best choice.
		266	AnyEvent::Impl::Tk based on Tk, very bad choice.
		267	AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
		268
		269	=item AnyEvent::detect
		270
		271	Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model if
		272	necessary. You should only call this function right before you would have
		273	created an AnyEvent watcher anyway, that is, very late at runtime.
		274
		275	=back
		276
		277	=head1 WHAT TO DO IN A MODULE
		278
		279	As a module author, you should "use AnyEvent" and call AnyEvent methods
		280	freely, but you should not load a specific event module or rely on it.
		281
		282	Be careful when you create watchers in the module body - Anyevent will
		283	decide which event module to use as soon as the first method is called, so
		284	by calling AnyEvent in your module body you force the user of your module
		285	to load the event module first.
		286
		287	=head1 WHAT TO DO IN THE MAIN PROGRAM
		288
		289	There will always be a single main program - the only place that should
		290	dictate which event model to use.
		291
		292	If it doesn't care, it can just "use AnyEvent" and use it itself, or not
		293	do anything special and let AnyEvent decide which implementation to chose.
		294
		295	If the main program relies on a specific event model (for example, in Gtk2
		296	programs you have to rely on either Glib or Glib::Event), you should load
		297	it before loading AnyEvent or any module that uses it, generally, as early
		298	as possible. The reason is that modules might create watchers when they
		299	are loaded, and AnyEvent will decide on the event model to use as soon as
		300	it creates watchers, and it might chose the wrong one unless you load the
		301	correct one yourself.
		302
		303	You can chose to use a rather inefficient pure-perl implementation by
		304	loading the C<AnyEvent::Impl::Perl> module, but letting AnyEvent chose is
		305	generally better.
		306
11	=cut	307	=cut
12		308
13	package AnyEvent;	309	package AnyEvent;
14		310
		311	no warnings;
		312	use strict;
		313
15	use Carp;	314	use Carp;
16		315
17	$VERSION = 0.1;	316	our $VERSION = '3.0';
		317	our $MODEL;
18		318
19	no warnings;	319	our $AUTOLOAD;
		320	our @ISA;
		321
		322	our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
		323
		324	our @REGISTRY;
20		325
21	my @models = (	326	my @models = (
22	[Coro => Coro::Event::],	327	[Coro::EV:: => AnyEvent::Impl::CoroEV::],
23	[Event => Event::],	328	[EV:: => AnyEvent::Impl::EV::],
24	[Glib => Glib::],	329	[Coro::Event:: => AnyEvent::Impl::CoroEvent::],
25	[Tk => Tk::],	330	[Event:: => AnyEvent::Impl::Event::],
		331	[Glib:: => AnyEvent::Impl::Glib::],
		332	[Tk:: => AnyEvent::Impl::Tk::],
		333	[AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
26	);	334	);
27		335
		336	our %method = map +($_ => 1), qw(io timer condvar broadcast wait signal one_event DESTROY);
		337
		338	sub detect() {
		339	unless ($MODEL) {
		340	no strict 'refs';
		341
		342	# check for already loaded models
		343	for (@REGISTRY, @models) {
		344	my ($package, $model) = @$_;
		345	if (${"$package\::VERSION"} > 0) {
		346	if (eval "require $model") {
		347	$MODEL = $model;
		348	warn "AnyEvent: found model '$model', using it.\n" if $verbose > 1;
		349	last;
		350	}
		351	}
		352	}
		353
		354	unless ($MODEL) {
		355	# try to load a model
		356
		357	for (@REGISTRY, @models) {
		358	my ($package, $model) = @$_;
		359	if (eval "require $package"
		360	and ${"$package\::VERSION"} > 0
		361	and eval "require $model") {
		362	$MODEL = $model;
		363	warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
		364	last;
		365	}
		366	}
		367
		368	$MODEL
		369	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.";
		370	}
		371
		372	unshift @ISA, $MODEL;
		373	push @{"$MODEL\::ISA"}, "AnyEvent::Base";
		374	}
		375
		376	$MODEL
		377	}
		378
28	sub AUTOLOAD {	379	sub AUTOLOAD {
29	$AUTOLOAD =~ s/.*://;	380	(my $func = $AUTOLOAD) =~ s/.*://;
30		381
31	for (@models) {	382	$method{$func}
32	my ($model, $package) = @$_;	383	or croak "$func: not a valid method for AnyEvent objects";
33	if (defined ${"$package\::VERSION"}) {	384
34	$EVENT = "AnyEvent::Impl::$model";	385	detect unless $MODEL;
35	eval "require $EVENT"; die if $@;	386
36	goto &{"$EVENT\::$AUTOLOAD"};	387	my $class = shift;
37	}	388	$class->$func (@_);
		389	}
		390
		391	package AnyEvent::Base;
		392
		393	# default implementation for ->condvar, ->wait, ->broadcast
		394
		395	sub condvar {
		396	bless \my $flag, "AnyEvent::Base::CondVar"
		397	}
		398
		399	sub AnyEvent::Base::CondVar::broadcast {
		400	${$_[0]}++;
		401	}
		402
		403	sub AnyEvent::Base::CondVar::wait {
		404	AnyEvent->one_event while !${$_[0]};
		405	}
		406
		407	# default implementation for ->signal
		408
		409	our %SIG_CB;
		410
		411	sub signal {
		412	my (undef, %arg) = @_;
		413
		414	my $signal = uc $arg{signal}
		415	or Carp::croak "required option 'signal' is missing";
		416
		417	$SIG_CB{$signal}{$arg{cb}} = $arg{cb};
		418	$SIG{$signal} \|\|= sub {
		419	$_->() for values %{ $SIG_CB{$signal} \|\| {} };
		420	};
		421
		422	bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"
		423	}
		424
		425	sub AnyEvent::Base::Signal::DESTROY {
		426	my ($signal, $cb) = @{$_[0]};
		427
		428	delete $SIG_CB{$signal}{$cb};
		429
		430	$SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} };
		431	}
		432
		433	# default implementation for ->child
		434
		435	our %PID_CB;
		436	our $CHLD_W;
		437	our $CHLD_DELAY_W;
		438	our $PID_IDLE;
		439	our $WNOHANG;
		440
		441	sub _child_wait {
		442	while (0 < (my $pid = waitpid -1, $WNOHANG)) {
		443	$_->($pid, $?) for (values %{ $PID_CB{$pid} \|\| {} }),
		444	(values %{ $PID_CB{0} \|\| {} });
38	}	445	}
39		446
40	for (@models) {	447	undef $PID_IDLE;
41	my ($model, $package) = @$_;	448	}
42	$EVENT = "AnyEvent::Impl::$model";	449
43	if (eval "require $EVENT") {	450	sub _sigchld {
44	goto &{"$EVENT\::$AUTOLOAD"};	451	# make sure we deliver these changes "synchronous" with the event loop.
45	}	452	$CHLD_DELAY_W \|\|= AnyEvent->timer (after => 0, cb => sub {
		453	undef $CHLD_DELAY_W;
		454	&_child_wait;
		455	});
		456	}
		457
		458	sub child {
		459	my (undef, %arg) = @_;
		460
		461	defined (my $pid = $arg{pid} + 0)
		462	or Carp::croak "required option 'pid' is missing";
		463
		464	$PID_CB{$pid}{$arg{cb}} = $arg{cb};
		465
		466	unless ($WNOHANG) {
		467	$WNOHANG = eval { require POSIX; &POSIX::WNOHANG } \|\| 1;
46	}	468	}
47		469
48	die "No event module selected for AnyEvent and autodetect failed. Install any of these: Coro, Event, Glib or Tk.";	470	unless ($CHLD_W) {
49	}	471	$CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld);
		472	# child could be a zombie already, so make at least one round
		473	&_sigchld;
		474	}
50		475
51	1;	476	bless [$pid, $arg{cb}], "AnyEvent::Base::Child"
		477	}
52		478
		479	sub AnyEvent::Base::Child::DESTROY {
		480	my ($pid, $cb) = @{$_[0]};
		481
		482	delete $PID_CB{$pid}{$cb};
		483	delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} };
		484
		485	undef $CHLD_W unless keys %PID_CB;
		486	}
		487
		488	=head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE
		489
		490	If you need to support another event library which isn't directly
		491	supported by AnyEvent, you can supply your own interface to it by
		492	pushing, before the first watcher gets created, the package name of
		493	the event module and the package name of the interface to use onto
		494	C<@AnyEvent::REGISTRY>. You can do that before and even without loading
		495	AnyEvent.
		496
		497	Example:
		498
		499	push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
		500
		501	This tells AnyEvent to (literally) use the C<urxvt::anyevent::>
		502	package/class when it finds the C<urxvt> package/module is loaded. When
		503	AnyEvent is loaded and asked to find a suitable event model, it will
		504	first check for the presence of urxvt.
		505
		506	The class should provide implementations for all watcher types (see
		507	L<AnyEvent::Impl::Event> (source code), L<AnyEvent::Impl::Glib>
		508	(Source code) and so on for actual examples, use C<perldoc -m
		509	AnyEvent::Impl::Glib> to see the sources).
		510
		511	The above isn't fictitious, the I<rxvt-unicode> (a.k.a. urxvt)
		512	uses the above line as-is. An interface isn't included in AnyEvent
		513	because it doesn't make sense outside the embedded interpreter inside
		514	I<rxvt-unicode>, and it is updated and maintained as part of the
		515	I<rxvt-unicode> distribution.
		516
		517	I<rxvt-unicode> also cheats a bit by not providing blocking access to
		518	condition variables: code blocking while waiting for a condition will
		519	C<die>. This still works with most modules/usages, and blocking calls must
		520	not be in an interactive application, so it makes sense.
		521
		522	=head1 ENVIRONMENT VARIABLES
		523
		524	The following environment variables are used by this module:
		525
		526	C<PERL_ANYEVENT_VERBOSE> when set to C<2> or higher, reports which event
		527	model gets used.
		528
		529	=head1 EXAMPLE
		530
		531	The following program uses an io watcher to read data from stdin, a timer
		532	to display a message once per second, and a condvar to exit the program
		533	when the user enters quit:
		534
		535	use AnyEvent;
		536
		537	my $cv = AnyEvent->condvar;
		538
		539	my $io_watcher = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
		540	warn "io event <$_[0]>\n"; # will always output <r>
		541	chomp (my $input = <STDIN>); # read a line
		542	warn "read: $input\n"; # output what has been read
		543	$cv->broadcast if $input =~ /^q/i; # quit program if /^q/i
		544	});
		545
		546	my $time_watcher; # can only be used once
		547
		548	sub new_timer {
		549	$timer = AnyEvent->timer (after => 1, cb => sub {
		550	warn "timeout\n"; # print 'timeout' about every second
		551	&new_timer; # and restart the time
		552	});
		553	}
		554
		555	new_timer; # create first timer
		556
		557	$cv->wait; # wait until user enters /^q/i
		558
		559	=head1 REAL-WORLD EXAMPLE
		560
		561	Consider the L<Net::FCP> module. It features (among others) the following
		562	API calls, which are to freenet what HTTP GET requests are to http:
		563
		564	my $data = $fcp->client_get ($url); # blocks
		565
		566	my $transaction = $fcp->txn_client_get ($url); # does not block
		567	$transaction->cb ( sub { ... } ); # set optional result callback
		568	my $data = $transaction->result; # possibly blocks
		569
		570	The C<client_get> method works like C<LWP::Simple::get>: it requests the
		571	given URL and waits till the data has arrived. It is defined to be:
		572
		573	sub client_get { $_[0]->txn_client_get ($_[1])->result }
		574
		575	And in fact is automatically generated. This is the blocking API of
		576	L<Net::FCP>, and it works as simple as in any other, similar, module.
		577
		578	More complicated is C<txn_client_get>: It only creates a transaction
		579	(completion, result, ...) object and initiates the transaction.
		580
		581	my $txn = bless { }, Net::FCP::Txn::;
		582
		583	It also creates a condition variable that is used to signal the completion
		584	of the request:
		585
		586	$txn->{finished} = AnyAvent->condvar;
		587
		588	It then creates a socket in non-blocking mode.
		589
		590	socket $txn->{fh}, ...;
		591	fcntl $txn->{fh}, F_SETFL, O_NONBLOCK;
		592	connect $txn->{fh}, ...
		593	and !$!{EWOULDBLOCK}
		594	and !$!{EINPROGRESS}
		595	and Carp::croak "unable to connect: $!\n";
		596
		597	Then it creates a write-watcher which gets called whenever an error occurs
		598	or the connection succeeds:
		599
		600	$txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'w', cb => sub { $txn->fh_ready_w });
		601
		602	And returns this transaction object. The C<fh_ready_w> callback gets
		603	called as soon as the event loop detects that the socket is ready for
		604	writing.
		605
		606	The C<fh_ready_w> method makes the socket blocking again, writes the
		607	request data and replaces the watcher by a read watcher (waiting for reply
		608	data). The actual code is more complicated, but that doesn't matter for
		609	this example:
		610
		611	fcntl $txn->{fh}, F_SETFL, 0;
		612	syswrite $txn->{fh}, $txn->{request}
		613	or die "connection or write error";
		614	$txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
		615
		616	Again, C<fh_ready_r> waits till all data has arrived, and then stores the
		617	result and signals any possible waiters that the request ahs finished:
		618
		619	sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
		620
		621	if (end-of-file or data complete) {
		622	$txn->{result} = $txn->{buf};
		623	$txn->{finished}->broadcast;
		624	$txb->{cb}->($txn) of $txn->{cb}; # also call callback
		625	}
		626
		627	The C<result> method, finally, just waits for the finished signal (if the
		628	request was already finished, it doesn't wait, of course, and returns the
		629	data:
		630
		631	$txn->{finished}->wait;
		632	return $txn->{result};
		633
		634	The actual code goes further and collects all errors (C<die>s, exceptions)
		635	that occured during request processing. The C<result> method detects
		636	wether an exception as thrown (it is stored inside the $txn object)
		637	and just throws the exception, which means connection errors and other
		638	problems get reported tot he code that tries to use the result, not in a
		639	random callback.
		640
		641	All of this enables the following usage styles:
		642
		643	1. Blocking:
		644
		645	my $data = $fcp->client_get ($url);
		646
		647	2. Blocking, but parallelizing:
		648
		649	my @datas = map $_->result,
		650	map $fcp->txn_client_get ($_),
		651	@urls;
		652
		653	Both blocking examples work without the module user having to know
		654	anything about events.
		655
		656	3a. Event-based in a main program, using any support Event module:
		657
		658	use Event;
		659
		660	$fcp->txn_client_get ($url)->cb (sub {
		661	my $txn = shift;
		662	my $data = $txn->result;
		663	...
		664	});
		665
		666	Event::loop;
		667
		668	3b. The module user could use AnyEvent, too:
		669
		670	use AnyEvent;
		671
		672	my $quit = AnyEvent->condvar;
		673
		674	$fcp->txn_client_get ($url)->cb (sub {
		675	...
		676	$quit->broadcast;
		677	});
		678
		679	$quit->wait;
		680
		681	=head1 SEE ALSO
		682
		683	Event modules: L<Coro::Event>, L<Coro>, L<Event>, L<Glib::Event>, L<Glib>.
		684
		685	Implementations: L<AnyEvent::Impl::Coro>, L<AnyEvent::Impl::Event>, L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>.
		686
		687	Nontrivial usage example: L<Net::FCP>.
		688
		689	=head1
		690
		691	=cut
		692
		693	1
		694

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.1 by root, Wed Apr 27 01:26:44 2005 UTC vs. Revision 1.48 by root, Mon Apr 14 19:00:23 2008 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.1 by root, Wed Apr 27 01:26:44 2005 UTC vs.
Revision 1.48 by root, Mon Apr 14 19:00:23 2008 UTC