[ViewVC] Diff of: cvs/cvsroot/Coro/Coro.pm

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.222 by root, Tue Nov 18 08:59:46 2008 UTC vs.
Revision 1.225 by root, Wed Nov 19 15:29:57 2008 UTC

…		…
305	>> on that once some event happens, and last you call C<schedule> to put	305	>> on that once some event happens, and last you call C<schedule> to put
306	yourself to sleep. Note that a lot of things can wake your coroutine up,	306	yourself to sleep. Note that a lot of things can wake your coroutine up,
307	so you need to check whether the event indeed happened, e.g. by storing the	307	so you need to check whether the event indeed happened, e.g. by storing the
308	status in a variable.	308	status in a variable.
309		309
310	The canonical way to wait on external events is this:	310	See B<HOW TO WAIT FOR A CALLBACK>, below, for some ways to wait for callbacks.
311
312	{
313	# remember current coroutine
314	my $current = $Coro::current;
315
316	# register a hypothetical event handler
317	on_event_invoke sub {
318	# wake up sleeping coroutine
319	$current->ready;
320	undef $current;
321	};
322
323	# call schedule until event occurred.
324	# in case we are woken up for other reasons
325	# (current still defined), loop.
326	Coro::schedule while $current;
327	}
328		311
329	=item cede	312	=item cede
330		313
331	"Cede" to other coroutines. This function puts the current coroutine into	314	"Cede" to other coroutines. This function puts the current coroutine into
332	the ready queue and calls C<schedule>, which has the effect of giving	315	the ready queue and calls C<schedule>, which has the effect of giving
…		…
388	See C<async> and C<Coro::State::new> for additional info about the	371	See C<async> and C<Coro::State::new> for additional info about the
389	coroutine environment.	372	coroutine environment.
390		373
391	=cut	374	=cut
392		375
393	sub _run_coro {	376	sub _terminate {
394	terminate &{+shift};	377	terminate &{+shift};
395	}
396
397	sub new {
398	my $class = shift;
399
400	$class->SUPER::new (\&_run_coro, @_)
401	}	378	}
402		379
403	=item $success = $coroutine->ready	380	=item $success = $coroutine->ready
404		381
405	Put the given coroutine into the end of its ready queue (there is one	382	Put the given coroutine into the end of its ready queue (there is one
…		…
441	inside the coroutine at the next convenient point in time. Otherwise	418	inside the coroutine at the next convenient point in time. Otherwise
442	clears the exception object.	419	clears the exception object.
443		420
444	Coro will check for the exception each time a schedule-like-function	421	Coro will check for the exception each time a schedule-like-function
445	returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down	422	returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down
446	>>, C<< Coro::Handle->readable >> and so on. Note that this means that	423	>>, C<< Coro::Handle->readable >> and so on. Most of these functions
447	when a coroutine is acquiring a lock, it might only throw after it has	424	detect this case and return early in case an exception is pending.
448	sucessfully acquired it.
449		425
450	The exception object will be thrown "as is" with the specified scalar in	426	The exception object will be thrown "as is" with the specified scalar in
451	C<$@>, i.e. if it is a string, no line number or newline will be appended	427	C<$@>, i.e. if it is a string, no line number or newline will be appended
452	(unlike with C<die>).	428	(unlike with C<die>).
453		429
…		…
654	unshift @unblock_queue, [$cb, @_];	630	unshift @unblock_queue, [$cb, @_];
655	$unblock_scheduler->ready;	631	$unblock_scheduler->ready;
656	}	632	}
657	}	633	}
658		634
		635	=item $cb = Coro::rouse_cb
		636
		637	Create and return a "rouse callback". That's a code reference that, when
		638	called, will save its arguments and notify the owner coroutine of the
		639	callback.
		640
		641	See the next function.
		642
		643	=item @args = Coro::rouse_wait [$cb]
		644
		645	Wait for the specified rouse callback (or the last one tht was created in
		646	this coroutine).
		647
		648	As soon as the callback is invoked (or when the calback was invoked before
		649	C<rouse_wait>), it will return a copy of the arguments originally passed
		650	to the rouse callback.
		651
		652	See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
		653
659	=back	654	=back
660		655
661	=cut	656	=cut
662		657
663	1;	658	1;
		659
		660	=head1 HOW TO WAIT FOR A CALLBACK
		661
		662	It is very common for a coroutine to wait for some callback to be
		663	called. This occurs naturally when you use coroutines in an otherwise
		664	event-based program, or when you use event-based libraries.
		665
		666	These typically register a callback for some event, and call that callback
		667	when the event occured. In a coroutine, however, you typically want to
		668	just wait for the event, simplyifying things.
		669
		670	For example C<< AnyEvent->child >> registers a callback to be called when
		671	a specific child has exited:
		672
		673	my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
		674
		675	But from withina coroutine, you often just want to write this:
		676
		677	my $status = wait_for_child $pid;
		678
		679	Coro offers two functions specifically designed to make this easy,
		680	C<Coro::rouse_cb> and C<Coro::rouse_wait>.
		681
		682	The first function, C<rouse_cb>, generates and returns a callback that,
		683	when invoked, will save it's arguments and notify the coroutine that
		684	created the callback.
		685
		686	The second function, C<rouse_wait>, waits for the callback to be called
		687	(by calling C<schedule> to go to sleep) and returns the arguments
		688	originally passed to the callback.
		689
		690	Using these functions, it becomes easy to write the C<wait_for_child>
		691	function mentioned above:
		692
		693	sub wait_for_child($) {
		694	my ($pid) = @_;
		695
		696	my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb);
		697
		698	my ($rpid, $rstatus) = Coro::rouse_wait;
		699	$rstatus
		700	}
		701
		702	In the case where C<rouse_cb> and C<rouse_wait> are not flexible enough,
		703	you can roll your own, using C<schedule>:
		704
		705	sub wait_for_child($) {
		706	my ($pid) = @_;
		707
		708	# store the current coroutine in $current,
		709	# and provide result variables for the closure passed to ->child
		710	my $current = $Coro::current;
		711	my ($done, $rstatus);
		712
		713	# pass a closure to ->child
		714	my $watcher = AnyEvent->child (pid => $pid, cb => sub {
		715	$rstatus = $_[1]; # remember rstatus
		716	$done = 1; # mark $rstatus as valud
		717	});
		718
		719	# wait until the closure has been called
		720	schedule while !$done;
		721
		722	$rstatus
		723	}
		724
664		725
665	=head1 BUGS/LIMITATIONS	726	=head1 BUGS/LIMITATIONS
666		727
667	=over 4	728	=over 4
668		729

Diff Legend

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

Comparing cvsroot/Coro/Coro.pm (file contents): Revision 1.222 by root, Tue Nov 18 08:59:46 2008 UTC vs. Revision 1.225 by root, Wed Nov 19 15:29:57 2008 UTC

Diff Legend

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.222 by root, Tue Nov 18 08:59:46 2008 UTC vs.
Revision 1.225 by root, Wed Nov 19 15:29:57 2008 UTC