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

Comparing Coro/Coro.pm (file contents):
Revision 1.251 by root, Mon Mar 16 22:22:12 2009 UTC vs.
Revision 1.321 by root, Sun Feb 2 03:26:06 2014 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 ported to unix, and as such act 44but only the windows process emulation (see section of same name for
46as processes), Coro provides a full shared address space, which makes 45more details) ported to UNIX, and as such act as processes), Coro
47communication between threads very easy. And Coro's threads are fast, 46provides a full shared address space, which makes communication between
48too: disabling the Windows process emulation code in your perl and using 47threads very easy. And coro threads are fast, too: disabling the Windows
49Coro can easily result in a two to four times speed increase for your 48process emulation code in your perl and using Coro can easily result in
50programs. A parallel matrix multiplication benchmark runs over 300 times 49a two to four times speed increase for your programs. A parallel matrix
50multiplication benchmark (very communication-intensive) runs over 300
51faster on a single core than perl's pseudo-threads on a quad core using 51times faster on a single core than perls pseudo-threads on a quad core
52all four cores. 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 strict qw(vars subs); 357use common::sense;
73no warnings "uninitialized"; 358
359use Carp ();
74 360
75use Guard (); 361use Guard ();
76 362
77use Coro::State; 363use Coro::State;
78 364
80 366
81our $idle; # idle handler 367our $idle; # idle handler
82our $main; # main coro 368our $main; # main coro
83our $current; # current coro 369our $current; # current coro
84 370
85our $VERSION = 5.131; 371our $VERSION = 6.33;
86 372
87our @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);
88our %EXPORT_TAGS = ( 374our %EXPORT_TAGS = (
89 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)],
90); 376);
91our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); 377our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
92 378
95=over 4 381=over 4
96 382
97=item $Coro::main 383=item $Coro::main
98 384
99This variable stores the Coro object that represents the main 385This variable stores the Coro object that represents the main
100program. 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
101coro, 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
102whether you are running in the main program or not. 388whether you are running in the main program or not.
103 389
104=cut 390=cut
105 391
123 409
124This 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
125usually 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
126pretty low-level functionality. 412pretty low-level functionality.
127 413
128This 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).
129 416
130If it is a callback, the it is called whenever the scheduler finds no 417The default implementation dies with "FATAL: deadlock detected.", followed
131ready coros to run. The default implementation prints "FATAL: 418by a thread listing, because the program has no other way to continue.
132deadlock detected" and exits, because the program has no other way to
133continue.
134
135If it is a coro object, then this object will be readied (without
136invoking any ready hooks, however) when the scheduler finds no other ready
137coros to run.
138 419
139This hook is overwritten by modules such as C<Coro::EV> and 420This hook is overwritten by modules such as C<Coro::EV> and
140C<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
141coro so the scheduler can run it. 422coro so the scheduler can run it.
142 423
143Note that the callback I<must not>, under any circumstances, block
144the current coro. Normally, this is achieved by having an "idle
145coro" that calls the event loop and then blocks again, and then
146readying that coro in the idle handler, or by simply placing the idle
147coro in this variable.
148
149See 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.
150technique.
151
152Please note that if your callback recursively invokes perl (e.g. for event
153handlers), then it must be prepared to be called recursively itself.
154 425
155=cut 426=cut
156 427
157$idle = sub { 428# ||= because other modules could have provided their own by now
158 require Carp; 429$idle ||= new Coro sub {
159 Carp::croak ("FATAL: deadlock detected"); 430 require Coro::Debug;
431 die "FATAL: deadlock detected.\n"
432 . Coro::Debug::ps_listing ();
160}; 433};
161 434
162# this coro is necessary because a coro 435# this coro is necessary because a coro
163# cannot destroy itself. 436# cannot destroy itself.
164our @destroy; 437our @destroy;
165our $manager; 438our $manager;
166 439
167$manager = new Coro sub { 440$manager = new Coro sub {
168 while () { 441 while () {
169 Coro::State::cancel shift @destroy 442 _destroy shift @destroy
170 while @destroy; 443 while @destroy;
171 444
172 &schedule; 445 &schedule;
173 } 446 }
174}; 447};
206Example: Create a new coro that just prints its arguments. 479Example: Create a new coro that just prints its arguments.
207 480
208 async { 481 async {
209 print "@_\n"; 482 print "@_\n";
210 } 1,2,3,4; 483 } 1,2,3,4;
211
212=cut
213
214sub async(&@) {
215 my $coro = new Coro @_;
216 $coro->ready;
217 $coro
218}
219 484
220=item async_pool { ... } [@args...] 485=item async_pool { ... } [@args...]
221 486
222Similar to C<async>, but uses a coro pool, so you should not call 487Similar to C<async>, but uses a coro pool, so you should not call
223terminate or join on it (although you are allowed to), and you get a 488terminate or join on it (although you are allowed to), and you get a
280=item schedule 545=item schedule
281 546
282Calls the scheduler. The scheduler will find the next coro that is 547Calls the scheduler. The scheduler will find the next coro that is
283to 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
284to 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
285in 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
286C<$Coro::idle> hook. 551C<$Coro::idle> hook.
287 552
288Please 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
289queue, so calling this function usually means you will never be called 554queue, so calling this function usually means you will never be called
290again unless something else (e.g. an event handler) calls C<< ->ready >>, 555again unless something else (e.g. an event handler) calls C<< ->ready >>,
316coro, regardless of priority. This is useful sometimes to ensure 581coro, regardless of priority. This is useful sometimes to ensure
317progress is made. 582progress is made.
318 583
319=item terminate [arg...] 584=item terminate [arg...]
320 585
321Terminates 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.
322 588
323=item Coro::on_enter BLOCK, Coro::on_leave BLOCK 589=item Coro::on_enter BLOCK, Coro::on_leave BLOCK
324 590
325These function install enter and leave winders in the current scope. The 591These function install enter and leave winders in the current scope. The
326enter 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
338 604
339These functions implement the same concept as C<dynamic-wind> in scheme 605These functions implement the same concept as C<dynamic-wind> in scheme
340does, and are useful when you want to localise some resource to a specific 606does, and are useful when you want to localise some resource to a specific
341coro. 607coro.
342 608
343They slow down coro switching considerably for coros that use 609They slow down thread switching considerably for coros that use them
344them (But coro switching is still reasonably fast if the handlers are 610(about 40% for a BLOCK with a single assignment, so thread switching is
345fast). 611still reasonably fast if the handlers are fast).
346 612
347These functions are best understood by an example: The following function 613These functions are best understood by an example: The following function
348will change the current timezone to "Antarctica/South_Pole", which 614will change the current timezone to "Antarctica/South_Pole", which
349requires a call to C<tzset>, but by using C<on_enter> and C<on_leave>, 615requires a call to C<tzset>, but by using C<on_enter> and C<on_leave>,
350which remember/change the current timezone and restore the previous 616which remember/change the current timezone and restore the previous
351value, respectively, the timezone is only changes for the coro that 617value, respectively, the timezone is only changed for the coro that
352installed those handlers. 618installed those handlers.
353 619
354 use POSIX qw(tzset); 620 use POSIX qw(tzset);
355 621
356 async { 622 async {
373 }; 639 };
374 640
375This can be used to localise about any resource (locale, uid, current 641This can be used to localise about any resource (locale, uid, current
376working directory etc.) to a block, despite the existance of other 642working directory etc.) to a block, despite the existance of other
377coros. 643coros.
644
645Another interesting example implements time-sliced multitasking using
646interval timers (this could obviously be optimised, but does the job):
647
648 # "timeslice" the given block
649 sub timeslice(&) {
650 use Time::HiRes ();
651
652 Coro::on_enter {
653 # on entering the thread, we set an VTALRM handler to cede
654 $SIG{VTALRM} = sub { cede };
655 # and then start the interval timer
656 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
657 };
658 Coro::on_leave {
659 # on leaving the thread, we stop the interval timer again
660 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
661 };
662
663 &{+shift};
664 }
665
666 # use like this:
667 timeslice {
668 # The following is an endless loop that would normally
669 # monopolise the process. Since it runs in a timesliced
670 # environment, it will regularly cede to other threads.
671 while () { }
672 };
673
378 674
379=item killall 675=item killall
380 676
381Kills/terminates/cancels all coros except the currently running one. 677Kills/terminates/cancels all coros except the currently running one.
382 678
452To 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
453unconditionally, as every synchronisation mechanism must protect itself 749unconditionally, as every synchronisation mechanism must protect itself
454against spurious wakeups, and the one in the Coro family certainly do 750against spurious wakeups, and the one in the Coro family certainly do
455that. 751that.
456 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
457=item $is_ready = $coro->is_ready 770=item $is_ready = $coro->is_ready
458 771
459Returns 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
460object gets destroyed, it will eventually be scheduled by the scheduler. 773object gets destroyed, it will eventually be scheduled by the scheduler.
461 774
470Returns true iff this Coro object has been suspended. Suspended Coros will 783Returns true iff this Coro object has been suspended. Suspended Coros will
471not ever be scheduled. 784not ever be scheduled.
472 785
473=item $coro->cancel (arg...) 786=item $coro->cancel (arg...)
474 787
475Terminates the given Coro and makes it return the given arguments as 788Terminates the given Coro thread and makes it return the given arguments as
476status (default: the empty list). Never returns if the Coro is the 789status (default: an empty list). Never returns if the Coro is the
477current Coro. 790current Coro.
478 791
479=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.
480 797
481sub cancel { 798Any cleanup code being run (e.g. from C<guard> blocks) will be run without
482 my $self = shift; 799a thread context, and is not allowed to switch to other threads. On the
800plus side, C<< ->cancel >> will always clean up the thread, no matter
801what. If your cleanup code is complex or you want to avoid cancelling a
802C-thread that doesn't know how to clean up itself, it can be better to C<<
803->throw >> an exception, or use C<< ->safe_cancel >>.
483 804
484 if ($current == $self) { 805The arguments to C<< ->cancel >> are not copied, but instead will
485 terminate @_; 806be referenced directly (e.g. if you pass C<$var> and after the call
486 } else { 807change that variable, then you might change the return values passed to
487 $self->{_status} = [@_]; 808e.g. C<join>, so don't do that).
488 Coro::State::cancel $self; 809
810The resources of the Coro are usually freed (or destructed) before this
811call returns, but this can be delayed for an indefinite amount of time, as
812in some cases the manager thread has to run first to actually destruct the
813Coro object.
814
815=item $coro->safe_cancel ($arg...)
816
817Works mostly like C<< ->cancel >>, but is inherently "safer", and
818consequently, can fail with an exception in cases the thread is not in a
819cancellable state.
820
821This method works a bit like throwing an exception that cannot be caught
822- specifically, it will clean up the thread from within itself, so
823all cleanup handlers (e.g. C<guard> blocks) are run with full thread
824context and can block if they wish. The downside is that there is no
825guarantee that the thread can be cancelled when you call this method, and
826therefore, it might fail. It is also considerably slower than C<cancel> or
827C<terminate>.
828
829A thread is in a safe-cancellable state if it either hasn't been run yet,
830or it has no C context attached and is inside an SLF function.
831
832The latter two basically mean that the thread isn't currently inside a
833perl callback called from some C function (usually via some XS modules)
834and isn't currently executing inside some C function itself (via Coro's XS
835API).
836
837This call returns true when it could cancel the thread, or croaks with an
838error otherwise (i.e. it either returns true or doesn't return at all).
839
840Why the weird interface? Well, there are two common models on how and
841when to cancel things. In the first, you have the expectation that your
842coro thread can be cancelled when you want to cancel it - if the thread
843isn't cancellable, this would be a bug somewhere, so C<< ->safe_cancel >>
844croaks to notify of the bug.
845
846In the second model you sometimes want to ask nicely to cancel a thread,
847but if it's not a good time, well, then don't cancel. This can be done
848relatively easy like this:
849
850 if (! eval { $coro->safe_cancel }) {
851 warn "unable to cancel thread: $@";
489 } 852 }
490} 853
854However, what you never should do is first try to cancel "safely" and
855if that fails, cancel the "hard" way with C<< ->cancel >>. That makes
856no sense: either you rely on being able to execute cleanup code in your
857thread context, or you don't. If you do, then C<< ->safe_cancel >> is the
858only way, and if you don't, then C<< ->cancel >> is always faster and more
859direct.
491 860
492=item $coro->schedule_to 861=item $coro->schedule_to
493 862
494Puts the current coro to sleep (like C<Coro::schedule>), but instead 863Puts the current coro to sleep (like C<Coro::schedule>), but instead
495of continuing with the next coro from the ready queue, always switch to 864of continuing with the next coro from the ready queue, always switch to
514inside the coro at the next convenient point in time. Otherwise 883inside the coro at the next convenient point in time. Otherwise
515clears the exception object. 884clears the exception object.
516 885
517Coro will check for the exception each time a schedule-like-function 886Coro will check for the exception each time a schedule-like-function
518returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down 887returns, i.e. after each C<schedule>, C<cede>, C<< Coro::Semaphore->down
519>>, C<< Coro::Handle->readable >> and so on. Most of these functions 888>>, C<< Coro::Handle->readable >> and so on. Most of those functions (all
520detect this case and return early in case an exception is pending. 889that are part of Coro itself) detect this case and return early in case an
890exception is pending.
521 891
522The exception object will be thrown "as is" with the specified scalar in 892The exception object will be thrown "as is" with the specified scalar in
523C<$@>, i.e. if it is a string, no line number or newline will be appended 893C<$@>, i.e. if it is a string, no line number or newline will be appended
524(unlike with C<die>). 894(unlike with C<die>).
525 895
526This can be used as a softer means than C<cancel> to ask a coro to 896This can be used as a softer means than either C<cancel> or C<safe_cancel
527end itself, although there is no guarantee that the exception will lead to 897>to ask a coro to end itself, although there is no guarantee that the
528termination, and if the exception isn't caught it might well end the whole 898exception will lead to termination, and if the exception isn't caught it
529program. 899might well end the whole program.
530 900
531You might also think of C<throw> as being the moral equivalent of 901You might also think of C<throw> as being the moral equivalent of
532C<kill>ing a coro with a signal (in this case, a scalar). 902C<kill>ing a coro with a signal (in this case, a scalar).
533 903
534=item $coro->join 904=item $coro->join
535 905
536Wait until the coro terminates and return any values given to the 906Wait until the coro terminates and return any values given to the
537C<terminate> or C<cancel> functions. C<join> can be called concurrently 907C<terminate> or C<cancel> functions. C<join> can be called concurrently
538from multiple coro, and all will be resumed and given the status 908from multiple threads, and all will be resumed and given the status
539return once the C<$coro> terminates. 909return once the C<$coro> terminates.
540 910
541=cut
542
543sub join {
544 my $self = shift;
545
546 unless ($self->{_status}) {
547 my $current = $current;
548
549 push @{$self->{_on_destroy}}, sub {
550 $current->ready;
551 undef $current;
552 };
553
554 &schedule while $current;
555 }
556
557 wantarray ? @{$self->{_status}} : $self->{_status}[0];
558}
559
560=item $coro->on_destroy (\&cb) 911=item $coro->on_destroy (\&cb)
561 912
562Registers a callback that is called when this coro gets destroyed, 913Registers a callback that is called when this coro thread gets destroyed,
563but before it is joined. The callback gets passed the terminate arguments, 914that is, after it's resources have been freed but before it is joined. The
915callback gets passed the terminate/cancel arguments, if any, and I<must
564if any, and I<must not> die, under any circumstances. 916not> die, under any circumstances.
565 917
566=cut 918There can be any number of C<on_destroy> callbacks per coro, and there is
567 919currently no way to remove a callback once added.
568sub on_destroy {
569 my ($self, $cb) = @_;
570
571 push @{ $self->{_on_destroy} }, $cb;
572}
573 920
574=item $oldprio = $coro->prio ($newprio) 921=item $oldprio = $coro->prio ($newprio)
575 922
576Sets (or gets, if the argument is missing) the priority of the 923Sets (or gets, if the argument is missing) the priority of the
577coro. Higher priority coro get run before lower priority 924coro thread. Higher priority coro get run before lower priority
578coro. Priorities are small signed integers (currently -4 .. +3), 925coros. Priorities are small signed integers (currently -4 .. +3),
579that you can refer to using PRIO_xxx constants (use the import tag :prio 926that you can refer to using PRIO_xxx constants (use the import tag :prio
580to get then): 927to get then):
581 928
582 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN 929 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
583 3 > 1 > 0 > -1 > -3 > -4 930 3 > 1 > 0 > -1 > -3 > -4
584 931
585 # set priority to HIGH 932 # set priority to HIGH
586 current->prio (PRIO_HIGH); 933 current->prio (PRIO_HIGH);
587 934
588The idle coro ($Coro::idle) always has a lower priority than any 935The idle coro thread ($Coro::idle) always has a lower priority than any
589existing coro. 936existing coro.
590 937
591Changing the priority of the current coro will take effect immediately, 938Changing the priority of the current coro will take effect immediately,
592but changing the priority of coro in the ready queue (but not 939but changing the priority of a coro in the ready queue (but not running)
593running) will only take effect after the next schedule (of that 940will only take effect after the next schedule (of that coro). This is a
594coro). This is a bug that will be fixed in some future version. 941bug that will be fixed in some future version.
595 942
596=item $newprio = $coro->nice ($change) 943=item $newprio = $coro->nice ($change)
597 944
598Similar to C<prio>, but subtract the given value from the priority (i.e. 945Similar to C<prio>, but subtract the given value from the priority (i.e.
599higher values mean lower priority, just as in unix). 946higher values mean lower priority, just as in UNIX's nice command).
600 947
601=item $olddesc = $coro->desc ($newdesc) 948=item $olddesc = $coro->desc ($newdesc)
602 949
603Sets (or gets in case the argument is missing) the description for this 950Sets (or gets in case the argument is missing) the description for this
604coro. This is just a free-form string you can associate with a 951coro thread. This is just a free-form string you can associate with a
605coro. 952coro.
606 953
607This method simply sets the C<< $coro->{desc} >> member to the given 954This method simply sets the C<< $coro->{desc} >> member to the given
608string. You can modify this member directly if you wish. 955string. You can modify this member directly if you wish, and in fact, this
956is often preferred to indicate major processing states that can then be
957seen for example in a L<Coro::Debug> session:
958
959 sub my_long_function {
960 local $Coro::current->{desc} = "now in my_long_function";
961 ...
962 $Coro::current->{desc} = "my_long_function: phase 1";
963 ...
964 $Coro::current->{desc} = "my_long_function: phase 2";
965 ...
966 }
609 967
610=cut 968=cut
611 969
612sub desc { 970sub desc {
613 my $old = $_[0]{desc}; 971 my $old = $_[0]{desc};
650returning a new coderef. Unblocking means that calling the new coderef 1008returning a new coderef. Unblocking means that calling the new coderef
651will return immediately without blocking, returning nothing, while the 1009will return immediately without blocking, returning nothing, while the
652original code ref will be called (with parameters) from within another 1010original code ref will be called (with parameters) from within another
653coro. 1011coro.
654 1012
655The reason this function exists is that many event libraries (such as the 1013The reason this function exists is that many event libraries (such as
656venerable L<Event|Event> module) are not thread-safe (a weaker form 1014the venerable L<Event|Event> module) are not thread-safe (a weaker form
657of reentrancy). This means you must not block within event callbacks, 1015of reentrancy). This means you must not block within event callbacks,
658otherwise you might suffer from crashes or worse. The only event library 1016otherwise you might suffer from crashes or worse. The only event library
659currently known that is safe to use without C<unblock_sub> is L<EV>. 1017currently known that is safe to use without C<unblock_sub> is L<EV> (but
1018you might still run into deadlocks if all event loops are blocked).
1019
1020Coro will try to catch you when you block in the event loop
1021("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and
1022only works when you do not run your own event loop.
660 1023
661This function allows your callbacks to block by executing them in another 1024This function allows your callbacks to block by executing them in another
662coro where it is safe to block. One example where blocking is handy 1025coro where it is safe to block. One example where blocking is handy
663is when you use the L<Coro::AIO|Coro::AIO> functions to save results to 1026is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
664disk, for example. 1027disk, for example.
706 unshift @unblock_queue, [$cb, @_]; 1069 unshift @unblock_queue, [$cb, @_];
707 $unblock_scheduler->ready; 1070 $unblock_scheduler->ready;
708 } 1071 }
709} 1072}
710 1073
711=item $cb = Coro::rouse_cb 1074=item $cb = rouse_cb
712 1075
713Create and return a "rouse callback". That's a code reference that, 1076Create and return a "rouse callback". That's a code reference that,
714when called, will remember a copy of its arguments and notify the owner 1077when called, will remember a copy of its arguments and notify the owner
715coro of the callback. 1078coro of the callback.
716 1079
717See the next function. 1080See the next function.
718 1081
719=item @args = Coro::rouse_wait [$cb] 1082=item @args = rouse_wait [$cb]
720 1083
721Wait for the specified rouse callback (or the last one that was created in 1084Wait for the specified rouse callback (or the last one that was created in
722this coro). 1085this coro).
723 1086
724As soon as the callback is invoked (or when the callback was invoked 1087As soon as the callback is invoked (or when the callback was invoked
725before C<rouse_wait>), it will return the arguments originally passed to 1088before C<rouse_wait>), it will return the arguments originally passed to
726the rouse callback. 1089the rouse callback. In scalar context, that means you get the I<last>
1090argument, just as if C<rouse_wait> had a C<return ($a1, $a2, $a3...)>
1091statement at the end.
727 1092
728See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example. 1093See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
729 1094
730=back 1095=back
731 1096
732=cut 1097=cut
1098
1099for my $module (qw(Channel RWLock Semaphore SemaphoreSet Signal Specific)) {
1100 my $old = defined &{"Coro::$module\::new"} && \&{"Coro::$module\::new"};
1101
1102 *{"Coro::$module\::new"} = sub {
1103 require "Coro/$module.pm";
1104
1105 # some modules have their new predefined in State.xs, some don't
1106 *{"Coro::$module\::new"} = $old
1107 if $old;
1108
1109 goto &{"Coro::$module\::new"};
1110 };
1111}
733 1112
7341; 11131;
735 1114
736=head1 HOW TO WAIT FOR A CALLBACK 1115=head1 HOW TO WAIT FOR A CALLBACK
737 1116
751But from within a coro, you often just want to write this: 1130But from within a coro, you often just want to write this:
752 1131
753 my $status = wait_for_child $pid; 1132 my $status = wait_for_child $pid;
754 1133
755Coro offers two functions specifically designed to make this easy, 1134Coro offers two functions specifically designed to make this easy,
756C<Coro::rouse_cb> and C<Coro::rouse_wait>. 1135C<rouse_cb> and C<rouse_wait>.
757 1136
758The first function, C<rouse_cb>, generates and returns a callback that, 1137The first function, C<rouse_cb>, generates and returns a callback that,
759when invoked, will save its arguments and notify the coro that 1138when invoked, will save its arguments and notify the coro that
760created the callback. 1139created the callback.
761 1140
767function mentioned above: 1146function mentioned above:
768 1147
769 sub wait_for_child($) { 1148 sub wait_for_child($) {
770 my ($pid) = @_; 1149 my ($pid) = @_;
771 1150
772 my $watcher = AnyEvent->child (pid => $pid, cb => Coro::rouse_cb); 1151 my $watcher = AnyEvent->child (pid => $pid, cb => rouse_cb);
773 1152
774 my ($rpid, $rstatus) = Coro::rouse_wait; 1153 my ($rpid, $rstatus) = rouse_wait;
775 $rstatus 1154 $rstatus
776 } 1155 }
777 1156
778In the case where C<rouse_cb> and C<rouse_wait> are not flexible enough, 1157In the case where C<rouse_cb> and C<rouse_wait> are not flexible enough,
779you can roll your own, using C<schedule>: 1158you can roll your own, using C<schedule> and C<ready>:
780 1159
781 sub wait_for_child($) { 1160 sub wait_for_child($) {
782 my ($pid) = @_; 1161 my ($pid) = @_;
783 1162
784 # store the current coro in $current, 1163 # store the current coro in $current,
787 my ($done, $rstatus); 1166 my ($done, $rstatus);
788 1167
789 # pass a closure to ->child 1168 # pass a closure to ->child
790 my $watcher = AnyEvent->child (pid => $pid, cb => sub { 1169 my $watcher = AnyEvent->child (pid => $pid, cb => sub {
791 $rstatus = $_[1]; # remember rstatus 1170 $rstatus = $_[1]; # remember rstatus
792 $done = 1; # mark $rstatus as valud 1171 $done = 1; # mark $rstatus as valid
1172 $current->ready; # wake up the waiting thread
793 }); 1173 });
794 1174
795 # wait until the closure has been called 1175 # wait until the closure has been called
796 schedule while !$done; 1176 schedule while !$done;
797 1177
817future to allow per-thread schedulers, but Coro::State does not yet allow 1197future to allow per-thread schedulers, but Coro::State does not yet allow
818this). I recommend disabling thread support and using processes, as having 1198this). I recommend disabling thread support and using processes, as having
819the windows process emulation enabled under unix roughly halves perl 1199the windows process emulation enabled under unix roughly halves perl
820performance, even when not used. 1200performance, even when not used.
821 1201
1202Attempts to use threads created in another emulated process will crash
1203("cleanly", with a null pointer exception).
1204
822=item coro switching is not signal safe 1205=item coro switching is not signal safe
823 1206
824You must not switch to another coro from within a signal handler 1207You must not switch to another coro from within a signal handler (only
825(only relevant with %SIG - most event libraries provide safe signals). 1208relevant with %SIG - most event libraries provide safe signals), I<unless>
1209you are sure you are not interrupting a Coro function.
826 1210
827That means you I<MUST NOT> call any function that might "block" the 1211That means you I<MUST NOT> call any function that might "block" the
828current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or 1212current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
829anything that calls those. Everything else, including calling C<ready>, 1213anything that calls those. Everything else, including calling C<ready>,
830works. 1214works.
831 1215
832=back 1216=back
833 1217
834 1218
1219=head1 WINDOWS PROCESS EMULATION
1220
1221A great many people seem to be confused about ithreads (for example, Chip
1222Salzenberg called me unintelligent, incapable, stupid and gullible,
1223while in the same mail making rather confused statements about perl
1224ithreads (for example, that memory or files would be shared), showing his
1225lack of understanding of this area - if it is hard to understand for Chip,
1226it is probably not obvious to everybody).
1227
1228What follows is an ultra-condensed version of my talk about threads in
1229scripting languages given on the perl workshop 2009:
1230
1231The so-called "ithreads" were originally implemented for two reasons:
1232first, to (badly) emulate unix processes on native win32 perls, and
1233secondly, to replace the older, real thread model ("5.005-threads").
1234
1235It does that by using threads instead of OS processes. The difference
1236between processes and threads is that threads share memory (and other
1237state, such as files) between threads within a single process, while
1238processes do not share anything (at least not semantically). That
1239means that modifications done by one thread are seen by others, while
1240modifications by one process are not seen by other processes.
1241
1242The "ithreads" work exactly like that: when creating a new ithreads
1243process, all state is copied (memory is copied physically, files and code
1244is copied logically). Afterwards, it isolates all modifications. On UNIX,
1245the same behaviour can be achieved by using operating system processes,
1246except that UNIX typically uses hardware built into the system to do this
1247efficiently, while the windows process emulation emulates this hardware in
1248software (rather efficiently, but of course it is still much slower than
1249dedicated hardware).
1250
1251As mentioned before, loading code, modifying code, modifying data
1252structures and so on is only visible in the ithreads process doing the
1253modification, not in other ithread processes within the same OS process.
1254
1255This is why "ithreads" do not implement threads for perl at all, only
1256processes. What makes it so bad is that on non-windows platforms, you can
1257actually take advantage of custom hardware for this purpose (as evidenced
1258by the forks module, which gives you the (i-) threads API, just much
1259faster).
1260
1261Sharing data is in the i-threads model is done by transfering data
1262structures between threads using copying semantics, which is very slow -
1263shared data simply does not exist. Benchmarks using i-threads which are
1264communication-intensive show extremely bad behaviour with i-threads (in
1265fact, so bad that Coro, which cannot take direct advantage of multiple
1266CPUs, is often orders of magnitude faster because it shares data using
1267real threads, refer to my talk for details).
1268
1269As summary, i-threads *use* threads to implement processes, while
1270the compatible forks module *uses* processes to emulate, uhm,
1271processes. I-threads slow down every perl program when enabled, and
1272outside of windows, serve no (or little) practical purpose, but
1273disadvantages every single-threaded Perl program.
1274
1275This is the reason that I try to avoid the name "ithreads", as it is
1276misleading as it implies that it implements some kind of thread model for
1277perl, and prefer the name "windows process emulation", which describes the
1278actual use and behaviour of it much better.
1279
835=head1 SEE ALSO 1280=head1 SEE ALSO
836 1281
837Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>. 1282Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
838 1283
839Debugging: L<Coro::Debug>. 1284Debugging: L<Coro::Debug>.

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines