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

Diff Legend

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