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

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

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.4 by root, Thu Dec 1 22:04:50 2005 UTC vs. Revision 1.42 by root, Mon Apr 7 19:40:12 2008 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.4 by root, Thu Dec 1 22:04:50 2005 UTC vs.
Revision 1.42 by root, Mon Apr 7 19:40:12 2008 UTC