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

Comparing Coro/Coro.pm (file contents):
Revision 1.256 by root, Wed Jun 17 21:38:23 2009 UTC vs.
Revision 1.292 by root, Sat Apr 30 05:17:42 2011 UTC

40points in your program, so locking and parallel access are rarely an 40points in your program, so locking and parallel access are rarely an
41issue, making thread programming much safer and easier than using other 41issue, making thread programming much safer and easier than using other
42thread models. 42thread models.
43 43
44Unlike the so-called "Perl threads" (which are not actually real threads 44Unlike the so-called "Perl threads" (which are not actually real threads
45but only the windows process emulation ported to unix, and as such act 45but only the windows process emulation (see section of same name for
46as processes), Coro provides a full shared address space, which makes 46more details) ported to UNIX, and as such act as processes), Coro
47communication between threads very easy. And Coro's threads are fast, 47provides a full shared address space, which makes communication between
48too: disabling the Windows process emulation code in your perl and using 48threads 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 49process emulation code in your perl and using Coro can easily result in
50programs. A parallel matrix multiplication benchmark runs over 300 times 50a two to four times speed increase for your programs. A parallel matrix
51multiplication benchmark (very communication-intensive) runs over 300
51faster on a single core than perl's pseudo-threads on a quad core using 52times faster on a single core than perls pseudo-threads on a quad core
52all four cores. 53using all four cores.
53 54
54Coro achieves that by supporting multiple running interpreters that share 55Coro achieves that by supporting multiple running interpreters that share
55data, which is especially useful to code pseudo-parallel processes and 56data, which is especially useful to code pseudo-parallel processes and
56for event-based programming, such as multiple HTTP-GET requests running 57for event-based programming, such as multiple HTTP-GET requests running
57concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro 58concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro
63variables (see L<Coro::State> for more configuration and background info). 64variables (see L<Coro::State> for more configuration and background info).
64 65
65See also the C<SEE ALSO> section at the end of this document - the Coro 66See also the C<SEE ALSO> section at the end of this document - the Coro
66module family is quite large. 67module family is quite large.
67 68
69=head1 CORO THREAD LIFE CYCLE
70
71During the long and exciting (or not) life of a coro thread, it goes
72through a number of states:
73
74=over 4
75
76=item 1. Creation
77
78The first thing in the life of a coro thread is it's creation -
79obviously. The typical way to create a thread is to call the C<async
80BLOCK> function:
81
82 async {
83 # thread code goes here
84 };
85
86You can also pass arguments, which are put in C<@_>:
87
88 async {
89 print $_[1]; # prints 2
90 } 1, 2, 3;
91
92This creates a new coro thread and puts it into the ready queue, meaning
93it will run as soon as the CPU is free for it.
94
95C<async> will return a coro object - you can store this for future
96reference or ignore it, the thread itself will keep a reference to it's
97thread object - threads are alive on their own.
98
99Another way to create a thread is to call the C<new> constructor with a
100code-reference:
101
102 new Coro sub {
103 # thread code goes here
104 }, @optional_arguments;
105
106This is quite similar to calling C<async>, but the important difference is
107that the new thread is not put into the ready queue, so the thread will
108not run until somebody puts it there. C<async> is, therefore, identical to
109this sequence:
110
111 my $coro = new Coro sub {
112 # thread code goes here
113 };
114 $coro->ready;
115 return $coro;
116
117=item 2. Startup
118
119When a new coro thread is created, only a copy of the code reference
120and the arguments are stored, no extra memory for stacks and so on is
121allocated, keeping the coro thread in a low-memory state.
122
123Only when it actually starts executing will all the resources be finally
124allocated.
125
126The optional arguments specified at coro creation are available in C<@_>,
127similar to function calls.
128
129=item 3. Running / Blocking
130
131A lot can happen after the coro thread has started running. Quite usually,
132it will not run to the end in one go (because you could use a function
133instead), but it will give up the CPU regularly because it waits for
134external events.
135
136As long as a coro thread runs, it's coro object is available in the global
137variable C<$Coro::current>.
138
139The low-level way to give up the CPU is to call the scheduler, which
140selects a new coro thread to run:
141
142 Coro::schedule;
143
144Since running threads are not in the ready queue, calling the scheduler
145without doing anything else will block the coro thread forever - you need
146to arrange either for the coro to put woken up (readied) by some other
147event or some other thread, or you can put it into the ready queue before
148scheduling:
149
150 # this is exactly what Coro::cede does
151 $Coro::current->ready;
152 Coro::schedule;
153
154All the higher-level synchronisation methods (Coro::Semaphore,
155Coro::rouse_*...) are actually implemented via C<< ->ready >> and C<<
156Coro::schedule >>.
157
158While the coro thread is running it also might get assigned a C-level
159thread, or the C-level thread might be unassigned from it, as the Coro
160runtime wishes. A C-level thread needs to be assigned when your perl
161thread calls into some C-level function and that function in turn calls
162perl and perl then wants to switch coroutines. This happens most often
163when you run an event loop and block in the callback, or when perl
164itself calls some function such as C<AUTOLOAD> or methods via the C<tie>
165mechanism.
166
167=item 4. Termination
168
169Many threads actually terminate after some time. There are a number of
170ways to terminate a coro thread, the simplest is returning from the
171top-level code reference:
172
173 async {
174 # after returning from here, the coro thread is terminated
175 };
176
177 async {
178 return if 0.5 < rand; # terminate a little earlier, maybe
179 print "got a chance to print this\n";
180 # or here
181 };
182
183Any values returned from the coroutine can be recovered using C<< ->join
184>>:
185
186 my $coro = async {
187 "hello, world\n" # return a string
188 };
189
190 my $hello_world = $coro->join;
191
192 print $hello_world;
193
194Another way to terminate is to call C<< Coro::terminate >>, which at any
195subroutine call nesting level:
196
197 async {
198 Coro::terminate "return value 1", "return value 2";
199 };
200
201And yet another way is to C<< ->cancel >> the coro thread from another
202thread:
203
204 my $coro = async {
205 exit 1;
206 };
207
208 $coro->cancel; # an also accept values for ->join to retrieve
209
210Cancellation I<can> be dangerous - it's a bit like calling C<exit> without
211actually exiting, and might leave C libraries and XS modules in a weird
212state. Unlike other thread implementations, however, Coro is exceptionally
213safe with regards to cancellation, as perl will always be in a consistent
214state.
215
216So, cancelling a thread that runs in an XS event loop might not be the
217best idea, but any other combination that deals with perl only (cancelling
218when a thread is in a C<tie> method or an C<AUTOLOAD> for example) is
219safe.
220
221=item 5. Cleanup
222
223Threads will allocate various resources. Most but not all will be returned
224when a thread terminates, during clean-up.
225
226Cleanup is quite similar to throwing an uncaught exception: perl will
227work it's way up through all subroutine calls and blocks. On it's way, it
228will release all C<my> variables, undo all C<local>'s and free any other
229resources truly local to the thread.
230
231So, a common way to free resources is to keep them referenced only by my
232variables:
233
234 async {
235 my $big_cache = new Cache ...;
236 };
237
238If there are no other references, then the C<$big_cache> object will be
239freed when the thread terminates, regardless of how it does so.
240
241What it does C<NOT> do is unlock any Coro::Semaphores or similar
242resources, but that's where the C<guard> methods come in handy:
243
244 my $sem = new Coro::Semaphore;
245
246 async {
247 my $lock_guard = $sem->guard;
248 # if we reutrn, or die or get cancelled, here,
249 # then the semaphore will be "up"ed.
250 };
251
252The C<Guard::guard> function comes in handy for any custom cleanup you
253might want to do:
254
255 async {
256 my $window = new Gtk2::Window "toplevel";
257 # The window will not be cleaned up automatically, even when $window
258 # gets freed, so use a guard to ensure it's destruction
259 # in case of an error:
260 my $window_guard = Guard::guard { $window->destroy };
261
262 # we are safe here
263 };
264
265Last not least, C<local> can often be handy, too, e.g. when temporarily
266replacing the coro thread description:
267
268 sub myfunction {
269 local $Coro::current->{desc} = "inside myfunction(@_)";
270
271 # if we return or die here, the description will be restored
272 }
273
274=item 6. Viva La Zombie Muerte
275
276Even after a thread has terminated and cleaned up it's resources, the coro
277object still is there and stores the return values of the thread. Only in
278this state will the coro object be "reference counted" in the normal perl
279sense: the thread code keeps a reference to it when it is active, but not
280after it has terminated.
281
282The means the coro object gets freed automatically when the thread has
283terminated and cleaned up and there arenot other references.
284
285If there are, the coro object will stay around, and you can call C<<
286->join >> as many times as you wish to retrieve the result values:
287
288 async {
289 print "hi\n";
290 1
291 };
292
293 # run the async above, and free everything before returning
294 # from Coro::cede:
295 Coro::cede;
296
297 {
298 my $coro = async {
299 print "hi\n";
300 1
301 };
302
303 # run the async above, and clean up, but do not free the coro
304 # object:
305 Coro::cede;
306
307 # optionally retrieve the result values
308 my @results = $coro->join;
309
310 # now $coro goes out of scope, and presumably gets freed
311 };
312
313=back
314
68=cut 315=cut
69 316
70package Coro; 317package Coro;
71 318
72use strict qw(vars subs); 319use common::sense;
73no warnings "uninitialized"; 320
321use Carp ();
74 322
75use Guard (); 323use Guard ();
76 324
77use Coro::State; 325use Coro::State;
78 326
80 328
81our $idle; # idle handler 329our $idle; # idle handler
82our $main; # main coro 330our $main; # main coro
83our $current; # current coro 331our $current; # current coro
84 332
85our $VERSION = 5.132; 333our $VERSION = 5.372;
86 334
87our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); 335our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait);
88our %EXPORT_TAGS = ( 336our %EXPORT_TAGS = (
89 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], 337 prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)],
90); 338);
91our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); 339our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
92 340
123 371
124This variable is mainly useful to integrate Coro into event loops. It is 372This 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 373usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is
126pretty low-level functionality. 374pretty low-level functionality.
127 375
128This variable stores either a Coro object or a callback. 376This variable stores a Coro object that is put into the ready queue when
377there are no other ready threads (without invoking any ready hooks).
129 378
130If it is a callback, the it is called whenever the scheduler finds no 379The default implementation dies with "FATAL: deadlock detected.", followed
131ready coros to run. The default implementation prints "FATAL: 380by 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 381
139This hook is overwritten by modules such as C<Coro::EV> and 382This 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 383C<Coro::AnyEvent> to wait on an external event that hopefully wakes up a
141coro so the scheduler can run it. 384coro so the scheduler can run it.
142 385
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 386See L<Coro::EV> or L<Coro::AnyEvent> for examples of using this technique.
150technique.
151 387
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
155=cut 388=cut
156 389
157$idle = sub { 390# ||= because other modules could have provided their own by now
158 require Carp; 391$idle ||= new Coro sub {
159 Carp::croak ("FATAL: deadlock detected"); 392 require Coro::Debug;
393 die "FATAL: deadlock detected.\n"
394 . Coro::Debug::ps_listing ();
160}; 395};
161 396
162# this coro is necessary because a coro 397# this coro is necessary because a coro
163# cannot destroy itself. 398# cannot destroy itself.
164our @destroy; 399our @destroy;
165our $manager; 400our $manager;
166 401
167$manager = new Coro sub { 402$manager = new Coro sub {
168 while () { 403 while () {
169 Coro::State::cancel shift @destroy 404 _destroy shift @destroy
170 while @destroy; 405 while @destroy;
171 406
172 &schedule; 407 &schedule;
173 } 408 }
174}; 409};
206Example: Create a new coro that just prints its arguments. 441Example: Create a new coro that just prints its arguments.
207 442
208 async { 443 async {
209 print "@_\n"; 444 print "@_\n";
210 } 1,2,3,4; 445 } 1,2,3,4;
211
212=cut
213
214sub async(&@) {
215 my $coro = new Coro @_;
216 $coro->ready;
217 $coro
218}
219 446
220=item async_pool { ... } [@args...] 447=item async_pool { ... } [@args...]
221 448
222Similar to C<async>, but uses a coro pool, so you should not call 449Similar 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 450terminate or join on it (although you are allowed to), and you get a
280=item schedule 507=item schedule
281 508
282Calls the scheduler. The scheduler will find the next coro that is 509Calls 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 510to 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 511to 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 512in its ready queue. If there is no coro ready, it will call the
286C<$Coro::idle> hook. 513C<$Coro::idle> hook.
287 514
288Please note that the current coro will I<not> be put into the ready 515Please 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 516queue, so calling this function usually means you will never be called
290again unless something else (e.g. an event handler) calls C<< ->ready >>, 517again unless something else (e.g. an event handler) calls C<< ->ready >>,
316coro, regardless of priority. This is useful sometimes to ensure 543coro, regardless of priority. This is useful sometimes to ensure
317progress is made. 544progress is made.
318 545
319=item terminate [arg...] 546=item terminate [arg...]
320 547
321Terminates the current coro with the given status values (see L<cancel>). 548Terminates the current coro with the given status values (see
549L<cancel>). The values will not be copied, but referenced directly.
322 550
323=item Coro::on_enter BLOCK, Coro::on_leave BLOCK 551=item Coro::on_enter BLOCK, Coro::on_leave BLOCK
324 552
325These function install enter and leave winders in the current scope. The 553These function install enter and leave winders in the current scope. The
326enter block will be executed when on_enter is called and whenever the 554enter block will be executed when on_enter is called and whenever the
500Returns true iff this Coro object has been suspended. Suspended Coros will 728Returns true iff this Coro object has been suspended. Suspended Coros will
501not ever be scheduled. 729not ever be scheduled.
502 730
503=item $coro->cancel (arg...) 731=item $coro->cancel (arg...)
504 732
505Terminates the given Coro and makes it return the given arguments as 733Terminates the given Coro object and makes it return the given arguments as
506status (default: the empty list). Never returns if the Coro is the 734status (default: an empty list). Never returns if the Coro is the
507current Coro. 735current Coro.
508 736
509=cut 737The arguments are not copied, but instead will be referenced directly
738(e.g. if you pass C<$var> and after the call change that variable, then
739you might change the return values passed to e.g. C<join>, so don't do
740that).
510 741
511sub cancel { 742The resources of the Coro are usually freed (or destructed) before this
512 my $self = shift; 743call returns, but this can be delayed for an indefinite amount of time, as
513 744in some cases the manager thread has to run first to actually destruct the
514 if ($current == $self) { 745Coro object.
515 terminate @_;
516 } else {
517 $self->{_status} = [@_];
518 Coro::State::cancel $self;
519 }
520}
521 746
522=item $coro->schedule_to 747=item $coro->schedule_to
523 748
524Puts the current coro to sleep (like C<Coro::schedule>), but instead 749Puts the current coro to sleep (like C<Coro::schedule>), but instead
525of continuing with the next coro from the ready queue, always switch to 750of continuing with the next coro from the ready queue, always switch to
563 788
564=item $coro->join 789=item $coro->join
565 790
566Wait until the coro terminates and return any values given to the 791Wait until the coro terminates and return any values given to the
567C<terminate> or C<cancel> functions. C<join> can be called concurrently 792C<terminate> or C<cancel> functions. C<join> can be called concurrently
568from multiple coro, and all will be resumed and given the status 793from multiple threads, and all will be resumed and given the status
569return once the C<$coro> terminates. 794return once the C<$coro> terminates.
570 795
571=cut 796=cut
572 797
573sub join { 798sub join {
587 wantarray ? @{$self->{_status}} : $self->{_status}[0]; 812 wantarray ? @{$self->{_status}} : $self->{_status}[0];
588} 813}
589 814
590=item $coro->on_destroy (\&cb) 815=item $coro->on_destroy (\&cb)
591 816
592Registers a callback that is called when this coro gets destroyed, 817Registers a callback that is called when this coro thread gets destroyed,
593but before it is joined. The callback gets passed the terminate arguments, 818but before it is joined. The callback gets passed the terminate arguments,
594if any, and I<must not> die, under any circumstances. 819if any, and I<must not> die, under any circumstances.
595 820
821There can be any number of C<on_destroy> callbacks per coro.
822
596=cut 823=cut
597 824
598sub on_destroy { 825sub on_destroy {
599 my ($self, $cb) = @_; 826 my ($self, $cb) = @_;
600 827
602} 829}
603 830
604=item $oldprio = $coro->prio ($newprio) 831=item $oldprio = $coro->prio ($newprio)
605 832
606Sets (or gets, if the argument is missing) the priority of the 833Sets (or gets, if the argument is missing) the priority of the
607coro. Higher priority coro get run before lower priority 834coro thread. Higher priority coro get run before lower priority
608coro. Priorities are small signed integers (currently -4 .. +3), 835coros. Priorities are small signed integers (currently -4 .. +3),
609that you can refer to using PRIO_xxx constants (use the import tag :prio 836that you can refer to using PRIO_xxx constants (use the import tag :prio
610to get then): 837to get then):
611 838
612 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN 839 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
613 3 > 1 > 0 > -1 > -3 > -4 840 3 > 1 > 0 > -1 > -3 > -4
614 841
615 # set priority to HIGH 842 # set priority to HIGH
616 current->prio (PRIO_HIGH); 843 current->prio (PRIO_HIGH);
617 844
618The idle coro ($Coro::idle) always has a lower priority than any 845The idle coro thread ($Coro::idle) always has a lower priority than any
619existing coro. 846existing coro.
620 847
621Changing the priority of the current coro will take effect immediately, 848Changing the priority of the current coro will take effect immediately,
622but changing the priority of coro in the ready queue (but not 849but changing the priority of a coro in the ready queue (but not running)
623running) will only take effect after the next schedule (of that 850will only take effect after the next schedule (of that coro). This is a
624coro). This is a bug that will be fixed in some future version. 851bug that will be fixed in some future version.
625 852
626=item $newprio = $coro->nice ($change) 853=item $newprio = $coro->nice ($change)
627 854
628Similar to C<prio>, but subtract the given value from the priority (i.e. 855Similar to C<prio>, but subtract the given value from the priority (i.e.
629higher values mean lower priority, just as in unix). 856higher values mean lower priority, just as in UNIX's nice command).
630 857
631=item $olddesc = $coro->desc ($newdesc) 858=item $olddesc = $coro->desc ($newdesc)
632 859
633Sets (or gets in case the argument is missing) the description for this 860Sets (or gets in case the argument is missing) the description for this
634coro. This is just a free-form string you can associate with a 861coro thread. This is just a free-form string you can associate with a
635coro. 862coro.
636 863
637This method simply sets the C<< $coro->{desc} >> member to the given 864This method simply sets the C<< $coro->{desc} >> member to the given
638string. You can modify this member directly if you wish. 865string. You can modify this member directly if you wish, and in fact, this
866is often preferred to indicate major processing states that cna then be
867seen for example in a L<Coro::Debug> session:
868
869 sub my_long_function {
870 local $Coro::current->{desc} = "now in my_long_function";
871 ...
872 $Coro::current->{desc} = "my_long_function: phase 1";
873 ...
874 $Coro::current->{desc} = "my_long_function: phase 2";
875 ...
876 }
639 877
640=cut 878=cut
641 879
642sub desc { 880sub desc {
643 my $old = $_[0]{desc}; 881 my $old = $_[0]{desc};
680returning a new coderef. Unblocking means that calling the new coderef 918returning a new coderef. Unblocking means that calling the new coderef
681will return immediately without blocking, returning nothing, while the 919will return immediately without blocking, returning nothing, while the
682original code ref will be called (with parameters) from within another 920original code ref will be called (with parameters) from within another
683coro. 921coro.
684 922
685The reason this function exists is that many event libraries (such as the 923The reason this function exists is that many event libraries (such as
686venerable L<Event|Event> module) are not thread-safe (a weaker form 924the venerable L<Event|Event> module) are not thread-safe (a weaker form
687of reentrancy). This means you must not block within event callbacks, 925of reentrancy). This means you must not block within event callbacks,
688otherwise you might suffer from crashes or worse. The only event library 926otherwise you might suffer from crashes or worse. The only event library
689currently known that is safe to use without C<unblock_sub> is L<EV>. 927currently known that is safe to use without C<unblock_sub> is L<EV> (but
928you might still run into deadlocks if all event loops are blocked).
929
930Coro will try to catch you when you block in the event loop
931("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and
932only works when you do not run your own event loop.
690 933
691This function allows your callbacks to block by executing them in another 934This function allows your callbacks to block by executing them in another
692coro where it is safe to block. One example where blocking is handy 935coro where it is safe to block. One example where blocking is handy
693is when you use the L<Coro::AIO|Coro::AIO> functions to save results to 936is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
694disk, for example. 937disk, for example.
736 unshift @unblock_queue, [$cb, @_]; 979 unshift @unblock_queue, [$cb, @_];
737 $unblock_scheduler->ready; 980 $unblock_scheduler->ready;
738 } 981 }
739} 982}
740 983
741=item $cb = Coro::rouse_cb 984=item $cb = rouse_cb
742 985
743Create and return a "rouse callback". That's a code reference that, 986Create and return a "rouse callback". That's a code reference that,
744when called, will remember a copy of its arguments and notify the owner 987when called, will remember a copy of its arguments and notify the owner
745coro of the callback. 988coro of the callback.
746 989
747See the next function. 990See the next function.
748 991
749=item @args = Coro::rouse_wait [$cb] 992=item @args = rouse_wait [$cb]
750 993
751Wait for the specified rouse callback (or the last one that was created in 994Wait for the specified rouse callback (or the last one that was created in
752this coro). 995this coro).
753 996
754As soon as the callback is invoked (or when the callback was invoked 997As soon as the callback is invoked (or when the callback was invoked
755before C<rouse_wait>), it will return the arguments originally passed to 998before C<rouse_wait>), it will return the arguments originally passed to
756the rouse callback. 999the rouse callback. In scalar context, that means you get the I<last>
1000argument, just as if C<rouse_wait> had a C<return ($a1, $a2, $a3...)>
1001statement at the end.
757 1002
758See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example. 1003See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
759 1004
760=back 1005=back
761 1006
762=cut 1007=cut
1008
1009for my $module (qw(Channel RWLock Semaphore SemaphoreSet Signal Specific)) {
1010 my $old = defined &{"Coro::$module\::new"} && \&{"Coro::$module\::new"};
1011
1012 *{"Coro::$module\::new"} = sub {
1013 require "Coro/$module.pm";
1014
1015 # some modules have their new predefined in State.xs, some don't
1016 *{"Coro::$module\::new"} = $old
1017 if $old;
1018
1019 goto &{"Coro::$module\::new"};
1020 };
1021}
763 1022
7641; 10231;
765 1024
766=head1 HOW TO WAIT FOR A CALLBACK 1025=head1 HOW TO WAIT FOR A CALLBACK
767 1026
849the windows process emulation enabled under unix roughly halves perl 1108the windows process emulation enabled under unix roughly halves perl
850performance, even when not used. 1109performance, even when not used.
851 1110
852=item coro switching is not signal safe 1111=item coro switching is not signal safe
853 1112
854You must not switch to another coro from within a signal handler 1113You must not switch to another coro from within a signal handler (only
855(only relevant with %SIG - most event libraries provide safe signals). 1114relevant with %SIG - most event libraries provide safe signals), I<unless>
1115you are sure you are not interrupting a Coro function.
856 1116
857That means you I<MUST NOT> call any function that might "block" the 1117That means you I<MUST NOT> call any function that might "block" the
858current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or 1118current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
859anything that calls those. Everything else, including calling C<ready>, 1119anything that calls those. Everything else, including calling C<ready>,
860works. 1120works.
861 1121
862=back 1122=back
863 1123
864 1124
1125=head1 WINDOWS PROCESS EMULATION
1126
1127A great many people seem to be confused about ithreads (for example, Chip
1128Salzenberg called me unintelligent, incapable, stupid and gullible,
1129while in the same mail making rather confused statements about perl
1130ithreads (for example, that memory or files would be shared), showing his
1131lack of understanding of this area - if it is hard to understand for Chip,
1132it is probably not obvious to everybody).
1133
1134What follows is an ultra-condensed version of my talk about threads in
1135scripting languages given on the perl workshop 2009:
1136
1137The so-called "ithreads" were originally implemented for two reasons:
1138first, to (badly) emulate unix processes on native win32 perls, and
1139secondly, to replace the older, real thread model ("5.005-threads").
1140
1141It does that by using threads instead of OS processes. The difference
1142between processes and threads is that threads share memory (and other
1143state, such as files) between threads within a single process, while
1144processes do not share anything (at least not semantically). That
1145means that modifications done by one thread are seen by others, while
1146modifications by one process are not seen by other processes.
1147
1148The "ithreads" work exactly like that: when creating a new ithreads
1149process, all state is copied (memory is copied physically, files and code
1150is copied logically). Afterwards, it isolates all modifications. On UNIX,
1151the same behaviour can be achieved by using operating system processes,
1152except that UNIX typically uses hardware built into the system to do this
1153efficiently, while the windows process emulation emulates this hardware in
1154software (rather efficiently, but of course it is still much slower than
1155dedicated hardware).
1156
1157As mentioned before, loading code, modifying code, modifying data
1158structures and so on is only visible in the ithreads process doing the
1159modification, not in other ithread processes within the same OS process.
1160
1161This is why "ithreads" do not implement threads for perl at all, only
1162processes. What makes it so bad is that on non-windows platforms, you can
1163actually take advantage of custom hardware for this purpose (as evidenced
1164by the forks module, which gives you the (i-) threads API, just much
1165faster).
1166
1167Sharing data is in the i-threads model is done by transfering data
1168structures between threads using copying semantics, which is very slow -
1169shared data simply does not exist. Benchmarks using i-threads which are
1170communication-intensive show extremely bad behaviour with i-threads (in
1171fact, so bad that Coro, which cannot take direct advantage of multiple
1172CPUs, is often orders of magnitude faster because it shares data using
1173real threads, refer to my talk for details).
1174
1175As summary, i-threads *use* threads to implement processes, while
1176the compatible forks module *uses* processes to emulate, uhm,
1177processes. I-threads slow down every perl program when enabled, and
1178outside of windows, serve no (or little) practical purpose, but
1179disadvantages every single-threaded Perl program.
1180
1181This is the reason that I try to avoid the name "ithreads", as it is
1182misleading as it implies that it implements some kind of thread model for
1183perl, and prefer the name "windows process emulation", which describes the
1184actual use and behaviour of it much better.
1185
865=head1 SEE ALSO 1186=head1 SEE ALSO
866 1187
867Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>. 1188Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>.
868 1189
869Debugging: L<Coro::Debug>. 1190Debugging: L<Coro::Debug>.

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines