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

Comparing cvsroot/Coro/Coro.pm (file contents):
Revision 1.145 by root, Wed Oct 3 16:03:17 2007 UTC vs.
Revision 1.179 by root, Sat Apr 19 19:06:02 2008 UTC

… …
2 2
3Coro - coroutine process abstraction 3Coro - coroutine process abstraction
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
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 };
12 15 print "1\n";
13 # alternatively create an async coroutine like this: 16 cede; # yield to coroutine
14 17 print "3\n";
15 sub some_func : Coro { 18 cede; # and again
16 # some more async code 19
17 } 20 # use locking
18 21 my $lock = new Coro::Semaphore;
19 cede; 22 my $locked;
23
24 $lock->down;
25 $locked = 1;
26 $lock->up;
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.0'; 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);
61our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); 68our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
62 69
63{
64 my @async;
65 my $init;
66
67 # this way of handling attributes simply is NOT scalable ;()
68 sub import {
69 no strict 'refs';
70
71 Coro->export_to_level (1, @_);
72
73 my $old = *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"}{CODE};
74 *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"} = sub {
75 my ($package, $ref) = (shift, shift);
76 my @attrs;
77 for (@_) {
78 if ($_ eq "Coro") {
79 push @async, $ref;
80 unless ($init++) {
81 eval q{
82 sub INIT {
83 &async(pop @async) while @async;
84 }
85 };
86 }
87 } else {
88 push @attrs, $_;
89 }
90 }
91 return $old ? $old->($package, $ref, @attrs) : @attrs;
92 };
93 }
94
95}
96
97=over 4 70=over 4
98 71
99=item $main 72=item $main
100 73
101This coroutine represents the main program. 74This coroutine represents the main program.
… …
134This hook is overwritten by modules such as C<Coro::Timer> and 107This 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 108C<Coro::Event> to wait on an external event that hopefully wake up a
136coroutine so the scheduler can run it. 109coroutine so the scheduler can run it.
137 110
138Please note that if your callback recursively invokes perl (e.g. for event 111Please note that if your callback recursively invokes perl (e.g. for event
139handlers), then it must be prepared to be called recursively. 112handlers), then it must be prepared to be called recursively itself.
140 113
141=cut 114=cut
142 115
143$idle = sub { 116$idle = sub {
144 require Carp; 117 require Carp;
… …
171 } 144 }
172}; 145};
173$manager->desc ("[coro manager]"); 146$manager->desc ("[coro manager]");
174$manager->prio (PRIO_MAX); 147$manager->prio (PRIO_MAX);
175 148
176# static methods. not really.
177
178=back 149=back
179 150
180=head2 STATIC METHODS 151=head2 STATIC METHODS
181 152
182Static methods are actually functions that operate on the current coroutine only. 153Static methods are actually functions that operate on the current coroutine only.
… …
188Create a new asynchronous coroutine and return it's coroutine object 159Create a new asynchronous coroutine and return it's coroutine object
189(usually unused). When the sub returns the new coroutine is automatically 160(usually unused). When the sub returns the new coroutine is automatically
190terminated. 161terminated.
191 162
192See the C<Coro::State::new> constructor for info about the coroutine 163See the C<Coro::State::new> constructor for info about the coroutine
193environment. 164environment in which coroutines run.
194 165
195Calling C<exit> in a coroutine will do the same as calling exit outside 166Calling C<exit> in a coroutine will do the same as calling exit outside
196the coroutine. Likewise, when the coroutine dies, the program will exit, 167the coroutine. Likewise, when the coroutine dies, the program will exit,
197just as it would in the main program. 168just as it would in the main program.
198 169
… …
219issued in case of an exception instead of terminating the program, as 190issued in case of an exception instead of terminating the program, as
220C<async> does. As the coroutine is being reused, stuff like C<on_destroy> 191C<async> does. As the coroutine is being reused, stuff like C<on_destroy>
221will not work in the expected way, unless you call terminate or cancel, 192will not work in the expected way, unless you call terminate or cancel,
222which somehow defeats the purpose of pooling. 193which somehow defeats the purpose of pooling.
223 194
224The priority will be reset to C<0> after each job, otherwise the coroutine 195The priority will be reset to C<0> after each job, tracing will be
225will be re-used "as-is". 196disabled, the description will be reset and the default output filehandle
197gets restored, so you can change alkl these. Otherwise the coroutine will
198be re-used "as-is": most notably if you change other per-coroutine global
199stuff such as C<$/> you need to revert that change, which is most simply
200done by using local as in C< local $/ >.
226 201
227The pool size is limited to 8 idle coroutines (this can be adjusted by 202The pool size is limited to 8 idle coroutines (this can be adjusted by
228changing $Coro::POOL_SIZE), and there can be as many non-idle coros as 203changing $Coro::POOL_SIZE), and there can be as many non-idle coros as
229required. 204required.
230 205
… …
251 _pool_2 $cb; 226 _pool_2 $cb;
252 &schedule; 227 &schedule;
253 } 228 }
254 }; 229 };
255 230
256 last if $@ eq "\3terminate\2\n"; 231 last if $@ eq "\3async_pool terminate\2\n";
257 warn $@ if $@; 232 warn $@ if $@;
258 } 233 }
259} 234}
260 235
261sub async_pool(&@) { 236sub async_pool(&@) {
… …
298 273
299"Cede" to other coroutines. This function puts the current coroutine into the 274"Cede" to other coroutines. This function puts the current coroutine into the
300ready queue and calls C<schedule>, which has the effect of giving up the 275ready queue and calls C<schedule>, which has the effect of giving up the
301current "timeslice" to other coroutines of the same or higher priority. 276current "timeslice" to other coroutines of the same or higher priority.
302 277
303Returns true if at least one coroutine switch has happened.
304
305=item Coro::cede_notself 278=item Coro::cede_notself
306 279
307Works like cede, but is not exported by default and will cede to any 280Works like cede, but is not exported by default and will cede to any
308coroutine, regardless of priority, once. 281coroutine, regardless of priority, once.
309
310Returns true if at least one coroutine switch has happened.
311 282
312=item terminate [arg...] 283=item terminate [arg...]
313 284
314Terminates the current coroutine with the given status values (see L<cancel>). 285Terminates the current coroutine with the given status values (see L<cancel>).
315 286
… …
331 if $_ != $current && UNIVERSAL::isa $_, "Coro"; 302 if $_ != $current && UNIVERSAL::isa $_, "Coro";
332 } 303 }
333} 304}
334 305
335=back 306=back
336
337# dynamic methods
338 307
339=head2 COROUTINE METHODS 308=head2 COROUTINE METHODS
340 309
341These are the methods you can call on coroutine objects. 310These are the methods you can call on coroutine objects.
342 311
… …
466Sets (or gets in case the argument is missing) the description for this 435Sets (or gets in case the argument is missing) the description for this
467coroutine. This is just a free-form string you can associate with a coroutine. 436coroutine. This is just a free-form string you can associate with a coroutine.
468 437
469This method simply sets the C<< $coroutine->{desc} >> member to the given string. You 438This method simply sets the C<< $coroutine->{desc} >> member to the given string. You
470can modify this member directly if you wish. 439can modify this member directly if you wish.
440
441=item $coroutine->throw ([$scalar])
442
443If C<$throw> is specified and defined, it will be thrown as an exception
444inside the coroutine at the next convinient point in time (usually after
445it gains control at the next schedule/transfer/cede). Otherwise clears the
446exception object.
447
448The exception object will be thrown "as is" with the specified scalar in
449C<$@>, i.e. if it is a string, no line number or newline will be appended
450(unlike with C<die>).
451
452This can be used as a softer means than C<cancel> to ask a coroutine to
453end itself, although there is no guarentee that the exception will lead to
454termination, and if the exception isn't caught it might well end the whole
455program.
471 456
472=cut 457=cut
473 458
474sub desc { 459sub desc {
475 my $old = $_[0]{desc}; 460 my $old = $_[0]{desc};
… …
593 to allow per-thread schedulers, but Coro::State does not yet allow 578 to allow per-thread schedulers, but Coro::State does not yet allow
594 this). 579 this).
595 580
596=head1 SEE ALSO 581=head1 SEE ALSO
597 582
583Lower level Configuration, Coroutine Environment: L<Coro::State>.
584
585Debugging: L<Coro::Debug>.
586
598Support/Utility: L<Coro::Cont>, L<Coro::Specific>, L<Coro::State>, L<Coro::Util>. 587Support/Utility: L<Coro::Specific>, L<Coro::Util>.
599 588
600Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>. 589Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>.
601 590
602Event/IO: L<Coro::Timer>, L<Coro::Event>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::Select>. 591Event/IO: L<Coro::Timer>, L<Coro::Event>, L<Coro::Handle>, L<Coro::Socket>.
603 592
593Compatibility: L<Coro::LWP>, L<Coro::Storable>, L<Coro::Select>.
594
604Embedding: L<Coro:MakeMaker> 595Embedding: L<Coro::MakeMaker>.
605 596
606=head1 AUTHOR 597=head1 AUTHOR
607 598
608 Marc Lehmann <schmorp@schmorp.de> 599 Marc Lehmann <schmorp@schmorp.de>
609 http://home.schmorp.de/ 600 http://home.schmorp.de/

Diff Legend

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