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

Comparing Coro/Coro.pm (file contents):
Revision 1.268 by root, Thu Oct 1 23:16:27 2009 UTC vs.
Revision 1.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 common::sense; 319use common::sense;
81 328
82our $idle; # idle handler 329our $idle; # idle handler
83our $main; # main coro 330our $main; # main coro
84our $current; # current coro 331our $current; # current coro
85 332
86our $VERSION = 5.17; 333our $VERSION = 5.37;
87 334
88our @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);
89our %EXPORT_TAGS = ( 336our %EXPORT_TAGS = (
90 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)],
91); 338);
92our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready)); 339our @EXPORT_OK = (@{$EXPORT_TAGS{prio}}, qw(nready));
93 340
124 371
125This 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
126usually 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
127pretty low-level functionality. 374pretty low-level functionality.
128 375
129This 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).
130 378
131If it is a callback, the it is called whenever the scheduler finds no 379The default implementation dies with "FATAL: deadlock detected.", followed
132ready coros to run. The default implementation prints "FATAL: 380by a thread listing, because the program has no other way to continue.
133deadlock detected" and exits, because the program has no other way to
134continue.
135
136If it is a coro object, then this object will be readied (without
137invoking any ready hooks, however) when the scheduler finds no other ready
138coros to run.
139 381
140This hook is overwritten by modules such as C<Coro::EV> and 382This hook is overwritten by modules such as C<Coro::EV> and
141C<Coro::AnyEvent> to wait on an external event that hopefully wake up a 383C<Coro::AnyEvent> to wait on an external event that hopefully wakes up a
142coro so the scheduler can run it. 384coro so the scheduler can run it.
143 385
144Note that the callback I<must not>, under any circumstances, block
145the current coro. Normally, this is achieved by having an "idle
146coro" that calls the event loop and then blocks again, and then
147readying that coro in the idle handler, or by simply placing the idle
148coro in this variable.
149
150See L<Coro::Event> or L<Coro::AnyEvent> for examples of using this 386See L<Coro::EV> or L<Coro::AnyEvent> for examples of using this technique.
151technique.
152 387
153Please note that if your callback recursively invokes perl (e.g. for event
154handlers), then it must be prepared to be called recursively itself.
155
156=cut 388=cut
157 389
158$idle = sub { 390# ||= because other modules could have provided their own by now
159 warn "oi\n";#d# 391$idle ||= new Coro sub {
160 Carp::confess ("FATAL: deadlock detected"); 392 require Coro::Debug;
393 die "FATAL: deadlock detected.\n"
394 . Coro::Debug::ps_listing ();
161}; 395};
162 396
163# this coro is necessary because a coro 397# this coro is necessary because a coro
164# cannot destroy itself. 398# cannot destroy itself.
165our @destroy; 399our @destroy;
273=item schedule 507=item schedule
274 508
275Calls the scheduler. The scheduler will find the next coro that is 509Calls the scheduler. The scheduler will find the next coro that is
276to be run from the ready queue and switches to it. The next coro 510to be run from the ready queue and switches to it. The next coro
277to be run is simply the one with the highest priority that is longest 511to be run is simply the one with the highest priority that is longest
278in its ready queue. If there is no coro ready, it will clal the 512in its ready queue. If there is no coro ready, it will call the
279C<$Coro::idle> hook. 513C<$Coro::idle> hook.
280 514
281Please 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
282queue, so calling this function usually means you will never be called 516queue, so calling this function usually means you will never be called
283again unless something else (e.g. an event handler) calls C<< ->ready >>, 517again unless something else (e.g. an event handler) calls C<< ->ready >>,
580 wantarray ? @{$self->{_status}} : $self->{_status}[0]; 814 wantarray ? @{$self->{_status}} : $self->{_status}[0];
581} 815}
582 816
583=item $coro->on_destroy (\&cb) 817=item $coro->on_destroy (\&cb)
584 818
585Registers a callback that is called when this coro gets destroyed, 819Registers a callback that is called when this coro thread gets destroyed,
586but before it is joined. The callback gets passed the terminate arguments, 820but before it is joined. The callback gets passed the terminate arguments,
587if any, and I<must not> die, under any circumstances. 821if any, and I<must not> die, under any circumstances.
588 822
823There can be any number of C<on_destroy> callbacks per coro.
824
589=cut 825=cut
590 826
591sub on_destroy { 827sub on_destroy {
592 my ($self, $cb) = @_; 828 my ($self, $cb) = @_;
593 829
595} 831}
596 832
597=item $oldprio = $coro->prio ($newprio) 833=item $oldprio = $coro->prio ($newprio)
598 834
599Sets (or gets, if the argument is missing) the priority of the 835Sets (or gets, if the argument is missing) the priority of the
600coro. Higher priority coro get run before lower priority 836coro thread. Higher priority coro get run before lower priority
601coro. Priorities are small signed integers (currently -4 .. +3), 837coros. Priorities are small signed integers (currently -4 .. +3),
602that 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
603to get then): 839to get then):
604 840
605 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
606 3 > 1 > 0 > -1 > -3 > -4 842 3 > 1 > 0 > -1 > -3 > -4
607 843
608 # set priority to HIGH 844 # set priority to HIGH
609 current->prio (PRIO_HIGH); 845 current->prio (PRIO_HIGH);
610 846
611The idle coro ($Coro::idle) always has a lower priority than any 847The idle coro thread ($Coro::idle) always has a lower priority than any
612existing coro. 848existing coro.
613 849
614Changing the priority of the current coro will take effect immediately, 850Changing the priority of the current coro will take effect immediately,
615but 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)
616running) will only take effect after the next schedule (of that 852will only take effect after the next schedule (of that coro). This is a
617coro). This is a bug that will be fixed in some future version. 853bug that will be fixed in some future version.
618 854
619=item $newprio = $coro->nice ($change) 855=item $newprio = $coro->nice ($change)
620 856
621Similar 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.
622higher values mean lower priority, just as in unix). 858higher values mean lower priority, just as in UNIX's nice command).
623 859
624=item $olddesc = $coro->desc ($newdesc) 860=item $olddesc = $coro->desc ($newdesc)
625 861
626Sets (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
627coro. 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
628coro. 864coro.
629 865
630This method simply sets the C<< $coro->{desc} >> member to the given 866This method simply sets the C<< $coro->{desc} >> member to the given
631string. 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 }
632 879
633=cut 880=cut
634 881
635sub desc { 882sub desc {
636 my $old = $_[0]{desc}; 883 my $old = $_[0]{desc};
673returning a new coderef. Unblocking means that calling the new coderef 920returning a new coderef. Unblocking means that calling the new coderef
674will return immediately without blocking, returning nothing, while the 921will return immediately without blocking, returning nothing, while the
675original code ref will be called (with parameters) from within another 922original code ref will be called (with parameters) from within another
676coro. 923coro.
677 924
678The reason this function exists is that many event libraries (such as the 925The reason this function exists is that many event libraries (such as
679venerable L<Event|Event> module) are not thread-safe (a weaker form 926the venerable L<Event|Event> module) are not thread-safe (a weaker form
680of reentrancy). This means you must not block within event callbacks, 927of reentrancy). This means you must not block within event callbacks,
681otherwise you might suffer from crashes or worse. The only event library 928otherwise you might suffer from crashes or worse. The only event library
682currently known that is safe to use without C<unblock_sub> is L<EV>. 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.
683 935
684This function allows your callbacks to block by executing them in another 936This function allows your callbacks to block by executing them in another
685coro 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
686is 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
687disk, for example. 939disk, for example.
729 unshift @unblock_queue, [$cb, @_]; 981 unshift @unblock_queue, [$cb, @_];
730 $unblock_scheduler->ready; 982 $unblock_scheduler->ready;
731 } 983 }
732} 984}
733 985
734=item $cb = Coro::rouse_cb 986=item $cb = rouse_cb
735 987
736Create and return a "rouse callback". That's a code reference that, 988Create and return a "rouse callback". That's a code reference that,
737when 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
738coro of the callback. 990coro of the callback.
739 991
740See the next function. 992See the next function.
741 993
742=item @args = Coro::rouse_wait [$cb] 994=item @args = rouse_wait [$cb]
743 995
744Wait 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
745this coro). 997this coro).
746 998
747As 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
753See 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.
754 1006
755=back 1007=back
756 1008
757=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}
758 1024
7591; 10251;
760 1026
761=head1 HOW TO WAIT FOR A CALLBACK 1027=head1 HOW TO WAIT FOR A CALLBACK
762 1028
844the windows process emulation enabled under unix roughly halves perl 1110the windows process emulation enabled under unix roughly halves perl
845performance, even when not used. 1111performance, even when not used.
846 1112
847=item coro switching is not signal safe 1113=item coro switching is not signal safe
848 1114
849You must not switch to another coro from within a signal handler 1115You must not switch to another coro from within a signal handler (only
850(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.
851 1118
852That 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
853current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or 1120current coro - C<cede>, C<schedule> C<< Coro::Semaphore->down >> or
854anything that calls those. Everything else, including calling C<ready>, 1121anything that calls those. Everything else, including calling C<ready>,
855works. 1122works.
865ithreads (for example, that memory or files would be shared), showing his 1132ithreads (for example, that memory or files would be shared), showing his
866lack of understanding of this area - if it is hard to understand for Chip, 1133lack of understanding of this area - if it is hard to understand for Chip,
867it is probably not obvious to everybody). 1134it is probably not obvious to everybody).
868 1135
869What 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
870scripting languages given onthe perl workshop 2009: 1137scripting languages given on the perl workshop 2009:
871 1138
872The so-called "ithreads" were originally implemented for two reasons: 1139The so-called "ithreads" were originally implemented for two reasons:
873first, to (badly) emulate unix processes on native win32 perls, and 1140first, to (badly) emulate unix processes on native win32 perls, and
874secondly, to replace the older, real thread model ("5.005-threads"). 1141secondly, to replace the older, real thread model ("5.005-threads").
875 1142

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines