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

Comparing Coro/Coro.pm (file contents):
Revision 1.266 by root, Wed Aug 26 07:41:07 2009 UTC vs.
Revision 1.287 by root, Sat Feb 19 06:51:22 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 (see section of same name for more 45but only the windows process emulation (see section of same name for
46details) ported to unix, and as such act as processes), Coro provides 46more details) ported to UNIX, and as such act as processes), Coro
47a full shared address space, which makes communication between threads 47provides a full shared address space, which makes communication between
48very easy. And Coro's threads are fast, too: disabling the Windows 48threads very easy. And coro threads are fast, too: disabling the Windows
49process emulation code in your perl and using Coro can easily result in 49process emulation code in your perl and using Coro can easily result in
50a two to four times speed increase for your programs. A parallel matrix 50a two to four times speed increase for your programs. A parallel matrix
51multiplication benchmark runs over 300 times faster on a single core than 51multiplication benchmark (very communication-intensive) runs over 300
52perl's pseudo-threads on a quad core using all four cores. 52times faster on a single core than perls pseudo-threads on a quad core
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.17; 333our $VERSION = 5.37;
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;
272=item schedule 507=item schedule
273 508
274Calls the scheduler. The scheduler will find the next coro that is 509Calls the scheduler. The scheduler will find the next coro that is
275to 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
276to 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
277in 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
278C<$Coro::idle> hook. 513C<$Coro::idle> hook.
279 514
280Please 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
281queue, so calling this function usually means you will never be called 516queue, so calling this function usually means you will never be called
282again unless something else (e.g. an event handler) calls C<< ->ready >>, 517again unless something else (e.g. an event handler) calls C<< ->ready >>,
579 wantarray ? @{$self->{_status}} : $self->{_status}[0]; 814 wantarray ? @{$self->{_status}} : $self->{_status}[0];
580} 815}
581 816
582=item $coro->on_destroy (\&cb) 817=item $coro->on_destroy (\&cb)
583 818
584Registers a callback that is called when this coro gets destroyed, 819Registers a callback that is called when this coro thread gets destroyed,
585but before it is joined. The callback gets passed the terminate arguments, 820but before it is joined. The callback gets passed the terminate arguments,
586if any, and I<must not> die, under any circumstances. 821if any, and I<must not> die, under any circumstances.
587 822
823There can be any number of C<on_destroy> callbacks per coro.
824
588=cut 825=cut
589 826
590sub on_destroy { 827sub on_destroy {
591 my ($self, $cb) = @_; 828 my ($self, $cb) = @_;
592 829
594} 831}
595 832
596=item $oldprio = $coro->prio ($newprio) 833=item $oldprio = $coro->prio ($newprio)
597 834
598Sets (or gets, if the argument is missing) the priority of the 835Sets (or gets, if the argument is missing) the priority of the
599coro. Higher priority coro get run before lower priority 836coro thread. Higher priority coro get run before lower priority
600coro. Priorities are small signed integers (currently -4 .. +3), 837coros. Priorities are small signed integers (currently -4 .. +3),
601that you can refer to using PRIO_xxx constants (use the import tag :prio 838that you can refer to using PRIO_xxx constants (use the import tag :prio
602to get then): 839to get then):
603 840
604 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN 841 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
605 3 > 1 > 0 > -1 > -3 > -4 842 3 > 1 > 0 > -1 > -3 > -4
606 843
607 # set priority to HIGH 844 # set priority to HIGH
608 current->prio (PRIO_HIGH); 845 current->prio (PRIO_HIGH);
609 846
610The idle coro ($Coro::idle) always has a lower priority than any 847The idle coro thread ($Coro::idle) always has a lower priority than any
611existing coro. 848existing coro.
612 849
613Changing the priority of the current coro will take effect immediately, 850Changing the priority of the current coro will take effect immediately,
614but changing the priority of coro in the ready queue (but not 851but changing the priority of a coro in the ready queue (but not running)
615running) will only take effect after the next schedule (of that 852will only take effect after the next schedule (of that coro). This is a
616coro). This is a bug that will be fixed in some future version. 853bug that will be fixed in some future version.
617 854
618=item $newprio = $coro->nice ($change) 855=item $newprio = $coro->nice ($change)
619 856
620Similar to C<prio>, but subtract the given value from the priority (i.e. 857Similar to C<prio>, but subtract the given value from the priority (i.e.
621higher values mean lower priority, just as in unix). 858higher values mean lower priority, just as in UNIX's nice command).
622 859
623=item $olddesc = $coro->desc ($newdesc) 860=item $olddesc = $coro->desc ($newdesc)
624 861
625Sets (or gets in case the argument is missing) the description for this 862Sets (or gets in case the argument is missing) the description for this
626coro. This is just a free-form string you can associate with a 863coro thread. This is just a free-form string you can associate with a
627coro. 864coro.
628 865
629This method simply sets the C<< $coro->{desc} >> member to the given 866This method simply sets the C<< $coro->{desc} >> member to the given
630string. You can modify this member directly if you wish. 867string. You can modify this member directly if you wish, and in fact, this
868is often preferred to indicate major processing states that cna then be
869seen for example in a L<Coro::Debug> session:
870
871 sub my_long_function {
872 local $Coro::current->{desc} = "now in my_long_function";
873 ...
874 $Coro::current->{desc} = "my_long_function: phase 1";
875 ...
876 $Coro::current->{desc} = "my_long_function: phase 2";
877 ...
878 }
631 879
632=cut 880=cut
633 881
634sub desc { 882sub desc {
635 my $old = $_[0]{desc}; 883 my $old = $_[0]{desc};
672returning a new coderef. Unblocking means that calling the new coderef 920returning a new coderef. Unblocking means that calling the new coderef
673will return immediately without blocking, returning nothing, while the 921will return immediately without blocking, returning nothing, while the
674original code ref will be called (with parameters) from within another 922original code ref will be called (with parameters) from within another
675coro. 923coro.
676 924
677The reason this function exists is that many event libraries (such as the 925The reason this function exists is that many event libraries (such as
678venerable L<Event|Event> module) are not thread-safe (a weaker form 926the venerable L<Event|Event> module) are not thread-safe (a weaker form
679of reentrancy). This means you must not block within event callbacks, 927of reentrancy). This means you must not block within event callbacks,
680otherwise you might suffer from crashes or worse. The only event library 928otherwise you might suffer from crashes or worse. The only event library
681currently known that is safe to use without C<unblock_sub> is L<EV>. 929currently known that is safe to use without C<unblock_sub> is L<EV> (but
930you might still run into deadlocks if all event loops are blocked).
931
932Coro will try to catch you when you block in the event loop
933("FATAL:$Coro::IDLE blocked itself"), but this is just best effort and
934only works when you do not run your own event loop.
682 935
683This function allows your callbacks to block by executing them in another 936This function allows your callbacks to block by executing them in another
684coro where it is safe to block. One example where blocking is handy 937coro where it is safe to block. One example where blocking is handy
685is when you use the L<Coro::AIO|Coro::AIO> functions to save results to 938is when you use the L<Coro::AIO|Coro::AIO> functions to save results to
686disk, for example. 939disk, for example.
728 unshift @unblock_queue, [$cb, @_]; 981 unshift @unblock_queue, [$cb, @_];
729 $unblock_scheduler->ready; 982 $unblock_scheduler->ready;
730 } 983 }
731} 984}
732 985
733=item $cb = Coro::rouse_cb 986=item $cb = rouse_cb
734 987
735Create and return a "rouse callback". That's a code reference that, 988Create and return a "rouse callback". That's a code reference that,
736when called, will remember a copy of its arguments and notify the owner 989when called, will remember a copy of its arguments and notify the owner
737coro of the callback. 990coro of the callback.
738 991
739See the next function. 992See the next function.
740 993
741=item @args = Coro::rouse_wait [$cb] 994=item @args = rouse_wait [$cb]
742 995
743Wait for the specified rouse callback (or the last one that was created in 996Wait for the specified rouse callback (or the last one that was created in
744this coro). 997this coro).
745 998
746As soon as the callback is invoked (or when the callback was invoked 999As soon as the callback is invoked (or when the callback was invoked
752See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example. 1005See the section B<HOW TO WAIT FOR A CALLBACK> for an actual usage example.
753 1006
754=back 1007=back
755 1008
756=cut 1009=cut
1010
1011for my $module (qw(Channel RWLock Semaphore SemaphoreSet Signal Specific)) {
1012 my $old = defined &{"Coro::$module\::new"} && \&{"Coro::$module\::new"};
1013
1014 *{"Coro::$module\::new"} = sub {
1015 require "Coro/$module.pm";
1016
1017 # some modules have their new predefined in State.xs, some don't
1018 *{"Coro::$module\::new"} = $old
1019 if $old;
1020
1021 goto &{"Coro::$module\::new"};
1022 };
1023}
757 1024
7581; 10251;
759 1026
760=head1 HOW TO WAIT FOR A CALLBACK 1027=head1 HOW TO WAIT FOR A CALLBACK
761 1028
843the windows process emulation enabled under unix roughly halves perl 1110the windows process emulation enabled under unix roughly halves perl
844performance, even when not used. 1111performance, even when not used.
845 1112
846=item coro switching is not signal safe 1113=item coro switching is not signal safe
847 1114
848You must not switch to another coro from within a signal handler 1115You must not switch to another coro from within a signal handler (only
849(only relevant with %SIG - most event libraries provide safe signals). 1116relevant with %SIG - most event libraries provide safe signals), I<unless>
1117you are sure you are not interrupting a Coro function.
850 1118
851That means you I<MUST NOT> call any function that might "block" the 1119That means you I<MUST NOT> call any function that might "block" the
852current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or 1120current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
853anything that calls those. Everything else, including calling C<ready>, 1121anything that calls those. Everything else, including calling C<ready>,
854works. 1122works.
857 1125
858 1126
859=head1 WINDOWS PROCESS EMULATION 1127=head1 WINDOWS PROCESS EMULATION
860 1128
861A great many people seem to be confused about ithreads (for example, Chip 1129A great many people seem to be confused about ithreads (for example, Chip
862Salzenberg called me unintelligent, incapable, stupid and ingullible, 1130Salzenberg called me unintelligent, incapable, stupid and gullible,
863while in the same mail making rather confused statements about perl 1131while in the same mail making rather confused statements about perl
864ithreads (for example, that memory or files would be shared), showing his 1132ithreads (for example, that memory or files would be shared), showing his
865lack of understanding of this area - if it is hard to understand for Chip, 1133lack of understanding of this area - if it is hard to understand for Chip,
866it is probably not obvious to everybody). 1134it is probably not obvious to everybody).
867 1135
868What follows is an ultra-condensed version of my talk about threads in 1136What follows is an ultra-condensed version of my talk about threads in
869scripting languages given onthe perl workshop 2009: 1137scripting languages given on the perl workshop 2009:
870 1138
871The so-called "ithreads" were originally implemented for two reasons: 1139The so-called "ithreads" were originally implemented for two reasons:
872first, to (badly) emulate unix processes on native win32 perls, and 1140first, to (badly) emulate unix processes on native win32 perls, and
873secondly, to replace the older, real thread model ("5.005-threads"). 1141secondly, to replace the older, real thread model ("5.005-threads").
874 1142

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines