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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.104 by root, Wed Apr 30 11:40:22 2008 UTC vs.
Revision 1.105 by root, Thu May 1 12:35:54 2008 UTC

…		…
297	# do something else, then wait for process exit	297	# do something else, then wait for process exit
298	$done->wait;	298	$done->wait;
299		299
300	=head2 CONDITION VARIABLES	300	=head2 CONDITION VARIABLES
301		301
		302	If you are familiar with some event loops you will know that all of them
		303	require you to run some blocking "loop", "run" or similar function that
		304	will actively watch for new events and call your callbacks.
		305
		306	AnyEvent is different, it expects somebody else to run the event loop and
		307	will only block when necessary (usually when told by the user).
		308
		309	The instrument to do that is called a "condition variable", so called
		310	because they represent a condition that must become true.
		311
302	Condition variables can be created by calling the C<< AnyEvent->condvar >>	312	Condition variables can be created by calling the C<< AnyEvent->condvar
303	method without any arguments.	313	>> method, usually without arguments. The only argument pair allowed is
		314	C<cb>, which specifies a callback to be called when the condition variable
		315	becomes true.
304		316
305	A condition variable waits for a condition - precisely that the C<<	317	After creation, the conditon variable is "false" until it becomes "true"
306	->broadcast >> method has been called.	318	by calling the C<broadcast> method.
307		319
308	They are very useful to signal that a condition has been fulfilled, for	320	Condition variables are similar to callbacks, except that you can
		321	optionally wait for them. They can also be called merge points - points
		322	in time where multiple outstandign events have been processed. And yet
		323	another way to call them is transations - each condition variable can be
		324	used to represent a transaction, which finishes at some point and delivers
		325	a result.
		326
		327	Condition variables are very useful to signal that something has finished,
309	example, if you write a module that does asynchronous http requests,	328	for example, if you write a module that does asynchronous http requests,
310	then a condition variable would be the ideal candidate to signal the	329	then a condition variable would be the ideal candidate to signal the
311	availability of results.	330	availability of results. The user can either act when the callback is
		331	called or can synchronously C<< ->wait >> for the results.
312		332
313	You can also use condition variables to block your main program until	333	You can also use them to simulate traditional event loops - for example,
314	an event occurs - for example, you could C<< ->wait >> in your main	334	you can block your main program until an event occurs - for example, you
315	program until the user clicks the Quit button in your app, which would C<<	335	could C<< ->wait >> in your main program until the user clicks the Quit
316	->broadcast >> the "quit" event.	336	button of your app, which would C<< ->broadcast >> the "quit" event.
317		337
318	Note that condition variables recurse into the event loop - if you have	338	Note that condition variables recurse into the event loop - if you have
319	two pirces of code that call C<< ->wait >> in a round-robbin fashion, you	339	two pieces of code that call C<< ->wait >> in a round-robbin fashion, you
320	lose. Therefore, condition variables are good to export to your caller, but	340	lose. Therefore, condition variables are good to export to your caller, but
321	you should avoid making a blocking wait yourself, at least in callbacks,	341	you should avoid making a blocking wait yourself, at least in callbacks,
322	as this asks for trouble.	342	as this asks for trouble.
323		343
324	This object has two methods:	344	Condition variables are represented by hash refs in perl, and the keys
		345	used by AnyEvent itself are all named C<_ae_XXX> to make subclassing
		346	easy (it is often useful to build your own transaction class on top of
		347	AnyEvent). To subclass, use C<AnyEvent::CondVar> as base class and call
		348	it's C<new> method in your own C<new> method.
325		349
326	=over 4	350	There are two "sides" to a condition variable - the "producer side" which
327		351	eventually calls C<< -> broadcast >>, and the "consumer side", which waits
328	=item $cv->wait	352	for the broadcast to occur.
329
330	Wait (blocking if necessary) until the C<< ->broadcast >> method has been
331	called on c<$cv>, while servicing other watchers normally.
332
333	You can only wait once on a condition - additional calls will return
334	immediately.
335
336	Not all event models support a blocking wait - some die in that case
337	(programs might want to do that to stay interactive), so I<if you are
338	using this from a module, never require a blocking wait>, but let the
339	caller decide whether the call will block or not (for example, by coupling
340	condition variables with some kind of request results and supporting
341	callbacks so the caller knows that getting the result will not block,
342	while still suppporting blocking waits if the caller so desires).
343
344	Another reason I<never> to C<< ->wait >> in a module is that you cannot
345	sensibly have two C<< ->wait >>'s in parallel, as that would require
346	multiple interpreters or coroutines/threads, none of which C<AnyEvent>
347	can supply (the coroutine-aware backends L<AnyEvent::Impl::CoroEV> and
348	L<AnyEvent::Impl::CoroEvent> explicitly support concurrent C<< ->wait >>'s
349	from different coroutines, however).
350
351	=item $cv->broadcast
352
353	Flag the condition as ready - a running C<< ->wait >> and all further
354	calls to C<wait> will (eventually) return after this method has been
355	called. If nobody is waiting the broadcast will be remembered..
356
357	=back
358		353
359	Example:	354	Example:
360		355
361	# wait till the result is ready	356	# wait till the result is ready
362	my $result_ready = AnyEvent->condvar;	357	my $result_ready = AnyEvent->condvar;
…		…
368	my $w = AnyEvent->timer (	363	my $w = AnyEvent->timer (
369	after => 1,	364	after => 1,
370	cb => sub { $result_ready->broadcast },	365	cb => sub { $result_ready->broadcast },
371	);	366	);
372		367
373	# this "blocks" (while handling events) till the watcher	368	# this "blocks" (while handling events) till the callback
374	# calls broadcast	369	# calls broadcast
375	$result_ready->wait;	370	$result_ready->wait;
		371
		372	=head3 METHODS FOR PRODUCERS
		373
		374	These methods should only be used by the producing side, i.e. the
		375	code/module that eventually broadcasts the signal. Note that it is also
		376	the producer side which creates the condvar in most cases, but it isn't
		377	uncommon for the consumer to create it as well.
		378
		379	=over 4
		380
		381	=item $cv->broadcast (...)
		382
		383	Flag the condition as ready - a running C<< ->wait >> and all further
		384	calls to C<wait> will (eventually) return after this method has been
		385	called. If nobody is waiting the broadcast will be remembered.
		386
		387	If a callback has been set on the condition variable, it is called
		388	immediately from within broadcast.
		389
		390	Any arguments passed to the C<broadcast> call will be returned by all
		391	future C<< ->wait >> calls.
		392
		393	=item $cv->croak ($error)
		394
		395	Similar to broadcast, but causes all call's wait C<< ->wait >> to invoke
		396	C<Carp::croak> with the given error message/object/scalar.
		397
		398	This can be used to signal any errors to the condition variable
		399	user/consumer.
		400
		401	=item $cv->begin ([group callback])
		402
		403	=item $cv->end
		404
		405	These two methods can be used to combine many transactions/events into
		406	one. For example, a function that pings many hosts in parallel might want
		407	to use a condition variable for the whole process.
		408
		409	Every call to C<< ->begin >> will increment a counter, and every call to
		410	C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end
		411	>>, the (last) callback passed to C<begin> will be executed. That callback
		412	is I<supposed> to call C<< ->broadcast >>, but that is not required. If no
		413	callback was set, C<broadcast> will be called without any arguments.
		414
		415	Let's clarify this with the ping example:
		416
		417	my $cv = AnyEvent->condvar;
		418
		419	my %result;
		420	$cv->begin (sub { $cv->broadcast (\%result) });
		421
		422	for my $host (@list_of_hosts) {
		423	$cv->begin;
		424	ping_host_then_call_callback $host, sub {
		425	$result{$host} = ...;
		426	$cv->end;
		427	};
		428	}
		429
		430	$cv->end;
		431
		432	This code fragment supposedly pings a number of hosts and calls
		433	C<broadcast> after results for all then have have been gathered - in any
		434	order. To achieve this, the code issues a call to C<begin> when it starts
		435	each ping request and calls C<end> when it has received some result for
		436	it. Since C<begin> and C<end> only maintain a counter, the order in which
		437	results arrive is not relevant.
		438
		439	There is an additional bracketing call to C<begin> and C<end> outside the
		440	loop, which serves two important purposes: first, it sets the callback
		441	to be called once the counter reaches C<0>, and second, it ensures that
		442	broadcast is called even when C<no> hosts are being pinged (the loop
		443	doesn't execute once).
		444
		445	This is the general pattern when you "fan out" into multiple subrequests:
		446	use an outer C<begin>/C<end> pair to set the callback and ensure C<end>
		447	is called at least once, and then, for each subrequest you start, call
		448	C<begin> and for eahc subrequest you finish, call C<end>.
		449
		450	=back
		451
		452	=head3 METHODS FOR CONSUMERS
		453
		454	These methods should only be used by the consuming side, i.e. the
		455	code awaits the condition.
		456
		457	=item $cv->wait
		458
		459	Wait (blocking if necessary) until the C<< ->broadcast >> or C<< ->croak
		460	>> methods have been called on c<$cv>, while servicing other watchers
		461	normally.
		462
		463	You can only wait once on a condition - additional calls are valid but
		464	will return immediately.
		465
		466	If an error condition has been set by calling C<< ->croak >>, then this
		467	function will call C<croak>.
		468
		469	In list context, all parameters passed to C<broadcast> will be returned,
		470	in scalar context only the first one will be returned.
		471
		472	Not all event models support a blocking wait - some die in that case
		473	(programs might want to do that to stay interactive), so I<if you are
		474	using this from a module, never require a blocking wait>, but let the
		475	caller decide whether the call will block or not (for example, by coupling
		476	condition variables with some kind of request results and supporting
		477	callbacks so the caller knows that getting the result will not block,
		478	while still suppporting blocking waits if the caller so desires).
		479
		480	Another reason I<never> to C<< ->wait >> in a module is that you cannot
		481	sensibly have two C<< ->wait >>'s in parallel, as that would require
		482	multiple interpreters or coroutines/threads, none of which C<AnyEvent>
		483	can supply (the coroutine-aware backends L<AnyEvent::Impl::CoroEV> and
		484	L<AnyEvent::Impl::CoroEvent> explicitly support concurrent C<< ->wait >>'s
		485	from different coroutines, however).
		486
		487	You can ensure that C<< -wait >> never blocks by setting a callback and
		488	only calling C<< ->wait >> from within that callback (or at a later
		489	time). This will work even when the event loop does not support blocking
		490	waits otherwise.
		491
		492	=back
376		493
377	=head1 GLOBAL VARIABLES AND FUNCTIONS	494	=head1 GLOBAL VARIABLES AND FUNCTIONS
378		495
379	=over 4	496	=over 4
380		497

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.104 by root, Wed Apr 30 11:40:22 2008 UTC vs. Revision 1.105 by root, Thu May 1 12:35:54 2008 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.104 by root, Wed Apr 30 11:40:22 2008 UTC vs.
Revision 1.105 by root, Thu May 1 12:35:54 2008 UTC