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

Comparing Coro/Coro.pm (file contents):
Revision 1.148 by root, Fri Oct 5 20:11:25 2007 UTC vs.
Revision 1.178 by root, Thu Apr 17 22:33:10 2008 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 = '4.01'; 62our $VERSION = '4.51';
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;
… …
171 } 178 }
172}; 179};
173$manager->desc ("[coro manager]"); 180$manager->desc ("[coro manager]");
174$manager->prio (PRIO_MAX); 181$manager->prio (PRIO_MAX);
175 182
176# static methods. not really.
177
178=back 183=back
179 184
180=head2 STATIC METHODS 185=head2 STATIC METHODS
181 186
182Static methods are actually functions that operate on the current coroutine only. 187Static methods are actually functions that operate on the current coroutine only.
… …
188Create a new asynchronous coroutine and return it's coroutine object 193Create a new asynchronous coroutine and return it's coroutine object
189(usually unused). When the sub returns the new coroutine is automatically 194(usually unused). When the sub returns the new coroutine is automatically
190terminated. 195terminated.
191 196
192See the C<Coro::State::new> constructor for info about the coroutine 197See the C<Coro::State::new> constructor for info about the coroutine
193environment. 198environment in which coroutines run.
194 199
195Calling C<exit> in a coroutine will do the same as calling exit outside 200Calling C<exit> in a coroutine will do the same as calling exit outside
196the coroutine. Likewise, when the coroutine dies, the program will exit, 201the coroutine. Likewise, when the coroutine dies, the program will exit,
197just as it would in the main program. 202just as it would in the main program.
198 203
… …
255 _pool_2 $cb; 260 _pool_2 $cb;
256 &schedule; 261 &schedule;
257 } 262 }
258 }; 263 };
259 264
260 last if $@ eq "\3terminate\2\n"; 265 last if $@ eq "\3async_pool terminate\2\n";
261 warn $@ if $@; 266 warn $@ if $@;
262 } 267 }
263} 268}
264 269
265sub async_pool(&@) { 270sub async_pool(&@) {
… …
302 307
303"Cede" to other coroutines. This function puts the current coroutine into the 308"Cede" to other coroutines. This function puts the current coroutine into the
304ready queue and calls C<schedule>, which has the effect of giving up the 309ready queue and calls C<schedule>, which has the effect of giving up the
305current "timeslice" to other coroutines of the same or higher priority. 310current "timeslice" to other coroutines of the same or higher priority.
306 311
307Returns true if at least one coroutine switch has happened.
308
309=item Coro::cede_notself 312=item Coro::cede_notself
310 313
311Works like cede, but is not exported by default and will cede to any 314Works like cede, but is not exported by default and will cede to any
312coroutine, regardless of priority, once. 315coroutine, regardless of priority, once.
313
314Returns true if at least one coroutine switch has happened.
315 316
316=item terminate [arg...] 317=item terminate [arg...]
317 318
318Terminates the current coroutine with the given status values (see L<cancel>). 319Terminates the current coroutine with the given status values (see L<cancel>).
319 320
… …
335 if $_ != $current && UNIVERSAL::isa $_, "Coro"; 336 if $_ != $current && UNIVERSAL::isa $_, "Coro";
336 } 337 }
337} 338}
338 339
339=back 340=back
340
341# dynamic methods
342 341
343=head2 COROUTINE METHODS 342=head2 COROUTINE METHODS
344 343
345These are the methods you can call on coroutine objects. 344These are the methods you can call on coroutine objects.
346 345
… …
470Sets (or gets in case the argument is missing) the description for this 469Sets (or gets in case the argument is missing) the description for this
471coroutine. This is just a free-form string you can associate with a coroutine. 470coroutine. This is just a free-form string you can associate with a coroutine.
472 471
473This method simply sets the C<< $coroutine->{desc} >> member to the given string. You 472This method simply sets the C<< $coroutine->{desc} >> member to the given string. You
474can modify this member directly if you wish. 473can modify this member directly if you wish.
474
475=item $coroutine->throw ([$scalar])
476
477If C<$throw> is specified and defined, it will be thrown as an exception
478inside the coroutine at the next convinient point in time (usually after
479it gains control at the next schedule/transfer/cede). Otherwise clears the
480exception object.
481
482The exception object will be thrown "as is" with the specified scalar in
483C<$@>, i.e. if it is a string, no line number or newline will be appended
484(unlike with C<die>).
485
486This can be used as a softer means than C<cancel> to ask a coroutine to
487end itself, although there is no guarentee that the exception will lead to
488termination, and if the exception isn't caught it might well end the whole
489program.
475 490
476=cut 491=cut
477 492
478sub desc { 493sub desc {
479 my $old = $_[0]{desc}; 494 my $old = $_[0]{desc};
… …
597 to allow per-thread schedulers, but Coro::State does not yet allow 612 to allow per-thread schedulers, but Coro::State does not yet allow
598 this). 613 this).
599 614
600=head1 SEE ALSO 615=head1 SEE ALSO
601 616
617Lower level Configuration, Coroutine Environment: L<Coro::State>.
618
619Debugging: L<Coro::Debug>.
620
602Support/Utility: L<Coro::Specific>, L<Coro::State>, L<Coro::Util>. 621Support/Utility: L<Coro::Specific>, L<Coro::Util>.
603 622
604Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>. 623Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>.
605 624
606Event/IO: L<Coro::Timer>, L<Coro::Event>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::Select>. 625Event/IO: L<Coro::Timer>, L<Coro::Event>, L<Coro::Handle>, L<Coro::Socket>.
607 626
627Compatibility: L<Coro::LWP>, L<Coro::Storable>, L<Coro::Select>.
628
608Embedding: L<Coro:MakeMaker> 629Embedding: L<Coro::MakeMaker>.
609 630
610=head1 AUTHOR 631=head1 AUTHOR
611 632
612 Marc Lehmann <schmorp@schmorp.de> 633 Marc Lehmann <schmorp@schmorp.de>
613 http://home.schmorp.de/ 634 http://home.schmorp.de/

Diff Legend

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