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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.220 by root, Sun Nov 16 11:12:57 2008 UTC vs.
Revision 1.224 by root, Wed Nov 19 05:52:42 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
…		…
436	}	419	}
437		420
438	=item $coroutine->throw ([$scalar])	421	=item $coroutine->throw ([$scalar])
439		422
440	If C<$throw> is specified and defined, it will be thrown as an exception	423	If C<$throw> is specified and defined, it will be thrown as an exception
441	inside the coroutine at the next convenient point in time (usually after	424	inside the coroutine at the next convenient point in time. Otherwise
442	it gains control at the next schedule/transfer/cede). Otherwise clears the
443	exception object.	425	clears the exception object.
		426
		427	Coro will check for the exception each time a schedule-like-function
		428	returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down
		429	>>, C<< Coro::Handle->readable >> and so on. Most of these functions
		430	detect this case and return early in case an exception is pending.
444		431
445	The exception object will be thrown "as is" with the specified scalar in	432	The exception object will be thrown "as is" with the specified scalar in
446	C<$@>, i.e. if it is a string, no line number or newline will be appended	433	C<$@>, i.e. if it is a string, no line number or newline will be appended
447	(unlike with C<die>).	434	(unlike with C<die>).
448		435
…		…
649	unshift @unblock_queue, [$cb, @_];	636	unshift @unblock_queue, [$cb, @_];
650	$unblock_scheduler->ready;	637	$unblock_scheduler->ready;
651	}	638	}
652	}	639	}
653		640
		641	=item $cb = Coro::rouse_cb
		642
		643	Create and return a "rouse callback". That's a code reference that, when
		644	called, will save its arguments and notify the owner coroutine of the
		645	callback.
		646
		647	See the next function.
		648
		649	=item @args = Coro::rouse_wait [$cb]
		650
		651	Wait for the specified rouse callback (or the last one tht was created in
		652	this coroutine).
		653
		654	As soon as the callback is invoked (or when the calback was invoked before
		655	C<rouse_wait>), it will return a copy of the arguments originally passed
		656	to the rouse callback.
		657
		658	See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
		659
654	=back	660	=back
655		661
656	=cut	662	=cut
657		663
658	1;	664	1;
		665
		666	=head1 HOW TO WAIT FOR A CALLBACK
		667
		668	It is very common for a coroutine to wait for some callback to be
		669	called. This occurs naturally when you use coroutines in an otherwise
		670	event-based program, or when you use event-based libraries.
		671
		672	These typically register a callback for some event, and call that callback
		673	when the event occured. In a coroutine, however, you typically want to
		674	just wait for the event, simplyifying things.
		675
		676	For example C<< AnyEvent->child >> registers a callback to be called when
		677	a specific child has exited:
		678
		679	my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
		680
		681	But from withina coroutine, you often just want to write this:
		682
		683	my $status = wait_for_child $pid;
		684
		685	Coro offers two functions specifically designed to make this easy,
		686	C<Coro::rouse_cb> and C<Coro::rouse_wait>.
		687
		688	The first function, C<rouse_cb>, generates and returns a callback that,
		689	when invoked, will save it's arguments and notify the coroutine that
		690	created the callback.
		691
		692	The second function, C<rouse_wait>, waits for the callback to be called
		693	(by calling C<schedule> to go to sleep) and returns the arguments
		694	originally passed to the callback.
		695
		696	Using these functions, it becomes easy to write the C<wait_for_child>
		697	function mentioned above:
		698
		699	sub wait_for_child($) {
		700	my ($pid) = @_;
		701
		702	my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb);
		703
		704	my ($rpid, $rstatus) = Coro::rouse_wait;
		705	$rstatus
		706	}
		707
		708	In the case where C<rouse_cb> and C<rouse_wait> are not flexible enough,
		709	you can roll your own, using C<schedule>:
		710
		711	sub wait_for_child($) {
		712	my ($pid) = @_;
		713
		714	# store the current coroutine in $current,
		715	# and provide result variables for the closure passed to ->child
		716	my $current = $Coro::current;
		717	my ($done, $rstatus);
		718
		719	# pass a closure to ->child
		720	my $watcher = AnyEvent->child (pid => $pid, cb => sub {
		721	$rstatus = $_[1]; # remember rstatus
		722	$done = 1; # mark $rstatus as valud
		723	});
		724
		725	# wait until the closure has been called
		726	schedule while !$done;
		727
		728	$rstatus
		729	}
		730
659		731
660	=head1 BUGS/LIMITATIONS	732	=head1 BUGS/LIMITATIONS
661		733
662	=over 4	734	=over 4
663		735
…		…
680	=item coroutine switching not signal safe	752	=item coroutine switching not signal safe
681		753
682	You must not switch to another coroutine from within a signal handler	754	You must not switch to another coroutine from within a signal handler
683	(only relevant with %SIG - most event libraries provide safe signals).	755	(only relevant with %SIG - most event libraries provide safe signals).
684		756
685	That means you I<MUST NOT> call any fucntion that might "block" the	757	That means you I<MUST NOT> call any function that might "block" the
686	current coroutine - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or	758	current coroutine - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
687	anything that calls those. Everything else, including calling C<ready>,	759	anything that calls those. Everything else, including calling C<ready>,
688	works.	760	works.
689		761
690	=back	762	=back

Diff Legend

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

Comparing cvsroot/Coro/Coro.pm (file contents): Revision 1.220 by root, Sun Nov 16 11:12:57 2008 UTC vs. Revision 1.224 by root, Wed Nov 19 05:52:42 2008 UTC

Diff Legend

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.220 by root, Sun Nov 16 11:12:57 2008 UTC vs.
Revision 1.224 by root, Wed Nov 19 05:52:42 2008 UTC