… | |
… | |
40 | points in your program, so locking and parallel access are rarely an |
40 | points in your program, so locking and parallel access are rarely an |
41 | issue, making thread programming much safer and easier than using other |
41 | issue, making thread programming much safer and easier than using other |
42 | thread models. |
42 | thread models. |
43 | |
43 | |
44 | Unlike the so-called "Perl threads" (which are not actually real threads |
44 | Unlike the so-called "Perl threads" (which are not actually real threads |
45 | but only the windows process emulation ported to unix), Coro provides a |
45 | but only the windows process emulation (see section of same name for more |
|
|
46 | details) ported to unix, and as such act as processes), Coro provides |
46 | full shared address space, which makes communication between threads |
47 | a full shared address space, which makes communication between threads |
47 | very easy. And threads are fast, too: disabling the Windows process |
48 | very easy. And Coro's threads are fast, too: disabling the Windows |
48 | emulation code in your perl and using Coro can easily result in a two to |
49 | process emulation code in your perl and using Coro can easily result in |
49 | four times speed increase for your programs. |
50 | a two to four times speed increase for your programs. A parallel matrix |
|
|
51 | multiplication benchmark runs over 300 times faster on a single core than |
|
|
52 | perl's pseudo-threads on a quad core using all four cores. |
50 | |
53 | |
51 | Coro achieves that by supporting multiple running interpreters that share |
54 | Coro achieves that by supporting multiple running interpreters that share |
52 | data, which is especially useful to code pseudo-parallel processes and |
55 | data, which is especially useful to code pseudo-parallel processes and |
53 | for event-based programming, such as multiple HTTP-GET requests running |
56 | for event-based programming, such as multiple HTTP-GET requests running |
54 | concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro |
57 | concurrently. See L<Coro::AnyEvent> to learn more on how to integrate Coro |
55 | into an event-based environment. |
58 | into an event-based environment. |
56 | |
59 | |
57 | In this module, a thread is defined as "callchain + lexical variables + |
60 | In this module, a thread is defined as "callchain + lexical variables + |
58 | @_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain, |
61 | some package variables + C stack), that is, a thread has its own callchain, |
59 | its own set of lexicals and its own set of perls most important global |
62 | its own set of lexicals and its own set of perls most important global |
60 | variables (see L<Coro::State> for more configuration and background info). |
63 | variables (see L<Coro::State> for more configuration and background info). |
61 | |
64 | |
62 | See also the C<SEE ALSO> section at the end of this document - the Coro |
65 | See also the C<SEE ALSO> section at the end of this document - the Coro |
63 | module family is quite large. |
66 | module family is quite large. |
64 | |
67 | |
65 | =cut |
68 | =cut |
66 | |
69 | |
67 | package Coro; |
70 | package Coro; |
68 | |
71 | |
69 | use strict qw(vars subs); |
72 | use common::sense; |
70 | no warnings "uninitialized"; |
73 | |
|
|
74 | use Carp (); |
71 | |
75 | |
72 | use Guard (); |
76 | use Guard (); |
73 | |
77 | |
74 | use Coro::State; |
78 | use Coro::State; |
75 | |
79 | |
… | |
… | |
77 | |
81 | |
78 | our $idle; # idle handler |
82 | our $idle; # idle handler |
79 | our $main; # main coro |
83 | our $main; # main coro |
80 | our $current; # current coro |
84 | our $current; # current coro |
81 | |
85 | |
82 | our $VERSION = 5.13; |
86 | our $VERSION = 5.21; |
83 | |
87 | |
84 | our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub); |
88 | our @EXPORT = qw(async async_pool cede schedule terminate current unblock_sub rouse_cb rouse_wait); |
85 | our %EXPORT_TAGS = ( |
89 | our %EXPORT_TAGS = ( |
86 | prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], |
90 | prio => [qw(PRIO_MAX PRIO_HIGH PRIO_NORMAL PRIO_LOW PRIO_IDLE PRIO_MIN)], |
87 | ); |
91 | ); |
88 | our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); |
92 | our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); |
89 | |
93 | |
… | |
… | |
120 | |
124 | |
121 | This variable is mainly useful to integrate Coro into event loops. It is |
125 | This variable is mainly useful to integrate Coro into event loops. It is |
122 | usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is |
126 | usually better to rely on L<Coro::AnyEvent> or L<Coro::EV>, as this is |
123 | pretty low-level functionality. |
127 | pretty low-level functionality. |
124 | |
128 | |
125 | This variable stores either a Coro object or a callback. |
129 | This variable stores a Coro object that is put into the ready queue when |
|
|
130 | there are no other ready threads (without invoking any ready hooks). |
126 | |
131 | |
127 | If it is a callback, the it is called whenever the scheduler finds no |
132 | The default implementation dies with "FATAL: deadlock detected.", followed |
128 | ready coros to run. The default implementation prints "FATAL: |
133 | by a thread listing, because the program has no other way to continue. |
129 | deadlock detected" and exits, because the program has no other way to |
|
|
130 | continue. |
|
|
131 | |
|
|
132 | If it is a coro object, then this object will be readied (without |
|
|
133 | invoking any ready hooks, however) when the scheduler finds no other ready |
|
|
134 | coros to run. |
|
|
135 | |
134 | |
136 | This hook is overwritten by modules such as C<Coro::EV> and |
135 | This hook is overwritten by modules such as C<Coro::EV> and |
137 | C<Coro::AnyEvent> to wait on an external event that hopefully wake up a |
136 | C<Coro::AnyEvent> to wait on an external event that hopefully wake up a |
138 | coro so the scheduler can run it. |
137 | coro so the scheduler can run it. |
139 | |
138 | |
140 | Note that the callback I<must not>, under any circumstances, block |
|
|
141 | the current coro. Normally, this is achieved by having an "idle |
|
|
142 | coro" that calls the event loop and then blocks again, and then |
|
|
143 | readying that coro in the idle handler, or by simply placing the idle |
|
|
144 | coro in this variable. |
|
|
145 | |
|
|
146 | See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this |
139 | See L<Coro::EV> or L<Coro::AnyEvent> for examples of using this technique. |
147 | technique. |
|
|
148 | |
140 | |
149 | Please note that if your callback recursively invokes perl (e.g. for event |
|
|
150 | handlers), then it must be prepared to be called recursively itself. |
|
|
151 | |
|
|
152 | =cut |
141 | =cut |
153 | |
142 | |
154 | $idle = sub { |
143 | $idle = new Coro sub { |
155 | require Carp; |
144 | require Coro::Debug; |
156 | Carp::croak ("FATAL: deadlock detected"); |
145 | die "FATAL: deadlock detected.\n" |
|
|
146 | . Coro::Debug::ps_listing (); |
157 | }; |
147 | }; |
158 | |
148 | |
159 | # this coro is necessary because a coro |
149 | # this coro is necessary because a coro |
160 | # cannot destroy itself. |
150 | # cannot destroy itself. |
161 | our @destroy; |
151 | our @destroy; |
… | |
… | |
203 | Example: Create a new coro that just prints its arguments. |
193 | Example: Create a new coro that just prints its arguments. |
204 | |
194 | |
205 | async { |
195 | async { |
206 | print "@_\n"; |
196 | print "@_\n"; |
207 | } 1,2,3,4; |
197 | } 1,2,3,4; |
208 | |
|
|
209 | =cut |
|
|
210 | |
|
|
211 | sub async(&@) { |
|
|
212 | my $coro = new Coro @_; |
|
|
213 | $coro->ready; |
|
|
214 | $coro |
|
|
215 | } |
|
|
216 | |
198 | |
217 | =item async_pool { ... } [@args...] |
199 | =item async_pool { ... } [@args...] |
218 | |
200 | |
219 | Similar to C<async>, but uses a coro pool, so you should not call |
201 | Similar to C<async>, but uses a coro pool, so you should not call |
220 | terminate or join on it (although you are allowed to), and you get a |
202 | terminate or join on it (although you are allowed to), and you get a |
… | |
… | |
277 | =item schedule |
259 | =item schedule |
278 | |
260 | |
279 | Calls the scheduler. The scheduler will find the next coro that is |
261 | Calls the scheduler. The scheduler will find the next coro that is |
280 | to be run from the ready queue and switches to it. The next coro |
262 | to be run from the ready queue and switches to it. The next coro |
281 | to be run is simply the one with the highest priority that is longest |
263 | to be run is simply the one with the highest priority that is longest |
282 | in its ready queue. If there is no coro ready, it will clal the |
264 | in its ready queue. If there is no coro ready, it will call the |
283 | C<$Coro::idle> hook. |
265 | C<$Coro::idle> hook. |
284 | |
266 | |
285 | Please note that the current coro will I<not> be put into the ready |
267 | Please note that the current coro will I<not> be put into the ready |
286 | queue, so calling this function usually means you will never be called |
268 | queue, so calling this function usually means you will never be called |
287 | again unless something else (e.g. an event handler) calls C<< ->ready >>, |
269 | again unless something else (e.g. an event handler) calls C<< ->ready >>, |
… | |
… | |
335 | |
317 | |
336 | These functions implement the same concept as C<dynamic-wind> in scheme |
318 | These functions implement the same concept as C<dynamic-wind> in scheme |
337 | does, and are useful when you want to localise some resource to a specific |
319 | does, and are useful when you want to localise some resource to a specific |
338 | coro. |
320 | coro. |
339 | |
321 | |
340 | They slow down coro switching considerably for coros that use |
322 | They slow down thread switching considerably for coros that use them |
341 | them (But coro switching is still reasonably fast if the handlers are |
323 | (about 40% for a BLOCK with a single assignment, so thread switching is |
342 | fast). |
324 | still reasonably fast if the handlers are fast). |
343 | |
325 | |
344 | These functions are best understood by an example: The following function |
326 | These functions are best understood by an example: The following function |
345 | will change the current timezone to "Antarctica/South_Pole", which |
327 | will change the current timezone to "Antarctica/South_Pole", which |
346 | requires a call to C<tzset>, but by using C<on_enter> and C<on_leave>, |
328 | requires a call to C<tzset>, but by using C<on_enter> and C<on_leave>, |
347 | which remember/change the current timezone and restore the previous |
329 | which remember/change the current timezone and restore the previous |
348 | value, respectively, the timezone is only changes for the coro that |
330 | value, respectively, the timezone is only changed for the coro that |
349 | installed those handlers. |
331 | installed those handlers. |
350 | |
332 | |
351 | use POSIX qw(tzset); |
333 | use POSIX qw(tzset); |
352 | |
334 | |
353 | async { |
335 | async { |
… | |
… | |
370 | }; |
352 | }; |
371 | |
353 | |
372 | This can be used to localise about any resource (locale, uid, current |
354 | This can be used to localise about any resource (locale, uid, current |
373 | working directory etc.) to a block, despite the existance of other |
355 | working directory etc.) to a block, despite the existance of other |
374 | coros. |
356 | coros. |
|
|
357 | |
|
|
358 | Another interesting example implements time-sliced multitasking using |
|
|
359 | interval timers (this could obviously be optimised, but does the job): |
|
|
360 | |
|
|
361 | # "timeslice" the given block |
|
|
362 | sub timeslice(&) { |
|
|
363 | use Time::HiRes (); |
|
|
364 | |
|
|
365 | Coro::on_enter { |
|
|
366 | # on entering the thread, we set an VTALRM handler to cede |
|
|
367 | $SIG{VTALRM} = sub { cede }; |
|
|
368 | # and then start the interval timer |
|
|
369 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01; |
|
|
370 | }; |
|
|
371 | Coro::on_leave { |
|
|
372 | # on leaving the thread, we stop the interval timer again |
|
|
373 | Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0; |
|
|
374 | }; |
|
|
375 | |
|
|
376 | &{+shift}; |
|
|
377 | } |
|
|
378 | |
|
|
379 | # use like this: |
|
|
380 | timeslice { |
|
|
381 | # The following is an endless loop that would normally |
|
|
382 | # monopolise the process. Since it runs in a timesliced |
|
|
383 | # environment, it will regularly cede to other threads. |
|
|
384 | while () { } |
|
|
385 | }; |
|
|
386 | |
375 | |
387 | |
376 | =item killall |
388 | =item killall |
377 | |
389 | |
378 | Kills/terminates/cancels all coros except the currently running one. |
390 | Kills/terminates/cancels all coros except the currently running one. |
379 | |
391 | |
… | |
… | |
423 | the ready queue, do nothing and return false. |
435 | the ready queue, do nothing and return false. |
424 | |
436 | |
425 | This ensures that the scheduler will resume this coro automatically |
437 | This ensures that the scheduler will resume this coro automatically |
426 | once all the coro of higher priority and all coro of the same |
438 | once all the coro of higher priority and all coro of the same |
427 | priority that were put into the ready queue earlier have been resumed. |
439 | priority that were put into the ready queue earlier have been resumed. |
|
|
440 | |
|
|
441 | =item $coro->suspend |
|
|
442 | |
|
|
443 | Suspends the specified coro. A suspended coro works just like any other |
|
|
444 | coro, except that the scheduler will not select a suspended coro for |
|
|
445 | execution. |
|
|
446 | |
|
|
447 | Suspending a coro can be useful when you want to keep the coro from |
|
|
448 | running, but you don't want to destroy it, or when you want to temporarily |
|
|
449 | freeze a coro (e.g. for debugging) to resume it later. |
|
|
450 | |
|
|
451 | A scenario for the former would be to suspend all (other) coros after a |
|
|
452 | fork and keep them alive, so their destructors aren't called, but new |
|
|
453 | coros can be created. |
|
|
454 | |
|
|
455 | =item $coro->resume |
|
|
456 | |
|
|
457 | If the specified coro was suspended, it will be resumed. Note that when |
|
|
458 | the coro was in the ready queue when it was suspended, it might have been |
|
|
459 | unreadied by the scheduler, so an activation might have been lost. |
|
|
460 | |
|
|
461 | To avoid this, it is best to put a suspended coro into the ready queue |
|
|
462 | unconditionally, as every synchronisation mechanism must protect itself |
|
|
463 | against spurious wakeups, and the one in the Coro family certainly do |
|
|
464 | that. |
428 | |
465 | |
429 | =item $is_ready = $coro->is_ready |
466 | =item $is_ready = $coro->is_ready |
430 | |
467 | |
431 | Returns true iff the Coro object is in the ready queue. Unless the Coro |
468 | Returns true iff the Coro object is in the ready queue. Unless the Coro |
432 | object gets destroyed, it will eventually be scheduled by the scheduler. |
469 | object gets destroyed, it will eventually be scheduled by the scheduler. |
… | |
… | |
678 | unshift @unblock_queue, [$cb, @_]; |
715 | unshift @unblock_queue, [$cb, @_]; |
679 | $unblock_scheduler->ready; |
716 | $unblock_scheduler->ready; |
680 | } |
717 | } |
681 | } |
718 | } |
682 | |
719 | |
683 | =item $cb = Coro::rouse_cb |
720 | =item $cb = rouse_cb |
684 | |
721 | |
685 | Create and return a "rouse callback". That's a code reference that, |
722 | Create and return a "rouse callback". That's a code reference that, |
686 | when called, will remember a copy of its arguments and notify the owner |
723 | when called, will remember a copy of its arguments and notify the owner |
687 | coro of the callback. |
724 | coro of the callback. |
688 | |
725 | |
689 | See the next function. |
726 | See the next function. |
690 | |
727 | |
691 | =item @args = Coro::rouse_wait [$cb] |
728 | =item @args = rouse_wait [$cb] |
692 | |
729 | |
693 | Wait for the specified rouse callback (or the last one that was created in |
730 | Wait for the specified rouse callback (or the last one that was created in |
694 | this coro). |
731 | this coro). |
695 | |
732 | |
696 | As soon as the callback is invoked (or when the callback was invoked |
733 | As soon as the callback is invoked (or when the callback was invoked |
697 | before C<rouse_wait>), it will return the arguments originally passed to |
734 | before C<rouse_wait>), it will return the arguments originally passed to |
698 | the rouse callback. |
735 | the rouse callback. In scalar context, that means you get the I<last> |
|
|
736 | argument, just as if C<rouse_wait> had a C<return ($a1, $a2, $a3...)> |
|
|
737 | statement at the end. |
699 | |
738 | |
700 | See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example. |
739 | See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example. |
701 | |
740 | |
702 | =back |
741 | =back |
703 | |
742 | |
… | |
… | |
791 | the windows process emulation enabled under unix roughly halves perl |
830 | the windows process emulation enabled under unix roughly halves perl |
792 | performance, even when not used. |
831 | performance, even when not used. |
793 | |
832 | |
794 | =item coro switching is not signal safe |
833 | =item coro switching is not signal safe |
795 | |
834 | |
796 | You must not switch to another coro from within a signal handler |
835 | You must not switch to another coro from within a signal handler (only |
797 | (only relevant with %SIG - most event libraries provide safe signals). |
836 | relevant with %SIG - most event libraries provide safe signals), I<unless> |
|
|
837 | you are sure you are not interrupting a Coro function. |
798 | |
838 | |
799 | That means you I<MUST NOT> call any function that might "block" the |
839 | That means you I<MUST NOT> call any function that might "block" the |
800 | current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or |
840 | current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or |
801 | anything that calls those. Everything else, including calling C<ready>, |
841 | anything that calls those. Everything else, including calling C<ready>, |
802 | works. |
842 | works. |
803 | |
843 | |
804 | =back |
844 | =back |
805 | |
845 | |
806 | |
846 | |
|
|
847 | =head1 WINDOWS PROCESS EMULATION |
|
|
848 | |
|
|
849 | A great many people seem to be confused about ithreads (for example, Chip |
|
|
850 | Salzenberg called me unintelligent, incapable, stupid and gullible, |
|
|
851 | while in the same mail making rather confused statements about perl |
|
|
852 | ithreads (for example, that memory or files would be shared), showing his |
|
|
853 | lack of understanding of this area - if it is hard to understand for Chip, |
|
|
854 | it is probably not obvious to everybody). |
|
|
855 | |
|
|
856 | What follows is an ultra-condensed version of my talk about threads in |
|
|
857 | scripting languages given onthe perl workshop 2009: |
|
|
858 | |
|
|
859 | The so-called "ithreads" were originally implemented for two reasons: |
|
|
860 | first, to (badly) emulate unix processes on native win32 perls, and |
|
|
861 | secondly, to replace the older, real thread model ("5.005-threads"). |
|
|
862 | |
|
|
863 | It does that by using threads instead of OS processes. The difference |
|
|
864 | between processes and threads is that threads share memory (and other |
|
|
865 | state, such as files) between threads within a single process, while |
|
|
866 | processes do not share anything (at least not semantically). That |
|
|
867 | means that modifications done by one thread are seen by others, while |
|
|
868 | modifications by one process are not seen by other processes. |
|
|
869 | |
|
|
870 | The "ithreads" work exactly like that: when creating a new ithreads |
|
|
871 | process, all state is copied (memory is copied physically, files and code |
|
|
872 | is copied logically). Afterwards, it isolates all modifications. On UNIX, |
|
|
873 | the same behaviour can be achieved by using operating system processes, |
|
|
874 | except that UNIX typically uses hardware built into the system to do this |
|
|
875 | efficiently, while the windows process emulation emulates this hardware in |
|
|
876 | software (rather efficiently, but of course it is still much slower than |
|
|
877 | dedicated hardware). |
|
|
878 | |
|
|
879 | As mentioned before, loading code, modifying code, modifying data |
|
|
880 | structures and so on is only visible in the ithreads process doing the |
|
|
881 | modification, not in other ithread processes within the same OS process. |
|
|
882 | |
|
|
883 | This is why "ithreads" do not implement threads for perl at all, only |
|
|
884 | processes. What makes it so bad is that on non-windows platforms, you can |
|
|
885 | actually take advantage of custom hardware for this purpose (as evidenced |
|
|
886 | by the forks module, which gives you the (i-) threads API, just much |
|
|
887 | faster). |
|
|
888 | |
|
|
889 | Sharing data is in the i-threads model is done by transfering data |
|
|
890 | structures between threads using copying semantics, which is very slow - |
|
|
891 | shared data simply does not exist. Benchmarks using i-threads which are |
|
|
892 | communication-intensive show extremely bad behaviour with i-threads (in |
|
|
893 | fact, so bad that Coro, which cannot take direct advantage of multiple |
|
|
894 | CPUs, is often orders of magnitude faster because it shares data using |
|
|
895 | real threads, refer to my talk for details). |
|
|
896 | |
|
|
897 | As summary, i-threads *use* threads to implement processes, while |
|
|
898 | the compatible forks module *uses* processes to emulate, uhm, |
|
|
899 | processes. I-threads slow down every perl program when enabled, and |
|
|
900 | outside of windows, serve no (or little) practical purpose, but |
|
|
901 | disadvantages every single-threaded Perl program. |
|
|
902 | |
|
|
903 | This is the reason that I try to avoid the name "ithreads", as it is |
|
|
904 | misleading as it implies that it implements some kind of thread model for |
|
|
905 | perl, and prefer the name "windows process emulation", which describes the |
|
|
906 | actual use and behaviour of it much better. |
|
|
907 | |
807 | =head1 SEE ALSO |
908 | =head1 SEE ALSO |
808 | |
909 | |
809 | Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>. |
910 | Event-Loop integration: L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>. |
810 | |
911 | |
811 | Debugging: L<Coro::Debug>. |
912 | Debugging: L<Coro::Debug>. |