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

Comparing Coro/Coro.pm (file contents):
Revision 1.174 by root, Sun Apr 6 17:51:14 2008 UTC vs.
Revision 1.246 by root, Mon Dec 15 00:30:40 2008 UTC

1=head1 NAME 1=head1 NAME
2 2
3Coro - coroutine process abstraction 3Coro - the only real threads in perl
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"; 11 print "2\n";
12 cede; # yield back to main 12 cede; # yield back to main
13 print "4\n"; 13 print "4\n";
14 }; 14 };
15 print "1\n"; 15 print "1\n";
16 cede; # yield to coroutine 16 cede; # yield to coroutine
17 print "3\n"; 17 print "3\n";
18 cede; # and again 18 cede; # and again
19 19
20 # use locking 20 # use locking
21 use Coro::Semaphore;
21 my $lock = new Coro::Semaphore; 22 my $lock = new Coro::Semaphore;
22 my $locked; 23 my $locked;
23 24
24 $lock->down; 25 $lock->down;
25 $locked = 1; 26 $locked = 1;
26 $lock->up; 27 $lock->up;
27 28
28=head1 DESCRIPTION 29=head1 DESCRIPTION
29 30
30This module collection manages coroutines. Coroutines are similar 31For a tutorial-style introduction, please read the L<Coro::Intro>
31to threads but don't run in parallel at the same time even on SMP 32manpage. This manpage mainly contains reference information.
32machines. The specific flavor of coroutine used in this module also
33guarantees you that it will not switch between coroutines unless
34necessary, at easily-identified points in your program, so locking and
35parallel access are rarely an issue, making coroutine programming much
36safer than threads programming.
37 33
38(Perl, however, does not natively support real threads but instead does a 34This module collection manages continuations in general, most often
39very slow and memory-intensive emulation of processes using threads. This 35in the form of cooperative threads (also called coroutines in the
40is a performance win on Windows machines, and a loss everywhere else). 36documentation). They are similar to kernel threads but don't (in general)
37run in parallel at the same time even on SMP machines. The specific flavor
38of thread offered by this module also guarantees you that it will not
39switch between threads unless necessary, at easily-identified points in
40your program, so locking and parallel access are rarely an issue, making
41thread programming much safer and easier than using other thread models.
41 42
43Unlike the so-called "Perl threads" (which are not actually real threads
44but only the windows process emulation ported to unix), Coro provides a
45full shared address space, which makes communication between threads
46very easy. And threads are fast, too: disabling the Windows process
47emulation code in your perl and using Coro can easily result in a two to
48four times speed increase for your programs.
49
50Coro achieves that by supporting multiple running interpreters that share
51data, which is especially useful to code pseudo-parallel processes and
52for event-based programming, such as multiple HTTP-GET requests running
53concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro
54into an event-based environment.
55
42In this module, coroutines are defined as "callchain + lexical variables + 56In this module, a thread is defined as "callchain + lexical variables +
43@_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own callchain, 57@_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain,
44its own set of lexicals and its own set of perls most important global 58its own set of lexicals and its own set of perls most important global
45variables (see L<Coro::State> for more configuration). 59variables (see L<Coro::State> for more configuration and background info).
60
61See also the C<SEE ALSO> section at the end of this document - the Coro
62module family is quite large.
46 63
47=cut 64=cut
48 65
49package Coro; 66package Coro;
50 67
51use strict; 68use strict qw(vars subs);
52no warnings "uninitialized"; 69no warnings "uninitialized";
70
71use Guard ();
53 72
54use Coro::State; 73use Coro::State;
55 74
56use base qw(Coro::State Exporter); 75use base qw(Coro::State Exporter);
57 76
58our $idle; # idle handler 77our $idle; # idle handler
59our $main; # main coroutine 78our $main; # main coroutine
60our $current; # current coroutine 79our $current; # current coroutine
61 80
62our $VERSION = '4.48'; 81our $VERSION = 5.13;
63 82
64our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 83our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub);
65our %EXPORT_TAGS = ( 84our %EXPORT_TAGS = (
66 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 85 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
67); 86);
68our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); 87our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
69 88
70{ 89=head1 GLOBAL VARIABLES
71 my @async;
72 my $init;
73
74 # this way of handling attributes simply is NOT scalable ;()
75 sub import {
76 no strict 'refs';
77
78 Coro->export_to_level (1, @_);
79
80 my $old = *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"}{CODE};
81 *{(caller)[0]."::MODIFY_CODE_ATTRIBUTES"} = sub {
82 my ($package, $ref) = (shift, shift);
83 my @attrs;
84 for (@_) {
85 if ($_ eq "Coro") {
86 push @async, $ref;
87 unless ($init++) {
88 eval q{
89 sub INIT {
90 &async(pop @async) while @async;
91 }
92 };
93 }
94 } else {
95 push @attrs, $_;
96 }
97 }
98 return $old ? $old->($package, $ref, @attrs) : @attrs;
99 };
100 }
101
102}
103 90
104=over 4 91=over 4
105 92
106=item $main 93=item $Coro::main
107 94
108This coroutine represents the main program. 95This variable stores the coroutine object that represents the main
96program. While you cna C<ready> it and do most other things you can do to
97coroutines, it is mainly useful to compare again C<$Coro::current>, to see
98whether you are running in the main program or not.
109 99
110=cut 100=cut
111 101
112$main = new Coro; 102# $main is now being initialised by Coro::State
113 103
114=item $current (or as function: current) 104=item $Coro::current
115 105
116The current coroutine (the last coroutine switched to). The initial value 106The coroutine object representing the current coroutine (the last
107coroutine that the Coro scheduler switched to). The initial value is
117is C<$main> (of course). 108C<$Coro::main> (of course).
118 109
119This variable is B<strictly> I<read-only>. It is provided for performance 110This variable is B<strictly> I<read-only>. You can take copies of the
120reasons. If performance is not essential you are encouraged to use the 111value stored in it and use it as any other coroutine object, but you must
121C<Coro::current> function instead. 112not otherwise modify the variable itself.
122 113
123=cut 114=cut
124 115
125$main->{desc} = "[main::]";
126
127# maybe some other module used Coro::Specific before...
128$main->{_specific} = $current->{_specific}
129 if $current;
130
131_set_current $main;
132
133sub current() { $current } 116sub current() { $current } # [DEPRECATED]
134 117
135=item $idle 118=item $Coro::idle
136 119
120This variable is mainly useful to integrate Coro into event loops. It is
121usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is
122pretty low-level functionality.
123
124This variable stores either a coroutine or a callback.
125
137A callback that is called whenever the scheduler finds no ready coroutines 126If it is a callback, the it is called whenever the scheduler finds no
138to run. The default implementation prints "FATAL: deadlock detected" and 127ready coroutines to run. The default implementation prints "FATAL:
139exits, because the program has no other way to continue. 128deadlock detected" and exits, because the program has no other way to
129continue.
140 130
131If it is a coroutine object, then this object will be readied (without
132invoking any ready hooks, however) when the scheduler finds no other ready
133coroutines to run.
134
141This hook is overwritten by modules such as C<Coro::Timer> and 135This hook is overwritten by modules such as C<Coro::EV> and
142C<Coro::Event> to wait on an external event that hopefully wake up a 136C<Coro::AnyEvent> to wait on an external event that hopefully wake up a
143coroutine so the scheduler can run it. 137coroutine so the scheduler can run it.
138
139Note that the callback I<must not>, under any circumstances, block
140the current coroutine. Normally, this is achieved by having an "idle
141coroutine" that calls the event loop and then blocks again, and then
142readying that coroutine in the idle handler, or by simply placing the idle
143coroutine in this variable.
144
145See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this
146technique.
144 147
145Please note that if your callback recursively invokes perl (e.g. for event 148Please note that if your callback recursively invokes perl (e.g. for event
146handlers), then it must be prepared to be called recursively itself. 149handlers), then it must be prepared to be called recursively itself.
147 150
148=cut 151=cut
… …
150$idle = sub { 153$idle = sub {
151 require Carp; 154 require Carp;
152 Carp::croak ("FATAL: deadlock detected"); 155 Carp::croak ("FATAL: deadlock detected");
153}; 156};
154 157
155sub _cancel {
156 my ($self) = @_;
157
158 # free coroutine data and mark as destructed
159 $self->_destroy
160 or return;
161
162 # call all destruction callbacks
163 $_->(@{$self->{_status}})
164 for @{(delete $self->{_on_destroy}) || []};
165}
166
167# this coroutine is necessary because a coroutine 158# this coroutine is necessary because a coroutine
168# cannot destroy itself. 159# cannot destroy itself.
169my @destroy; 160our @destroy;
170my $manager; 161our $manager;
171 162
172$manager = new Coro sub { 163$manager = new Coro sub {
173 while () { 164 while () {
174 (shift @destroy)->_cancel 165 Coro::_cancel shift @destroy
175 while @destroy; 166 while @destroy;
176 167
177 &schedule; 168 &schedule;
178 } 169 }
179}; 170};
180$manager->desc ("[coro manager]"); 171$manager->{desc} = "[coro manager]";
181$manager->prio (PRIO_MAX); 172$manager->prio (PRIO_MAX);
182 173
183# static methods. not really.
184
185=back 174=back
186 175
187=head2 STATIC METHODS 176=head1 SIMPLE COROUTINE CREATION
188
189Static methods are actually functions that operate on the current coroutine only.
190 177
191=over 4 178=over 4
192 179
193=item async { ... } [@args...] 180=item async { ... } [@args...]
194 181
195Create a new asynchronous coroutine and return it's coroutine object 182Create a new coroutine and return its coroutine object (usually
196(usually unused). When the sub returns the new coroutine is automatically 183unused). The coroutine will be put into the ready queue, so
184it will start running automatically on the next scheduler run.
185
186The first argument is a codeblock/closure that should be executed in the
187coroutine. When it returns argument returns the coroutine is automatically
197terminated. 188terminated.
198 189
190The remaining arguments are passed as arguments to the closure.
191
199See the C<Coro::State::new> constructor for info about the coroutine 192See the C<Coro::State::new> constructor for info about the coroutine
200environment in which coroutines run. 193environment in which coroutines are executed.
201 194
202Calling C<exit> in a coroutine will do the same as calling exit outside 195Calling C<exit> in a coroutine will do the same as calling exit outside
203the coroutine. Likewise, when the coroutine dies, the program will exit, 196the coroutine. Likewise, when the coroutine dies, the program will exit,
204just as it would in the main program. 197just as it would in the main program.
205 198
199If you do not want that, you can provide a default C<die> handler, or
200simply avoid dieing (by use of C<eval>).
201
206 # create a new coroutine that just prints its arguments 202Example: Create a new coroutine that just prints its arguments.
203
207 async { 204 async {
208 print "@_\n"; 205 print "@_\n";
209 } 1,2,3,4; 206 } 1,2,3,4;
210 207
211=cut 208=cut
… …
217} 214}
218 215
219=item async_pool { ... } [@args...] 216=item async_pool { ... } [@args...]
220 217
221Similar to C<async>, but uses a coroutine pool, so you should not call 218Similar to C<async>, but uses a coroutine pool, so you should not call
222terminate or join (although you are allowed to), and you get a coroutine 219terminate or join on it (although you are allowed to), and you get a
223that might have executed other code already (which can be good or bad :). 220coroutine that might have executed other code already (which can be good
221or bad :).
224 222
223On the plus side, this function is about twice as fast as creating (and
224destroying) a completely new coroutine, so if you need a lot of generic
225coroutines in quick successsion, use C<async_pool>, not C<async>.
226
225Also, the block is executed in an C<eval> context and a warning will be 227The code block is executed in an C<eval> context and a warning will be
226issued in case of an exception instead of terminating the program, as 228issued in case of an exception instead of terminating the program, as
227C<async> does. As the coroutine is being reused, stuff like C<on_destroy> 229C<async> does. As the coroutine is being reused, stuff like C<on_destroy>
228will not work in the expected way, unless you call terminate or cancel, 230will not work in the expected way, unless you call terminate or cancel,
229which somehow defeats the purpose of pooling. 231which somehow defeats the purpose of pooling (but is fine in the
232exceptional case).
230 233
231The priority will be reset to C<0> after each job, tracing will be 234The priority will be reset to C<0> after each run, tracing will be
232disabled, the description will be reset and the default output filehandle 235disabled, the description will be reset and the default output filehandle
233gets restored, so you can change alkl these. Otherwise the coroutine will 236gets restored, so you can change all these. Otherwise the coroutine will
234be re-used "as-is": most notably if you change other per-coroutine global 237be 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 238stuff such as C<$/> you I<must needs> revert that change, which is most
236done by using local as in C< local $/ >. 239simply done by using local as in: C<< local $/ >>.
237 240
238The pool size is limited to 8 idle coroutines (this can be adjusted by 241The idle pool size is limited to C<8> idle coroutines (this can be
239changing $Coro::POOL_SIZE), and there can be as many non-idle coros as 242adjusted by changing $Coro::POOL_SIZE), but there can be as many non-idle
240required. 243coros as required.
241 244
242If you are concerned about pooled coroutines growing a lot because a 245If you are concerned about pooled coroutines growing a lot because a
243single C<async_pool> used a lot of stackspace you can e.g. C<async_pool 246single C<async_pool> used a lot of stackspace you can e.g. C<async_pool
244{ terminate }> once per second or so to slowly replenish the pool. In 247{ terminate }> once per second or so to slowly replenish the pool. In
245addition to that, when the stacks used by a handler grows larger than 16kb 248addition to that, when the stacks used by a handler grows larger than 32kb
246(adjustable with $Coro::POOL_RSS) it will also exit. 249(adjustable via $Coro::POOL_RSS) it will also be destroyed.
247 250
248=cut 251=cut
249 252
250our $POOL_SIZE = 8; 253our $POOL_SIZE = 8;
251our $POOL_RSS = 16 * 1024; 254our $POOL_RSS = 32 * 1024;
252our @async_pool; 255our @async_pool;
253 256
254sub pool_handler { 257sub pool_handler {
255 my $cb;
256
257 while () { 258 while () {
258 eval { 259 eval {
259 while () { 260 &{&_pool_handler} while 1;
260 _pool_1 $cb;
261 &$cb;
262 _pool_2 $cb;
263 &schedule;
264 }
265 }; 261 };
266 262
267 last if $@ eq "\3async_pool terminate\2\n";
268 warn $@ if $@; 263 warn $@ if $@;
269 } 264 }
270} 265}
271 266
272sub async_pool(&@) { 267=back
273 # this is also inlined into the unlock_scheduler
274 my $coro = (pop @async_pool) || new Coro \&pool_handler;
275 268
276 $coro->{_invoke} = [@_]; 269=head1 STATIC METHODS
277 $coro->ready;
278 270
279 $coro 271Static methods are actually functions that implicitly operate on the
280} 272current coroutine.
273
274=over 4
281 275
282=item schedule 276=item schedule
283 277
284Calls the scheduler. Please note that the current coroutine will not be put 278Calls the scheduler. The scheduler will find the next coroutine that is
279to be run from the ready queue and switches to it. The next coroutine
280to be run is simply the one with the highest priority that is longest
281in its ready queue. If there is no coroutine ready, it will clal the
282C<$Coro::idle> hook.
283
284Please note that the current coroutine will I<not> be put into the ready
285into the ready queue, so calling this function usually means you will 285queue, so calling this function usually means you will never be called
286never be called again unless something else (e.g. an event handler) calls 286again unless something else (e.g. an event handler) calls C<< ->ready >>,
287ready. 287thus waking you up.
288 288
289The canonical way to wait on external events is this: 289This makes C<schedule> I<the> generic method to use to block the current
290coroutine and wait for events: first you remember the current coroutine in
291a variable, then arrange for some callback of yours to call C<< ->ready
292>> on that once some event happens, and last you call C<schedule> to put
293yourself to sleep. Note that a lot of things can wake your coroutine up,
294so you need to check whether the event indeed happened, e.g. by storing the
295status in a variable.
290 296
291 { 297See B<HOW TO WAIT FOR A CALLBACK>, below, for some ways to wait for callbacks.
292 # remember current coroutine
293 my $current = $Coro::current;
294
295 # register a hypothetical event handler
296 on_event_invoke sub {
297 # wake up sleeping coroutine
298 $current->ready;
299 undef $current;
300 };
301
302 # call schedule until event occurred.
303 # in case we are woken up for other reasons
304 # (current still defined), loop.
305 Coro::schedule while $current;
306 }
307 298
308=item cede 299=item cede
309 300
310"Cede" to other coroutines. This function puts the current coroutine into the 301"Cede" to other coroutines. This function puts the current coroutine into
311ready queue and calls C<schedule>, which has the effect of giving up the 302the ready queue and calls C<schedule>, which has the effect of giving
312current "timeslice" to other coroutines of the same or higher priority. 303up the current "timeslice" to other coroutines of the same or higher
304priority. Once your coroutine gets its turn again it will automatically be
305resumed.
306
307This function is often called C<yield> in other languages.
313 308
314=item Coro::cede_notself 309=item Coro::cede_notself
315 310
316Works like cede, but is not exported by default and will cede to any 311Works like cede, but is not exported by default and will cede to I<any>
317coroutine, regardless of priority, once. 312coroutine, regardless of priority. This is useful sometimes to ensure
313progress is made.
318 314
319=item terminate [arg...] 315=item terminate [arg...]
320 316
321Terminates the current coroutine with the given status values (see L<cancel>). 317Terminates the current coroutine with the given status values (see L<cancel>).
322 318
323=item killall 319=item killall
324 320
325Kills/terminates/cancels all coroutines except the currently running 321Kills/terminates/cancels all coroutines except the currently running
326one. This is useful after a fork, either in the child or the parent, as 322one. This can be useful after a fork, either in the child or the parent,
327usually only one of them should inherit the running coroutines. 323as usually only one of them should inherit the running coroutines.
328 324
329=cut 325Note that in the implementation, destructors run as normal, making this
326function not so useful after a fork. Future versions of this function
327might try to free resources without running any code.
330 328
331sub terminate { 329Note that while this will try to free some of the main programs resources,
332 $current->cancel (@_); 330you cannot free all of them, so if a coroutine that is not the main
333} 331program calls this function, there will be some one-time resource leak.
332
333=cut
334 334
335sub killall { 335sub killall {
336 for (Coro::State::list) { 336 for (Coro::State::list) {
337 $_->cancel 337 $_->cancel
338 if $_ != $current && UNIVERSAL::isa $_, "Coro"; 338 if $_ != $current && UNIVERSAL::isa $_, "Coro";
339 } 339 }
340} 340}
341 341
342=back 342=back
343 343
344# dynamic methods
345
346=head2 COROUTINE METHODS 344=head1 COROUTINE OBJECT METHODS
347 345
348These are the methods you can call on coroutine objects. 346These are the methods you can call on coroutine objects (or to create
347them).
349 348
350=over 4 349=over 4
351 350
352=item new Coro \&sub [, @args...] 351=item new Coro \&sub [, @args...]
353 352
354Create a new coroutine and return it. When the sub returns the coroutine 353Create a new coroutine and return it. When the sub returns, the coroutine
355automatically terminates as if C<terminate> with the returned values were 354automatically terminates as if C<terminate> with the returned values were
356called. To make the coroutine run you must first put it into the ready queue 355called. To make the coroutine run you must first put it into the ready
357by calling the ready method. 356queue by calling the ready method.
358 357
359See C<async> and C<Coro::State::new> for additional info about the 358See C<async> and C<Coro::State::new> for additional info about the
360coroutine environment. 359coroutine environment.
361 360
362=cut 361=cut
363 362
364sub _run_coro { 363sub _coro_run {
365 terminate &{+shift}; 364 terminate &{+shift};
366} 365}
367 366
368sub new {
369 my $class = shift;
370
371 $class->SUPER::new (\&_run_coro, @_)
372}
373
374=item $success = $coroutine->ready 367=item $success = $coroutine->ready
375 368
376Put the given coroutine into the ready queue (according to it's priority) 369Put the given coroutine into the end of its ready queue (there is one
377and return true. If the coroutine is already in the ready queue, do nothing 370queue for each priority) and return true. If the coroutine is already in
378and return false. 371the ready queue, do nothing and return false.
372
373This ensures that the scheduler will resume this coroutine automatically
374once all the coroutines of higher priority and all coroutines of the same
375priority that were put into the ready queue earlier have been resumed.
379 376
380=item $is_ready = $coroutine->is_ready 377=item $is_ready = $coroutine->is_ready
381 378
382Return wether the coroutine is currently the ready queue or not, 379Return whether the coroutine is currently the ready queue or not,
383 380
384=item $coroutine->cancel (arg...) 381=item $coroutine->cancel (arg...)
385 382
386Terminates the given coroutine and makes it return the given arguments as 383Terminates the given coroutine and makes it return the given arguments as
387status (default: the empty list). Never returns if the coroutine is the 384status (default: the empty list). Never returns if the coroutine is the
… …
389 386
390=cut 387=cut
391 388
392sub cancel { 389sub cancel {
393 my $self = shift; 390 my $self = shift;
394 $self->{_status} = [@_];
395 391
396 if ($current == $self) { 392 if ($current == $self) {
397 push @destroy, $self; 393 terminate @_;
398 $manager->ready;
399 &schedule while 1;
400 } else { 394 } else {
395 $self->{_status} = [@_];
401 $self->_cancel; 396 $self->_cancel;
402 } 397 }
403} 398}
399
400=item $coroutine->schedule_to
401
402Puts the current coroutine to sleep (like C<Coro::schedule>), but instead
403of continuing with the next coro from the ready queue, always switch to
404the given coroutine object (regardless of priority etc.). The readyness
405state of that coroutine isn't changed.
406
407This is an advanced method for special cases - I'd love to hear about any
408uses for this one.
409
410=item $coroutine->cede_to
411
412Like C<schedule_to>, but puts the current coroutine into the ready
413queue. This has the effect of temporarily switching to the given
414coroutine, and continuing some time later.
415
416This is an advanced method for special cases - I'd love to hear about any
417uses for this one.
418
419=item $coroutine->throw ([$scalar])
420
421If C<$throw> is specified and defined, it will be thrown as an exception
422inside the coroutine at the next convenient point in time. Otherwise
423clears the exception object.
424
425Coro will check for the exception each time a schedule-like-function
426returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down
427>>, C<< Coro::Handle->readable >> and so on. Most of these functions
428detect this case and return early in case an exception is pending.
429
430The exception object will be thrown "as is" with the specified scalar in
431C<$@>, i.e. if it is a string, no line number or newline will be appended
432(unlike with C<die>).
433
434This can be used as a softer means than C<cancel> to ask a coroutine to
435end itself, although there is no guarantee that the exception will lead to
436termination, and if the exception isn't caught it might well end the whole
437program.
438
439You might also think of C<throw> as being the moral equivalent of
440C<kill>ing a coroutine with a signal (in this case, a scalar).
404 441
405=item $coroutine->join 442=item $coroutine->join
406 443
407Wait until the coroutine terminates and return any values given to the 444Wait until the coroutine terminates and return any values given to the
408C<terminate> or C<cancel> functions. C<join> can be called concurrently 445C<terminate> or C<cancel> functions. C<join> can be called concurrently
409from multiple coroutines. 446from multiple coroutines, and all will be resumed and given the status
447return once the C<$coroutine> terminates.
410 448
411=cut 449=cut
412 450
413sub join { 451sub join {
414 my $self = shift; 452 my $self = shift;
… …
429 467
430=item $coroutine->on_destroy (\&cb) 468=item $coroutine->on_destroy (\&cb)
431 469
432Registers a callback that is called when this coroutine gets destroyed, 470Registers a callback that is called when this coroutine gets destroyed,
433but before it is joined. The callback gets passed the terminate arguments, 471but before it is joined. The callback gets passed the terminate arguments,
434if any. 472if any, and I<must not> die, under any circumstances.
435 473
436=cut 474=cut
437 475
438sub on_destroy { 476sub on_destroy {
439 my ($self, $cb) = @_; 477 my ($self, $cb) = @_;
… …
469higher values mean lower priority, just as in unix). 507higher values mean lower priority, just as in unix).
470 508
471=item $olddesc = $coroutine->desc ($newdesc) 509=item $olddesc = $coroutine->desc ($newdesc)
472 510
473Sets (or gets in case the argument is missing) the description for this 511Sets (or gets in case the argument is missing) the description for this
474coroutine. This is just a free-form string you can associate with a coroutine. 512coroutine. This is just a free-form string you can associate with a
513coroutine.
475 514
476This method simply sets the C<< $coroutine->{desc} >> member to the given string. You 515This method simply sets the C<< $coroutine->{desc} >> member to the given
477can modify this member directly if you wish. 516string. You can modify this member directly if you wish.
478
479=item $coroutine->throw ([$scalar])
480
481If C<$throw> is specified and defined, it will be thrown as an exception
482inside the coroutine at the next convinient point in time (usually after
483it gains control at the next schedule/transfer/cede). Otherwise clears the
484exception object.
485
486The exception object will be thrown "as is" with the specified scalar in
487C<$@>, i.e. if it is a string, no line number or newline will be appended
488(unlike with C<die>).
489
490This can be used as a softer means than C<cancel> to ask a coroutine to
491end itself, although there is no guarentee that the exception will lead to
492termination, and if the exception isn't caught it might well end the whole
493program.
494 517
495=cut 518=cut
496 519
497sub desc { 520sub desc {
498 my $old = $_[0]{desc}; 521 my $old = $_[0]{desc};
499 $_[0]{desc} = $_[1] if @_ > 1; 522 $_[0]{desc} = $_[1] if @_ > 1;
500 $old; 523 $old;
501} 524}
502 525
526sub transfer {
527 require Carp;
528 Carp::croak ("You must not call ->transfer on Coro objects. Use Coro::State objects or the ->schedule_to method. Caught");
529}
530
503=back 531=back
504 532
505=head2 GLOBAL FUNCTIONS 533=head1 GLOBAL FUNCTIONS
506 534
507=over 4 535=over 4
508 536
509=item Coro::nready 537=item Coro::nready
510 538
511Returns the number of coroutines that are currently in the ready state, 539Returns the number of coroutines that are currently in the ready state,
512i.e. that can be switched to. The value C<0> means that the only runnable 540i.e. that can be switched to by calling C<schedule> directory or
541indirectly. The value C<0> means that the only runnable coroutine is the
513coroutine is the currently running one, so C<cede> would have no effect, 542currently running one, so C<cede> would have no effect, and C<schedule>
514and C<schedule> would cause a deadlock unless there is an idle handler 543would cause a deadlock unless there is an idle handler that wakes up some
515that wakes up some coroutines. 544coroutines.
516 545
517=item my $guard = Coro::guard { ... } 546=item my $guard = Coro::guard { ... }
518 547
519This creates and returns a guard object. Nothing happens until the object 548This function still exists, but is deprecated. Please use the
520gets destroyed, in which case the codeblock given as argument will be 549C<Guard::guard> function instead.
521executed. This is useful to free locks or other resources in case of a
522runtime error or when the coroutine gets canceled, as in both cases the
523guard block will be executed. The guard object supports only one method,
524C<< ->cancel >>, which will keep the codeblock from being executed.
525 550
526Example: set some flag and clear it again when the coroutine gets canceled
527or the function returns:
528
529 sub do_something {
530 my $guard = Coro::guard { $busy = 0 };
531 $busy = 1;
532
533 # do something that requires $busy to be true
534 }
535
536=cut 551=cut
537 552
538sub guard(&) { 553BEGIN { *guard = \&Guard::guard }
539 bless \(my $cb = $_[0]), "Coro::guard"
540}
541
542sub Coro::guard::cancel {
543 ${$_[0]} = sub { };
544}
545
546sub Coro::guard::DESTROY {
547 ${$_[0]}->();
548}
549
550 554
551=item unblock_sub { ... } 555=item unblock_sub { ... }
552 556
553This utility function takes a BLOCK or code reference and "unblocks" it, 557This utility function takes a BLOCK or code reference and "unblocks" it,
554returning the new coderef. This means that the new coderef will return 558returning a new coderef. Unblocking means that calling the new coderef
555immediately without blocking, returning nothing, while the original code 559will return immediately without blocking, returning nothing, while the
556ref will be called (with parameters) from within its own coroutine. 560original code ref will be called (with parameters) from within another
561coroutine.
557 562
558The reason this function exists is that many event libraries (such as the 563The reason this function exists is that many event libraries (such as the
559venerable L<Event|Event> module) are not coroutine-safe (a weaker form 564venerable L<Event|Event> module) are not coroutine-safe (a weaker form
560of thread-safety). This means you must not block within event callbacks, 565of reentrancy). This means you must not block within event callbacks,
561otherwise you might suffer from crashes or worse. 566otherwise you might suffer from crashes or worse. The only event library
567currently known that is safe to use without C<unblock_sub> is L<EV>.
562 568
563This function allows your callbacks to block by executing them in another 569This function allows your callbacks to block by executing them in another
564coroutine where it is safe to block. One example where blocking is handy 570coroutine where it is safe to block. One example where blocking is handy
565is when you use the L<Coro::AIO|Coro::AIO> functions to save results to 571is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
566disk. 572disk, for example.
567 573
568In short: simply use C<unblock_sub { ... }> instead of C<sub { ... }> when 574In short: simply use C<unblock_sub { ... }> instead of C<sub { ... }> when
569creating event callbacks that want to block. 575creating event callbacks that want to block.
576
577If your handler does not plan to block (e.g. simply sends a message to
578another coroutine, or puts some other coroutine into the ready queue),
579there is no reason to use C<unblock_sub>.
580
581Note that you also need to use C<unblock_sub> for any other callbacks that
582are indirectly executed by any C-based event loop. For example, when you
583use a module that uses L<AnyEvent> (and you use L<Coro::AnyEvent>) and it
584provides callbacks that are the result of some event callback, then you
585must not block either, or use C<unblock_sub>.
570 586
571=cut 587=cut
572 588
573our @unblock_queue; 589our @unblock_queue;
574 590
… …
577# return immediately and can be reused) and because we cannot cede 593# return immediately and can be reused) and because we cannot cede
578# inside an event callback. 594# inside an event callback.
579our $unblock_scheduler = new Coro sub { 595our $unblock_scheduler = new Coro sub {
580 while () { 596 while () {
581 while (my $cb = pop @unblock_queue) { 597 while (my $cb = pop @unblock_queue) {
582 # this is an inlined copy of async_pool 598 &async_pool (@$cb);
583 my $coro = (pop @async_pool) || new Coro \&pool_handler;
584 599
585 $coro->{_invoke} = $cb;
586 $coro->ready;
587 cede; # for short-lived callbacks, this reduces pressure on the coro pool 600 # for short-lived callbacks, this reduces pressure on the coro pool
601 # as the chance is very high that the async_poll coro will be back
602 # in the idle state when cede returns
603 cede;
588 } 604 }
589 schedule; # sleep well 605 schedule; # sleep well
590 } 606 }
591}; 607};
592$unblock_scheduler->desc ("[unblock_sub scheduler]"); 608$unblock_scheduler->{desc} = "[unblock_sub scheduler]";
593 609
594sub unblock_sub(&) { 610sub unblock_sub(&) {
595 my $cb = shift; 611 my $cb = shift;
596 612
597 sub { 613 sub {
598 unshift @unblock_queue, [$cb, @_]; 614 unshift @unblock_queue, [$cb, @_];
599 $unblock_scheduler->ready; 615 $unblock_scheduler->ready;
600 } 616 }
601} 617}
602 618
619=item $cb = Coro::rouse_cb
620
621Create and return a "rouse callback". That's a code reference that,
622when called, will remember a copy of its arguments and notify the owner
623coroutine of the callback.
624
625See the next function.
626
627=item @args = Coro::rouse_wait [$cb]
628
629Wait for the specified rouse callback (or the last one that was created in
630this coroutine).
631
632As soon as the callback is invoked (or when the callback was invoked
633before C<rouse_wait>), it will return the arguments originally passed to
634the rouse callback.
635
636See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
637
603=back 638=back
604 639
605=cut 640=cut
606 641
6071; 6421;
608 643
644=head1 HOW TO WAIT FOR A CALLBACK
645
646It is very common for a coroutine to wait for some callback to be
647called. This occurs naturally when you use coroutines in an otherwise
648event-based program, or when you use event-based libraries.
649
650These typically register a callback for some event, and call that callback
651when the event occured. In a coroutine, however, you typically want to
652just wait for the event, simplyifying things.
653
654For example C<< AnyEvent->child >> registers a callback to be called when
655a specific child has exited:
656
657 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
658
659But from withina coroutine, you often just want to write this:
660
661 my $status = wait_for_child $pid;
662
663Coro offers two functions specifically designed to make this easy,
664C<Coro::rouse_cb> and C<Coro::rouse_wait>.
665
666The first function, C<rouse_cb>, generates and returns a callback that,
667when invoked, will save its arguments and notify the coroutine that
668created the callback.
669
670The second function, C<rouse_wait>, waits for the callback to be called
671(by calling C<schedule> to go to sleep) and returns the arguments
672originally passed to the callback.
673
674Using these functions, it becomes easy to write the C<wait_for_child>
675function mentioned above:
676
677 sub wait_for_child($) {
678 my ($pid) = @_;
679
680 my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb);
681
682 my ($rpid, $rstatus) = Coro::rouse_wait;
683 $rstatus
684 }
685
686In the case where C<rouse_cb> and C<rouse_wait> are not flexible enough,
687you can roll your own, using C<schedule>:
688
689 sub wait_for_child($) {
690 my ($pid) = @_;
691
692 # store the current coroutine in $current,
693 # and provide result variables for the closure passed to ->child
694 my $current = $Coro::current;
695 my ($done, $rstatus);
696
697 # pass a closure to ->child
698 my $watcher = AnyEvent->child (pid => $pid, cb => sub {
699 $rstatus = $_[1]; # remember rstatus
700 $done = 1; # mark $rstatus as valud
701 });
702
703 # wait until the closure has been called
704 schedule while !$done;
705
706 $rstatus
707 }
708
709
609=head1 BUGS/LIMITATIONS 710=head1 BUGS/LIMITATIONS
610 711
611 - you must make very sure that no coro is still active on global 712=over 4
612 destruction. very bad things might happen otherwise (usually segfaults).
613 713
714=item fork with pthread backend
715
716When Coro is compiled using the pthread backend (which isn't recommended
717but required on many BSDs as their libcs are completely broken), then
718coroutines will not survive a fork. There is no known workaround except to
719fix your libc and use a saner backend.
720
721=item perl process emulation ("threads")
722
614 - this module is not thread-safe. You should only ever use this module 723This module is not perl-pseudo-thread-safe. You should only ever use this
615 from the same thread (this requirement might be loosened in the future 724module from the first thread (this requirement might be removed in the
616 to allow per-thread schedulers, but Coro::State does not yet allow 725future to allow per-thread schedulers, but Coro::State does not yet allow
617 this). 726this). I recommend disabling thread support and using processes, as having
727the windows process emulation enabled under unix roughly halves perl
728performance, even when not used.
729
730=item coroutine switching not signal safe
731
732You must not switch to another coroutine from within a signal handler
733(only relevant with %SIG - most event libraries provide safe signals).
734
735That means you I<MUST NOT> call any function that might "block" the
736current coroutine - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
737anything that calls those. Everything else, including calling C<ready>,
738works.
739
740=back
741
618 742
619=head1 SEE ALSO 743=head1 SEE ALSO
620 744
621Lower level Configuration, Coroutine Environment: L<Coro::State>. 745Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
622 746
623Debugging: L<Coro::Debug>. 747Debugging: L<Coro::Debug>.
624 748
625Support/Utility: L<Coro::Specific>, L<Coro::Util>. 749Support/Utility: L<Coro::Specific>, L<Coro::Util>.
626 750
627Locking/IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>, L<Coro::SemaphoreSet>, L<Coro::RWLock>. 751Locking and IPC: L<Coro::Signal>, L<Coro::Channel>, L<Coro::Semaphore>,
752L<Coro::SemaphoreSet>, L<Coro::RWLock>.
628 753
629Event/IO: L<Coro::Timer>, L<Coro::Event>, L<Coro::Handle>, L<Coro::Socket>. 754I/O and Timers: L<Coro::Timer>, L<Coro::Handle>, L<Coro::Socket>, L<Coro::AIO>.
630 755
631Compatibility: L<Coro::LWP>, L<Coro::Storable>, L<Coro::Select>. 756Compatibility with other modules: L<Coro::LWP> (but see also L<AnyEvent::HTTP> for
757a better-working alternative), L<Coro::BDB>, L<Coro::Storable>,
758L<Coro::Select>.
632 759
633Embedding: L<Coro::MakeMaker>. 760XS API: L<Coro::MakeMaker>.
761
762Low level Configuration, Thread Environment, Continuations: L<Coro::State>.
634 763
635=head1 AUTHOR 764=head1 AUTHOR
636 765
637 Marc Lehmann <schmorp@schmorp.de> 766 Marc Lehmann <schmorp@schmorp.de>
638 http://home.schmorp.de/ 767 http://home.schmorp.de/

Diff Legend

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