ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Coro/Coro.pm
(Generate patch)

Comparing Coro/Coro.pm (file contents):
Revision 1.143 by root, Tue Oct 2 23:27:52 2007 UTC vs.
Revision 1.152 by root, Sun Oct 7 13:53:37 2007 UTC

… …
6 6
7 use Coro; 7 use Coro;
8 8
9 async { 9 async {
10 # some asynchronous thread of execution 10 # some asynchronous thread of execution
11 print "2\n";
12 cede; # yield back to main
13 print "4\n";
11 }; 14 };
15 print "1\n";
16 cede; # yield to coroutine
17 print "3\n";
18 cede; # and again
12 19
13 # alternatively create an async coroutine like this: 20 # use locking
21 my $lock = new Coro::Semaphore;
22 my $locked;
14 23
15 sub some_func : Coro { 24 $lock->down;
16 # some more async code 25 $locked = 1;
17 } 26 $lock->up;
18
19 cede;
20 27
21=head1 DESCRIPTION 28=head1 DESCRIPTION
22 29
23This module collection manages coroutines. Coroutines are similar 30This module collection manages coroutines. Coroutines are similar
24to threads but don't run in parallel at the same time even on SMP 31to threads but don't run in parallel at the same time even on SMP
… …
33is a performance win on Windows machines, and a loss everywhere else). 40is a performance win on Windows machines, and a loss everywhere else).
34 41
35In this module, coroutines are defined as "callchain + lexical variables + 42In this module, coroutines are defined as "callchain + lexical variables +
36@_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own callchain, 43@_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own callchain,
37its own set of lexicals and its own set of perls most important global 44its own set of lexicals and its own set of perls most important global
38variables. 45variables (see L<Coro::State> for more configuration).
39 46
40=cut 47=cut
41 48
42package Coro; 49package Coro;
43 50
… …
50 57
51our $idle; # idle handler 58our $idle; # idle handler
52our $main; # main coroutine 59our $main; # main coroutine
53our $current; # current coroutine 60our $current; # current coroutine
54 61
55our $VERSION = '3.8'; 62our $VERSION = '4.1';
56 63
57our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 64our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
58our %EXPORT_TAGS = ( 65our %EXPORT_TAGS = (
59 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 66 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
60); 67);
… …
134This hook is overwritten by modules such as C<Coro::Timer> and 141This hook is overwritten by modules such as C<Coro::Timer> and
135C<Coro::Event> to wait on an external event that hopefully wake up a 142C<Coro::Event> to wait on an external event that hopefully wake up a
136coroutine so the scheduler can run it. 143coroutine so the scheduler can run it.
137 144
138Please note that if your callback recursively invokes perl (e.g. for event 145Please note that if your callback recursively invokes perl (e.g. for event
139handlers), then it must be prepared to be called recursively. 146handlers), then it must be prepared to be called recursively itself.
140 147
141=cut 148=cut
142 149
143$idle = sub { 150$idle = sub {
144 require Carp; 151 require Carp;
… …
186=item async { ... } [@args...] 193=item async { ... } [@args...]
187 194
188Create a new asynchronous coroutine and return it's coroutine object 195Create a new asynchronous coroutine and return it's coroutine object
189(usually unused). When the sub returns the new coroutine is automatically 196(usually unused). When the sub returns the new coroutine is automatically
190terminated. 197terminated.
198
199See the C<Coro::State::new> constructor for info about the coroutine
200environment in which coroutines run.
191 201
192Calling C<exit> in a coroutine will do the same as calling exit outside 202Calling C<exit> in a coroutine will do the same as calling exit outside
193the coroutine. Likewise, when the coroutine dies, the program will exit, 203the coroutine. Likewise, when the coroutine dies, the program will exit,
194just as it would in the main program. 204just as it would in the main program.
195 205
… …
216issued in case of an exception instead of terminating the program, as 226issued in case of an exception instead of terminating the program, as
217C<async> does. As the coroutine is being reused, stuff like C<on_destroy> 227C<async> does. As the coroutine is being reused, stuff like C<on_destroy>
218will not work in the expected way, unless you call terminate or cancel, 228will not work in the expected way, unless you call terminate or cancel,
219which somehow defeats the purpose of pooling. 229which somehow defeats the purpose of pooling.
220 230
221The priority will be reset to C<0> after each job, otherwise the coroutine 231The priority will be reset to C<0> after each job, tracing will be
222will be re-used "as-is". 232disabled, the description will be reset and the default output filehandle
233gets restored, so you can change alkl these. Otherwise the coroutine will
234be re-used "as-is": most notably if you change other per-coroutine global
235stuff such as C<$/> you need to revert that change, which is most simply
236done by using local as in C< local $/ >.
223 237
224The pool size is limited to 8 idle coroutines (this can be adjusted by 238The pool size is limited to 8 idle coroutines (this can be adjusted by
225changing $Coro::POOL_SIZE), and there can be as many non-idle coros as 239changing $Coro::POOL_SIZE), and there can be as many non-idle coros as
226required. 240required.
227 241
… …
248 _pool_2 $cb; 262 _pool_2 $cb;
249 &schedule; 263 &schedule;
250 } 264 }
251 }; 265 };
252 266
253 last if $@ eq "\3terminate\2\n"; 267 last if $@ eq "\3async_pool terminate\2\n";
254 warn $@ if $@; 268 warn $@ if $@;
255 } 269 }
256} 270}
257 271
258sub async_pool(&@) { 272sub async_pool(&@) {
… …
344Create a new coroutine and return it. When the sub returns the coroutine 358Create a new coroutine and return it. When the sub returns the coroutine
345automatically terminates as if C<terminate> with the returned values were 359automatically terminates as if C<terminate> with the returned values were
346called. To make the coroutine run you must first put it into the ready queue 360called. To make the coroutine run you must first put it into the ready queue
347by calling the ready method. 361by calling the ready method.
348 362
349See C<async> for additional discussion. 363See C<async> and C<Coro::State::new> for additional info about the
364coroutine environment.
350 365
351=cut 366=cut
352 367
353sub _run_coro { 368sub _run_coro {
354 terminate &{+shift}; 369 terminate &{+shift};
… …
462Sets (or gets in case the argument is missing) the description for this 477Sets (or gets in case the argument is missing) the description for this
463coroutine. This is just a free-form string you can associate with a coroutine. 478coroutine. This is just a free-form string you can associate with a coroutine.
464 479
465This method simply sets the C<< $coroutine->{desc} >> member to the given string. You 480This method simply sets the C<< $coroutine->{desc} >> member to the given string. You
466can modify this member directly if you wish. 481can modify this member directly if you wish.
482
483=item $coroutine->throw ([$scalar])
484
485If C<$throw> is specified and defined, it will be thrown as an exception
486inside the coroutine at the next convinient point in time (usually after
487it gains control at the next schedule/transfer/cede). Otherwise clears the
488exception object.
489
490The exception object will be thrown "as is" with the specified scalar in
491C<$@>, i.e. if it is a string, no line number or newline will be appended
492(unlike with C<die>).
493
494This can be used as a softer means than C<cancel> to ask a coroutine to
495end itself, although there is no guarentee that the exception will lead to
496termination, and if the exception isn't caught it might well end the whole
497program.
467 498
468=cut 499=cut
469 500
470sub desc { 501sub desc {
471 my $old = $_[0]{desc}; 502 my $old = $_[0]{desc};
… …
589 to allow per-thread schedulers, but Coro::State does not yet allow 620 to allow per-thread schedulers, but Coro::State does not yet allow
590 this). 621 this).
591 622
592=head1 SEE ALSO 623=head1 SEE ALSO
593 624
625Lower level Configuration, Coroutine Environment: L<Coro::State>.
626
627Debugging: L<Coro::Debug>.
628
594Support/Utility: L<Coro::Cont>, L<Coro::Specific>, L<Coro::State>, L<Coro::Util>. 629Support/Utility: L<Coro::Specific>, L<Coro::Util>.
595 630
596Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>. 631Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>.
597 632
598Event/IO: L<Coro::Timer>, L<Coro::Event>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::Select>. 633Event/IO: L<Coro::Timer>, L<Coro::Event>, L<Coro::Handle>, L<Coro::Socket>.
599 634
635Compatibility: L<Coro::LWP>, L<Coro::Storable>, L<Coro::Select>.
636
600Embedding: L<Coro:MakeMaker> 637Embedding: L<Coro:MakeMaker>.
601 638
602=head1 AUTHOR 639=head1 AUTHOR
603 640
604 Marc Lehmann <schmorp@schmorp.de> 641 Marc Lehmann <schmorp@schmorp.de>
605 http://home.schmorp.de/ 642 http://home.schmorp.de/

Diff Legend

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