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

Comparing Coro/Coro.pm (file contents):
Revision 1.268 by root, Thu Oct 1 23:16:27 2009 UTC vs.
Revision 1.334 by root, Mon Jun 29 23:49:34 2015 UTC

16 cede; # yield to coro 16 cede; # yield to coro
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;
22 my $lock = new Coro::Semaphore; 21 my $lock = new Coro::Semaphore;
23 my $locked; 22 my $locked;
24 23
25 $lock->down; 24 $lock->down;
26 $locked = 1; 25 $locked = 1;
40points in your program, so locking and parallel access are rarely an 39points in your program, so locking and parallel access are rarely an
41issue, making thread programming much safer and easier than using other 40issue, making thread programming much safer and easier than using other
42thread models. 41thread models.
43 42
44Unlike the so-called "Perl threads" (which are not actually real threads 43Unlike the so-called "Perl threads" (which are not actually real threads
45but only the windows process emulation (see section of same name for more 44but only the windows process emulation (see section of same name for
46details) ported to unix, and as such act as processes), Coro provides 45more details) ported to UNIX, and as such act as processes), Coro
47a full shared address space, which makes communication between threads 46provides a full shared address space, which makes communication between
48very easy. And Coro's threads are fast, too: disabling the Windows 47threads very easy. And coro threads are fast, too: disabling the Windows
49process emulation code in your perl and using Coro can easily result in 48process emulation code in your perl and using Coro can easily result in
50a two to four times speed increase for your programs. A parallel matrix 49a two to four times speed increase for your programs. A parallel matrix
51multiplication benchmark runs over 300 times faster on a single core than 50multiplication benchmark (very communication-intensive) runs over 300
52perl's pseudo-threads on a quad core using all four cores. 51times faster on a single core than perls pseudo-threads on a quad core
52using all four cores.
53 53
54Coro achieves that by supporting multiple running interpreters that share 54Coro achieves that by supporting multiple running interpreters that share
55data, which is especially useful to code pseudo-parallel processes and 55data, which is especially useful to code pseudo-parallel processes and
56for event-based programming, such as multiple HTTP-GET requests running 56for event-based programming, such as multiple HTTP-GET requests running
57concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro 57concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro
63variables (see L<Coro::State> for more configuration and background info). 63variables (see L<Coro::State> for more configuration and background info).
64 64
65See also the C<SEE ALSO> section at the end of this document - the Coro 65See also the C<SEE ALSO> section at the end of this document - the Coro
66module family is quite large. 66module family is quite large.
67 67
68=head1 CORO THREAD LIFE CYCLE
69
70During the long and exciting (or not) life of a coro thread, it goes
71through a number of states:
72
73=over 4
74
75=item 1. Creation
76
77The first thing in the life of a coro thread is it's creation -
78obviously. The typical way to create a thread is to call the C<async
79BLOCK> function:
80
81 async {
82 # thread code goes here
83 };
84
85You can also pass arguments, which are put in C<@_>:
86
87 async {
88 print $_[1]; # prints 2
89 } 1, 2, 3;
90
91This creates a new coro thread and puts it into the ready queue, meaning
92it will run as soon as the CPU is free for it.
93
94C<async> will return a Coro object - you can store this for future
95reference or ignore it - a thread that is running, ready to run or waiting
96for some event is alive on it's own.
97
98Another way to create a thread is to call the C<new> constructor with a
99code-reference:
100
101 new Coro sub {
102 # thread code goes here
103 }, @optional_arguments;
104
105This is quite similar to calling C<async>, but the important difference is
106that the new thread is not put into the ready queue, so the thread will
107not run until somebody puts it there. C<async> is, therefore, identical to
108this sequence:
109
110 my $coro = new Coro sub {
111 # thread code goes here
112 };
113 $coro->ready;
114 return $coro;
115
116=item 2. Startup
117
118When a new coro thread is created, only a copy of the code reference
119and the arguments are stored, no extra memory for stacks and so on is
120allocated, keeping the coro thread in a low-memory state.
121
122Only when it actually starts executing will all the resources be finally
123allocated.
124
125The optional arguments specified at coro creation are available in C<@_>,
126similar to function calls.
127
128=item 3. Running / Blocking
129
130A lot can happen after the coro thread has started running. Quite usually,
131it will not run to the end in one go (because you could use a function
132instead), but it will give up the CPU regularly because it waits for
133external events.
134
135As long as a coro thread runs, its Coro object is available in the global
136variable C<$Coro::current>.
137
138The low-level way to give up the CPU is to call the scheduler, which
139selects a new coro thread to run:
140
141 Coro::schedule;
142
143Since running threads are not in the ready queue, calling the scheduler
144without doing anything else will block the coro thread forever - you need
145to arrange either for the coro to put woken up (readied) by some other
146event or some other thread, or you can put it into the ready queue before
147scheduling:
148
149 # this is exactly what Coro::cede does
150 $Coro::current->ready;
151 Coro::schedule;
152
153All the higher-level synchronisation methods (Coro::Semaphore,
154Coro::rouse_*...) are actually implemented via C<< ->ready >> and C<<
155Coro::schedule >>.
156
157While the coro thread is running it also might get assigned a C-level
158thread, or the C-level thread might be unassigned from it, as the Coro
159runtime wishes. A C-level thread needs to be assigned when your perl
160thread calls into some C-level function and that function in turn calls
161perl and perl then wants to switch coroutines. This happens most often
162when you run an event loop and block in the callback, or when perl
163itself calls some function such as C<AUTOLOAD> or methods via the C<tie>
164mechanism.
165
166=item 4. Termination
167
168Many threads actually terminate after some time. There are a number of
169ways to terminate a coro thread, the simplest is returning from the
170top-level code reference:
171
172 async {
173 # after returning from here, the coro thread is terminated
174 };
175
176 async {
177 return if 0.5 < rand; # terminate a little earlier, maybe
178 print "got a chance to print this\n";
179 # or here
180 };
181
182Any values returned from the coroutine can be recovered using C<< ->join
183>>:
184
185 my $coro = async {
186 "hello, world\n" # return a string
187 };
188
189 my $hello_world = $coro->join;
190
191 print $hello_world;
192
193Another way to terminate is to call C<< Coro::terminate >>, which at any
194subroutine call nesting level:
195
196 async {
197 Coro::terminate "return value 1", "return value 2";
198 };
199
200Yet another way is to C<< ->cancel >> (or C<< ->safe_cancel >>) the coro
201thread from another thread:
202
203 my $coro = async {
204 exit 1;
205 };
206
207 $coro->cancel; # also accepts values for ->join to retrieve
208
209Cancellation I<can> be dangerous - it's a bit like calling C<exit> without
210actually exiting, and might leave C libraries and XS modules in a weird
211state. Unlike other thread implementations, however, Coro is exceptionally
212safe with regards to cancellation, as perl will always be in a consistent
213state, and for those cases where you want to do truly marvellous things
214with your coro while it is being cancelled - that is, make sure all
215cleanup code is executed from the thread being cancelled - there is even a
216C<< ->safe_cancel >> method.
217
218So, cancelling a thread that runs in an XS event loop might not be the
219best idea, but any other combination that deals with perl only (cancelling
220when a thread is in a C<tie> method or an C<AUTOLOAD> for example) is
221safe.
222
223Last not least, a coro thread object that isn't referenced is C<<
224->cancel >>'ed automatically - just like other objects in Perl. This
225is not such a common case, however - a running thread is referencedy by
226C<$Coro::current>, a thread ready to run is referenced by the ready queue,
227a thread waiting on a lock or semaphore is referenced by being in some
228wait list and so on. But a thread that isn't in any of those queues gets
229cancelled:
230
231 async {
232 schedule; # cede to other coros, don't go into the ready queue
233 };
234
235 cede;
236 # now the async above is destroyed, as it is not referenced by anything.
237
238A slightly embellished example might make it clearer:
239
240 async {
241 my $guard = Guard::guard { print "destroyed\n" };
242 schedule while 1;
243 };
244
245 cede;
246
247Superficially one might not expect any output - since the C<async>
248implements an endless loop, the C<$guard> will not be cleaned up. However,
249since the thread object returned by C<async> is not stored anywhere, the
250thread is initially referenced because it is in the ready queue, when it
251runs it is referenced by C<$Coro::current>, but when it calls C<schedule>,
252it gets C<cancel>ed causing the guard object to be destroyed (see the next
253section), and printing it's message.
254
255If this seems a bit drastic, remember that this only happens when nothing
256references the thread anymore, which means there is no way to further
257execute it, ever. The only options at this point are leaking the thread,
258or cleaning it up, which brings us to...
259
260=item 5. Cleanup
261
262Threads will allocate various resources. Most but not all will be returned
263when a thread terminates, during clean-up.
264
265Cleanup is quite similar to throwing an uncaught exception: perl will
266work it's way up through all subroutine calls and blocks. On it's way, it
267will release all C<my> variables, undo all C<local>'s and free any other
268resources truly local to the thread.
269
270So, a common way to free resources is to keep them referenced only by my
271variables:
272
273 async {
274 my $big_cache = new Cache ...;
275 };
276
277If there are no other references, then the C<$big_cache> object will be
278freed when the thread terminates, regardless of how it does so.
279
280What it does C<NOT> do is unlock any Coro::Semaphores or similar
281resources, but that's where the C<guard> methods come in handy:
282
283 my $sem = new Coro::Semaphore;
284
285 async {
286 my $lock_guard = $sem->guard;
287 # if we return, or die or get cancelled, here,
288 # then the semaphore will be "up"ed.
289 };
290
291The C<Guard::guard> function comes in handy for any custom cleanup you
292might want to do (but you cannot switch to other coroutines from those
293code blocks):
294
295 async {
296 my $window = new Gtk2::Window "toplevel";
297 # The window will not be cleaned up automatically, even when $window
298 # gets freed, so use a guard to ensure it's destruction
299 # in case of an error:
300 my $window_guard = Guard::guard { $window->destroy };
301
302 # we are safe here
303 };
304
305Last not least, C<local> can often be handy, too, e.g. when temporarily
306replacing the coro thread description:
307
308 sub myfunction {
309 local $Coro::current->{desc} = "inside myfunction(@_)";
310
311 # if we return or die here, the description will be restored
312 }
313
314=item 6. Viva La Zombie Muerte
315
316Even after a thread has terminated and cleaned up its resources, the Coro
317object still is there and stores the return values of the thread.
318
319When there are no other references, it will simply be cleaned up and
320freed.
321
322If there areany references, the Coro object will stay around, and you
323can call C<< ->join >> as many times as you wish to retrieve the result
324values:
325
326 async {
327 print "hi\n";
328 1
329 };
330
331 # run the async above, and free everything before returning
332 # from Coro::cede:
333 Coro::cede;
334
335 {
336 my $coro = async {
337 print "hi\n";
338 1
339 };
340
341 # run the async above, and clean up, but do not free the coro
342 # object:
343 Coro::cede;
344
345 # optionally retrieve the result values
346 my @results = $coro->join;
347
348 # now $coro goes out of scope, and presumably gets freed
349 };
350
351=back
352
68=cut 353=cut
69 354
70package Coro; 355package Coro;
71 356
72use common::sense; 357use common::sense;
81 366
82our $idle; # idle handler 367our $idle; # idle handler
83our $main; # main coro 368our $main; # main coro
84our $current; # current coro 369our $current; # current coro
85 370
86our $VERSION = 5.17; 371our $VERSION = 6.45;
87 372
88our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 373our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait);
89our %EXPORT_TAGS = ( 374our %EXPORT_TAGS = (
90 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 375 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
91); 376);
92our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); 377our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
93 378
96=over 4 381=over 4
97 382
98=item $Coro::main 383=item $Coro::main
99 384
100This variable stores the Coro object that represents the main 385This variable stores the Coro object that represents the main
101program. While you cna C<ready> it and do most other things you can do to 386program. While you can C<ready> it and do most other things you can do to
102coro, it is mainly useful to compare again C<$Coro::current>, to see 387coro, it is mainly useful to compare again C<$Coro::current>, to see
103whether you are running in the main program or not. 388whether you are running in the main program or not.
104 389
105=cut 390=cut
106 391
124 409
125This variable is mainly useful to integrate Coro into event loops. It is 410This variable is mainly useful to integrate Coro into event loops. It is
126usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is 411usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is
127pretty low-level functionality. 412pretty low-level functionality.
128 413
129This variable stores either a Coro object or a callback. 414This variable stores a Coro object that is put into the ready queue when
415there are no other ready threads (without invoking any ready hooks).
130 416
131If it is a callback, the it is called whenever the scheduler finds no 417The default implementation dies with "FATAL: deadlock detected.", followed
132ready coros to run. The default implementation prints "FATAL: 418by a thread listing, because the program has no other way to continue.
133deadlock detected" and exits, because the program has no other way to
134continue.
135
136If it is a coro object, then this object will be readied (without
137invoking any ready hooks, however) when the scheduler finds no other ready
138coros to run.
139 419
140This hook is overwritten by modules such as C<Coro::EV> and 420This hook is overwritten by modules such as C<Coro::EV> and
141C<Coro::AnyEvent> to wait on an external event that hopefully wake up a 421C<Coro::AnyEvent> to wait on an external event that hopefully wakes up a
142coro so the scheduler can run it. 422coro so the scheduler can run it.
143 423
144Note that the callback I<must not>, under any circumstances, block
145the current coro. Normally, this is achieved by having an "idle
146coro" that calls the event loop and then blocks again, and then
147readying that coro in the idle handler, or by simply placing the idle
148coro in this variable.
149
150See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this 424See L<Coro::EV> or L<Coro::AnyEvent> for examples of using this technique.
151technique.
152
153Please note that if your callback recursively invokes perl (e.g. for event
154handlers), then it must be prepared to be called recursively itself.
155 425
156=cut 426=cut
157 427
158$idle = sub { 428# ||= because other modules could have provided their own by now
159 warn "oi\n";#d# 429$idle ||= new Coro sub {
160 Carp::confess ("FATAL: deadlock detected"); 430 require Coro::Debug;
431 die "FATAL: deadlock detected.\n"
432 . Coro::Debug::ps_listing ();
161}; 433};
162 434
163# this coro is necessary because a coro 435# this coro is necessary because a coro
164# cannot destroy itself. 436# cannot destroy itself.
165our @destroy; 437our @destroy;
166our $manager; 438our $manager;
167 439
168$manager = new Coro sub { 440$manager = new Coro sub {
169 while () { 441 while () {
170 Coro::State::cancel shift @destroy 442 _destroy shift @destroy
171 while @destroy; 443 while @destroy;
172 444
173 &schedule; 445 &schedule;
174 } 446 }
175}; 447};
273=item schedule 545=item schedule
274 546
275Calls the scheduler. The scheduler will find the next coro that is 547Calls the scheduler. The scheduler will find the next coro that is
276to be run from the ready queue and switches to it. The next coro 548to be run from the ready queue and switches to it. The next coro
277to be run is simply the one with the highest priority that is longest 549to be run is simply the one with the highest priority that is longest
278in its ready queue. If there is no coro ready, it will clal the 550in its ready queue. If there is no coro ready, it will call the
279C<$Coro::idle> hook. 551C<$Coro::idle> hook.
280 552
281Please note that the current coro will I<not> be put into the ready 553Please note that the current coro will I<not> be put into the ready
282queue, so calling this function usually means you will never be called 554queue, so calling this function usually means you will never be called
283again unless something else (e.g. an event handler) calls C<< ->ready >>, 555again unless something else (e.g. an event handler) calls C<< ->ready >>,
309coro, regardless of priority. This is useful sometimes to ensure 581coro, regardless of priority. This is useful sometimes to ensure
310progress is made. 582progress is made.
311 583
312=item terminate [arg...] 584=item terminate [arg...]
313 585
314Terminates the current coro with the given status values (see L<cancel>). 586Terminates the current coro with the given status values (see
587L<cancel>). The values will not be copied, but referenced directly.
315 588
316=item Coro::on_enter BLOCK, Coro::on_leave BLOCK 589=item Coro::on_enter BLOCK, Coro::on_leave BLOCK
317 590
318These function install enter and leave winders in the current scope. The 591These function install enter and leave winders in the current scope. The
319enter block will be executed when on_enter is called and whenever the 592enter block will be executed when on_enter is called and whenever the
379 Coro::on_enter { 652 Coro::on_enter {
380 # on entering the thread, we set an VTALRM handler to cede 653 # on entering the thread, we set an VTALRM handler to cede
381 $SIG{VTALRM} = sub { cede }; 654 $SIG{VTALRM} = sub { cede };
382 # and then start the interval timer 655 # and then start the interval timer
383 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01; 656 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
384 }; 657 };
385 Coro::on_leave { 658 Coro::on_leave {
386 # on leaving the thread, we stop the interval timer again 659 # on leaving the thread, we stop the interval timer again
387 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0; 660 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
388 }; 661 };
389 662
390 &{+shift}; 663 &{+shift};
391 } 664 }
392 665
393 # use like this: 666 # use like this:
394 timeslice { 667 timeslice {
395 # The following is an endless loop that would normally 668 # The following is an endless loop that would normally
396 # monopolise the process. Since it runs in a timesliced 669 # monopolise the process. Since it runs in a timesliced
397 # environment, it will regularly cede to other threads. 670 # environment, it will regularly cede to other threads.
398 while () { } 671 while () { }
399 }; 672 };
400 673
401 674
402=item killall 675=item killall
403 676
404Kills/terminates/cancels all coros except the currently running one. 677Kills/terminates/cancels all coros except the currently running one.
475To avoid this, it is best to put a suspended coro into the ready queue 748To avoid this, it is best to put a suspended coro into the ready queue
476unconditionally, as every synchronisation mechanism must protect itself 749unconditionally, as every synchronisation mechanism must protect itself
477against spurious wakeups, and the one in the Coro family certainly do 750against spurious wakeups, and the one in the Coro family certainly do
478that. 751that.
479 752
753=item $state->is_new
754
755Returns true iff this Coro object is "new", i.e. has never been run
756yet. Those states basically consist of only the code reference to call and
757the arguments, but consumes very little other resources. New states will
758automatically get assigned a perl interpreter when they are transfered to.
759
760=item $state->is_zombie
761
762Returns true iff the Coro object has been cancelled, i.e.
763it's resources freed because they were C<cancel>'ed, C<terminate>'d,
764C<safe_cancel>'ed or simply went out of scope.
765
766The name "zombie" stems from UNIX culture, where a process that has
767exited and only stores and exit status and no other resources is called a
768"zombie".
769
480=item $is_ready = $coro->is_ready 770=item $is_ready = $coro->is_ready
481 771
482Returns true iff the Coro object is in the ready queue. Unless the Coro 772Returns true iff the Coro object is in the ready queue. Unless the Coro
483object gets destroyed, it will eventually be scheduled by the scheduler. 773object gets destroyed, it will eventually be scheduled by the scheduler.
484 774
493Returns true iff this Coro object has been suspended. Suspended Coros will 783Returns true iff this Coro object has been suspended. Suspended Coros will
494not ever be scheduled. 784not ever be scheduled.
495 785
496=item $coro->cancel (arg...) 786=item $coro->cancel (arg...)
497 787
498Terminates the given Coro and makes it return the given arguments as 788Terminates the given Coro thread and makes it return the given arguments as
499status (default: the empty list). Never returns if the Coro is the 789status (default: an empty list). Never returns if the Coro is the
500current Coro. 790current Coro.
501 791
502=cut 792This is a rather brutal way to free a coro, with some limitations - if
793the thread is inside a C callback that doesn't expect to be canceled,
794bad things can happen, or if the cancelled thread insists on running
795complicated cleanup handlers that rely on its thread context, things will
796not work.
503 797
504sub cancel { 798Any cleanup code being run (e.g. from C<guard> blocks, destructors and so
505 my $self = shift; 799on) will be run without a thread context, and is not allowed to switch
800to other threads. A common mistake is to call C<< ->cancel >> from a
801destructor called by die'ing inside the thread to be cancelled for
802example.
506 803
507 if ($current == $self) { 804On the plus side, C<< ->cancel >> will always clean up the thread, no
508 terminate @_; 805matter what. If your cleanup code is complex or you want to avoid
509 } else { 806cancelling a C-thread that doesn't know how to clean up itself, it can be
510 $self->{_status} = [@_]; 807better to C<< ->throw >> an exception, or use C<< ->safe_cancel >>.
511 Coro::State::cancel $self; 808
809The arguments to C<< ->cancel >> are not copied, but instead will
810be referenced directly (e.g. if you pass C<$var> and after the call
811change that variable, then you might change the return values passed to
812e.g. C<join>, so don't do that).
813
814The resources of the Coro are usually freed (or destructed) before this
815call returns, but this can be delayed for an indefinite amount of time, as
816in some cases the manager thread has to run first to actually destruct the
817Coro object.
818
819=item $coro->safe_cancel ($arg...)
820
821Works mostly like C<< ->cancel >>, but is inherently "safer", and
822consequently, can fail with an exception in cases the thread is not in a
823cancellable state. Essentially, C<< ->safe_cancel >> is a C<< ->cancel >>
824with extra checks before canceling.
825
826It works a bit like throwing an exception that cannot be caught -
827specifically, it will clean up the thread from within itself, so all
828cleanup handlers (e.g. C<guard> blocks) are run with full thread
829context and can block if they wish. The downside is that there is no
830guarantee that the thread can be cancelled when you call this method, and
831therefore, it might fail. It is also considerably slower than C<cancel> or
832C<terminate>.
833
834A thread is in a safe-cancellable state if it either hasn't been run yet,
835or it has no C context attached and is inside an SLF function.
836
837The latter two basically mean that the thread isn't currently inside a
838perl callback called from some C function (usually via some XS modules)
839and isn't currently executing inside some C function itself (via Coro's XS
840API).
841
842This call returns true when it could cancel the thread, or croaks with an
843error otherwise (i.e. it either returns true or doesn't return at all).
844
845Why the weird interface? Well, there are two common models on how and
846when to cancel things. In the first, you have the expectation that your
847coro thread can be cancelled when you want to cancel it - if the thread
848isn't cancellable, this would be a bug somewhere, so C<< ->safe_cancel >>
849croaks to notify of the bug.
850
851In the second model you sometimes want to ask nicely to cancel a thread,
852but if it's not a good time, well, then don't cancel. This can be done
853relatively easy like this:
854
855 if (! eval { $coro->safe_cancel }) {
856 warn "unable to cancel thread: $@";
512 } 857 }
513} 858
859However, what you never should do is first try to cancel "safely" and
860if that fails, cancel the "hard" way with C<< ->cancel >>. That makes
861no sense: either you rely on being able to execute cleanup code in your
862thread context, or you don't. If you do, then C<< ->safe_cancel >> is the
863only way, and if you don't, then C<< ->cancel >> is always faster and more
864direct.
514 865
515=item $coro->schedule_to 866=item $coro->schedule_to
516 867
517Puts the current coro to sleep (like C<Coro::schedule>), but instead 868Puts the current coro to sleep (like C<Coro::schedule>), but instead
518of continuing with the next coro from the ready queue, always switch to 869of continuing with the next coro from the ready queue, always switch to
537inside the coro at the next convenient point in time. Otherwise 888inside the coro at the next convenient point in time. Otherwise
538clears the exception object. 889clears the exception object.
539 890
540Coro will check for the exception each time a schedule-like-function 891Coro will check for the exception each time a schedule-like-function
541returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down 892returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down
542>>, C<< Coro::Handle->readable >> and so on. Most of these functions 893>>, C<< Coro::Handle->readable >> and so on. Most of those functions (all
543detect this case and return early in case an exception is pending. 894that are part of Coro itself) detect this case and return early in case an
895exception is pending.
544 896
545The exception object will be thrown "as is" with the specified scalar in 897The exception object will be thrown "as is" with the specified scalar in
546C<$@>, i.e. if it is a string, no line number or newline will be appended 898C<$@>, i.e. if it is a string, no line number or newline will be appended
547(unlike with C<die>). 899(unlike with C<die>).
548 900
549This can be used as a softer means than C<cancel> to ask a coro to 901This can be used as a softer means than either C<cancel> or C<safe_cancel
550end itself, although there is no guarantee that the exception will lead to 902>to ask a coro to end itself, although there is no guarantee that the
551termination, and if the exception isn't caught it might well end the whole 903exception will lead to termination, and if the exception isn't caught it
552program. 904might well end the whole program.
553 905
554You might also think of C<throw> as being the moral equivalent of 906You might also think of C<throw> as being the moral equivalent of
555C<kill>ing a coro with a signal (in this case, a scalar). 907C<kill>ing a coro with a signal (in this case, a scalar).
556 908
557=item $coro->join 909=item $coro->join
558 910
559Wait until the coro terminates and return any values given to the 911Wait until the coro terminates and return any values given to the
560C<terminate> or C<cancel> functions. C<join> can be called concurrently 912C<terminate> or C<cancel> functions. C<join> can be called concurrently
561from multiple coro, and all will be resumed and given the status 913from multiple threads, and all will be resumed and given the status
562return once the C<$coro> terminates. 914return once the C<$coro> terminates.
563 915
564=cut
565
566sub join {
567 my $self = shift;
568
569 unless ($self->{_status}) {
570 my $current = $current;
571
572 push @{$self->{_on_destroy}}, sub {
573 $current->ready;
574 undef $current;
575 };
576
577 &schedule while $current;
578 }
579
580 wantarray ? @{$self->{_status}} : $self->{_status}[0];
581}
582
583=item $coro->on_destroy (\&cb) 916=item $coro->on_destroy (\&cb)
584 917
585Registers a callback that is called when this coro gets destroyed, 918Registers a callback that is called when this coro thread gets destroyed,
586but before it is joined. The callback gets passed the terminate arguments, 919that is, after it's resources have been freed but before it is joined. The
920callback gets passed the terminate/cancel arguments, if any, and I<must
587if any, and I<must not> die, under any circumstances. 921not> die, under any circumstances.
588 922
589=cut 923There can be any number of C<on_destroy> callbacks per coro, and there is
590 924currently no way to remove a callback once added.
591sub on_destroy {
592 my ($self, $cb) = @_;
593
594 push @{ $self->{_on_destroy} }, $cb;
595}
596 925
597=item $oldprio = $coro->prio ($newprio) 926=item $oldprio = $coro->prio ($newprio)
598 927
599Sets (or gets, if the argument is missing) the priority of the 928Sets (or gets, if the argument is missing) the priority of the
600coro. Higher priority coro get run before lower priority 929coro thread. Higher priority coro get run before lower priority
601coro. Priorities are small signed integers (currently -4 .. +3), 930coros. Priorities are small signed integers (currently -4 .. +3),
602that you can refer to using PRIO_xxx constants (use the import tag :prio 931that you can refer to using PRIO_xxx constants (use the import tag :prio
603to get then): 932to get then):
604 933
605 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN 934 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
606 3 > 1 > 0 > -1 > -3 > -4 935 3 > 1 > 0 > -1 > -3 > -4
607 936
608 # set priority to HIGH 937 # set priority to HIGH
609 current->prio (PRIO_HIGH); 938 current->prio (PRIO_HIGH);
610 939
611The idle coro ($Coro::idle) always has a lower priority than any 940The idle coro thread ($Coro::idle) always has a lower priority than any
612existing coro. 941existing coro.
613 942
614Changing the priority of the current coro will take effect immediately, 943Changing the priority of the current coro will take effect immediately,
615but changing the priority of coro in the ready queue (but not 944but changing the priority of a coro in the ready queue (but not running)
616running) will only take effect after the next schedule (of that 945will only take effect after the next schedule (of that coro). This is a
617coro). This is a bug that will be fixed in some future version. 946bug that will be fixed in some future version.
618 947
619=item $newprio = $coro->nice ($change) 948=item $newprio = $coro->nice ($change)
620 949
621Similar to C<prio>, but subtract the given value from the priority (i.e. 950Similar to C<prio>, but subtract the given value from the priority (i.e.
622higher values mean lower priority, just as in unix). 951higher values mean lower priority, just as in UNIX's nice command).
623 952
624=item $olddesc = $coro->desc ($newdesc) 953=item $olddesc = $coro->desc ($newdesc)
625 954
626Sets (or gets in case the argument is missing) the description for this 955Sets (or gets in case the argument is missing) the description for this
627coro. This is just a free-form string you can associate with a 956coro thread. This is just a free-form string you can associate with a
628coro. 957coro.
629 958
630This method simply sets the C<< $coro->{desc} >> member to the given 959This method simply sets the C<< $coro->{desc} >> member to the given
631string. You can modify this member directly if you wish. 960string. You can modify this member directly if you wish, and in fact, this
961is often preferred to indicate major processing states that can then be
962seen for example in a L<Coro::Debug> session:
963
964 sub my_long_function {
965 local $Coro::current->{desc} = "now in my_long_function";
966 ...
967 $Coro::current->{desc} = "my_long_function: phase 1";
968 ...
969 $Coro::current->{desc} = "my_long_function: phase 2";
970 ...
971 }
632 972
633=cut 973=cut
634 974
635sub desc { 975sub desc {
636 my $old = $_[0]{desc}; 976 my $old = $_[0]{desc};
673returning a new coderef. Unblocking means that calling the new coderef 1013returning a new coderef. Unblocking means that calling the new coderef
674will return immediately without blocking, returning nothing, while the 1014will return immediately without blocking, returning nothing, while the
675original code ref will be called (with parameters) from within another 1015original code ref will be called (with parameters) from within another
676coro. 1016coro.
677 1017
678The reason this function exists is that many event libraries (such as the 1018The reason this function exists is that many event libraries (such as
679venerable L<Event|Event> module) are not thread-safe (a weaker form 1019the venerable L<Event|Event> module) are not thread-safe (a weaker form
680of reentrancy). This means you must not block within event callbacks, 1020of reentrancy). This means you must not block within event callbacks,
681otherwise you might suffer from crashes or worse. The only event library 1021otherwise you might suffer from crashes or worse. The only event library
682currently known that is safe to use without C<unblock_sub> is L<EV>. 1022currently known that is safe to use without C<unblock_sub> is L<EV> (but
1023you might still run into deadlocks if all event loops are blocked).
1024
1025Coro will try to catch you when you block in the event loop
1026("FATAL: $Coro::idle blocked itself"), but this is just best effort and
1027only works when you do not run your own event loop.
683 1028
684This function allows your callbacks to block by executing them in another 1029This function allows your callbacks to block by executing them in another
685coro where it is safe to block. One example where blocking is handy 1030coro where it is safe to block. One example where blocking is handy
686is when you use the L<Coro::AIO|Coro::AIO> functions to save results to 1031is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
687disk, for example. 1032disk, for example.
729 unshift @unblock_queue, [$cb, @_]; 1074 unshift @unblock_queue, [$cb, @_];
730 $unblock_scheduler->ready; 1075 $unblock_scheduler->ready;
731 } 1076 }
732} 1077}
733 1078
734=item $cb = Coro::rouse_cb 1079=item $cb = rouse_cb
735 1080
736Create and return a "rouse callback". That's a code reference that, 1081Create and return a "rouse callback". That's a code reference that,
737when called, will remember a copy of its arguments and notify the owner 1082when called, will remember a copy of its arguments and notify the owner
738coro of the callback. 1083coro of the callback.
739 1084
740See the next function. 1085See the next function.
741 1086
742=item @args = Coro::rouse_wait [$cb] 1087=item @args = rouse_wait [$cb]
743 1088
744Wait for the specified rouse callback (or the last one that was created in 1089Wait for the specified rouse callback (or the last one that was created in
745this coro). 1090this coro).
746 1091
747As soon as the callback is invoked (or when the callback was invoked 1092As soon as the callback is invoked (or when the callback was invoked
754 1099
755=back 1100=back
756 1101
757=cut 1102=cut
758 1103
1104for my $module (qw(Channel RWLock Semaphore SemaphoreSet Signal Specific)) {
1105 my $old = defined &{"Coro::$module\::new"} && \&{"Coro::$module\::new"};
1106
1107 *{"Coro::$module\::new"} = sub {
1108 require "Coro/$module.pm";
1109
1110 # some modules have their new predefined in State.xs, some don't
1111 *{"Coro::$module\::new"} = $old
1112 if $old;
1113
1114 goto &{"Coro::$module\::new"};
1115 };
1116}
1117
7591; 11181;
760 1119
761=head1 HOW TO WAIT FOR A CALLBACK 1120=head1 HOW TO WAIT FOR A CALLBACK
762 1121
763It is very common for a coro to wait for some callback to be 1122It is very common for a coro to wait for some callback to be
776But from within a coro, you often just want to write this: 1135But from within a coro, you often just want to write this:
777 1136
778 my $status = wait_for_child $pid; 1137 my $status = wait_for_child $pid;
779 1138
780Coro offers two functions specifically designed to make this easy, 1139Coro offers two functions specifically designed to make this easy,
781C<Coro::rouse_cb> and C<Coro::rouse_wait>. 1140C<rouse_cb> and C<rouse_wait>.
782 1141
783The first function, C<rouse_cb>, generates and returns a callback that, 1142The first function, C<rouse_cb>, generates and returns a callback that,
784when invoked, will save its arguments and notify the coro that 1143when invoked, will save its arguments and notify the coro that
785created the callback. 1144created the callback.
786 1145
792function mentioned above: 1151function mentioned above:
793 1152
794 sub wait_for_child($) { 1153 sub wait_for_child($) {
795 my ($pid) = @_; 1154 my ($pid) = @_;
796 1155
797 my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb); 1156 my $watcher = AnyEvent->child (pid => $pid, cb => rouse_cb);
798 1157
799 my ($rpid, $rstatus) = Coro::rouse_wait; 1158 my ($rpid, $rstatus) = rouse_wait;
800 $rstatus 1159 $rstatus
801 } 1160 }
802 1161
803In the case where C<rouse_cb> and C<rouse_wait> are not flexible enough, 1162In the case where C<rouse_cb> and C<rouse_wait> are not flexible enough,
804you can roll your own, using C<schedule>: 1163you can roll your own, using C<schedule> and C<ready>:
805 1164
806 sub wait_for_child($) { 1165 sub wait_for_child($) {
807 my ($pid) = @_; 1166 my ($pid) = @_;
808 1167
809 # store the current coro in $current, 1168 # store the current coro in $current,
812 my ($done, $rstatus); 1171 my ($done, $rstatus);
813 1172
814 # pass a closure to ->child 1173 # pass a closure to ->child
815 my $watcher = AnyEvent->child (pid => $pid, cb => sub { 1174 my $watcher = AnyEvent->child (pid => $pid, cb => sub {
816 $rstatus = $_[1]; # remember rstatus 1175 $rstatus = $_[1]; # remember rstatus
817 $done = 1; # mark $rstatus as valud 1176 $done = 1; # mark $rstatus as valid
1177 $current->ready; # wake up the waiting thread
818 }); 1178 });
819 1179
820 # wait until the closure has been called 1180 # wait until the closure has been called
821 schedule while !$done; 1181 schedule while !$done;
822 1182
842future to allow per-thread schedulers, but Coro::State does not yet allow 1202future to allow per-thread schedulers, but Coro::State does not yet allow
843this). I recommend disabling thread support and using processes, as having 1203this). I recommend disabling thread support and using processes, as having
844the windows process emulation enabled under unix roughly halves perl 1204the windows process emulation enabled under unix roughly halves perl
845performance, even when not used. 1205performance, even when not used.
846 1206
1207Attempts to use threads created in another emulated process will crash
1208("cleanly", with a null pointer exception).
1209
847=item coro switching is not signal safe 1210=item coro switching is not signal safe
848 1211
849You must not switch to another coro from within a signal handler 1212You must not switch to another coro from within a signal handler (only
850(only relevant with %SIG - most event libraries provide safe signals). 1213relevant with %SIG - most event libraries provide safe signals), I<unless>
1214you are sure you are not interrupting a Coro function.
851 1215
852That means you I<MUST NOT> call any function that might "block" the 1216That means you I<MUST NOT> call any function that might "block" the
853current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or 1217current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
854anything that calls those. Everything else, including calling C<ready>, 1218anything that calls those. Everything else, including calling C<ready>,
855works. 1219works.
865ithreads (for example, that memory or files would be shared), showing his 1229ithreads (for example, that memory or files would be shared), showing his
866lack of understanding of this area - if it is hard to understand for Chip, 1230lack of understanding of this area - if it is hard to understand for Chip,
867it is probably not obvious to everybody). 1231it is probably not obvious to everybody).
868 1232
869What follows is an ultra-condensed version of my talk about threads in 1233What follows is an ultra-condensed version of my talk about threads in
870scripting languages given onthe perl workshop 2009: 1234scripting languages given on the perl workshop 2009:
871 1235
872The so-called "ithreads" were originally implemented for two reasons: 1236The so-called "ithreads" were originally implemented for two reasons:
873first, to (badly) emulate unix processes on native win32 perls, and 1237first, to (badly) emulate unix processes on native win32 perls, and
874secondly, to replace the older, real thread model ("5.005-threads"). 1238secondly, to replace the older, real thread model ("5.005-threads").
875 1239
937 1301
938XS API: L<Coro::MakeMaker>. 1302XS API: L<Coro::MakeMaker>.
939 1303
940Low level Configuration, Thread Environment, Continuations: L<Coro::State>. 1304Low level Configuration, Thread Environment, Continuations: L<Coro::State>.
941 1305
942=head1 AUTHOR 1306=head1 AUTHOR/SUPPORT/CONTACT
943 1307
944 Marc Lehmann <schmorp@schmorp.de> 1308 Marc A. Lehmann <schmorp@schmorp.de>
945 http://home.schmorp.de/ 1309 http://software.schmorp.de/pkg/Coro.html
946 1310
947=cut 1311=cut
948 1312

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines