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

Comparing Coro/README (file contents):
Revision 1.14 by root, Sat May 10 22:32:40 2008 UTC vs.
Revision 1.39 by root, Fri Jul 14 13:14:32 2017 UTC

1NAME 1NAME
2 Coro - coroutine process abstraction 2 Coro - the only real threads in perl
3 3
4SYNOPSIS 4SYNOPSIS
5 use Coro; 5 use Coro;
6 6
7 async { 7 async {
8 # some asynchronous thread of execution 8 # some asynchronous thread of execution
9 print "2\n"; 9 print "2\n";
10 cede; # yield back to main 10 cede; # yield back to main
11 print "4\n"; 11 print "4\n";
12 }; 12 };
13 print "1\n"; 13 print "1\n";
14 cede; # yield to coroutine 14 cede; # yield to coro
15 print "3\n"; 15 print "3\n";
16 cede; # and again 16 cede; # and again
17 17
18 # use locking 18 # use locking
19 my $lock = new Coro::Semaphore; 19 my $lock = new Coro::Semaphore;
20 my $locked; 20 my $locked;
21 21
22 $lock->down; 22 $lock->down;
23 $locked = 1; 23 $locked = 1;
24 $lock->up; 24 $lock->up;
25 25
26DESCRIPTION 26DESCRIPTION
27 This module collection manages coroutines. Coroutines are similar to 27 For a tutorial-style introduction, please read the Coro::Intro manpage.
28 threads but don't (in general) run in parallel at the same time even on 28 This manpage mainly contains reference information.
29 SMP machines. The specific flavor of coroutine used in this module also 29
30 guarantees you that it will not switch between coroutines unless 30 This module collection manages continuations in general, most often in
31 the form of cooperative threads (also called coros, or simply "coro" in
32 the documentation). They are similar to kernel threads but don't (in
33 general) run in parallel at the same time even on SMP machines. The
34 specific flavor of thread offered by this module also guarantees you
35 that it will not switch between threads unless necessary, at
31 necessary, at easily-identified points in your program, so locking and 36 easily-identified points in your program, so locking and parallel access
32 parallel access are rarely an issue, making coroutine programming much 37 are rarely an issue, making thread programming much safer and easier
33 safer and easier than threads programming. 38 than using other thread models.
34 39
35 Unlike a normal perl program, however, coroutines allow you to have 40 Unlike the so-called "Perl threads" (which are not actually real threads
36 multiple running interpreters that share data, which is especially 41 but only the windows process emulation (see section of same name for
37 useful to code pseudo-parallel processes and for event-based 42 more details) ported to UNIX, and as such act as processes), Coro
38 programming, such as multiple HTTP-GET requests running concurrently. 43 provides a full shared address space, which makes communication between
39 See Coro::AnyEvent to learn more. 44 threads very easy. And coro threads are fast, too: disabling the Windows
45 process emulation code in your perl and using Coro can easily result in
46 a two to four times speed increase for your programs. A parallel matrix
47 multiplication benchmark (very communication-intensive) runs over 300
48 times faster on a single core than perls pseudo-threads on a quad core
49 using all four cores.
40 50
41 Coroutines are also useful because Perl has no support for threads (the 51 Coro achieves that by supporting multiple running interpreters that
42 so called "threads" that perl offers are nothing more than the (bad) 52 share data, which is especially useful to code pseudo-parallel processes
43 process emulation coming from the Windows platform: On standard 53 and for event-based programming, such as multiple HTTP-GET requests
44 operating systems they serve no purpose whatsoever, except by making 54 running concurrently. See Coro::AnyEvent to learn more on how to
45 your programs slow and making them use a lot of memory. Best disable 55 integrate Coro into an event-based environment.
46 them when building perl, or aks your software vendor/distributor to do
47 it for you).
48 56
49 In this module, coroutines are defined as "callchain + lexical variables 57 In this module, a thread is defined as "callchain + lexical variables +
50 + @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own 58 some package variables + C stack), that is, a thread has its own
51 callchain, its own set of lexicals and its own set of perls most 59 callchain, its own set of lexicals and its own set of perls most
52 important global variables (see Coro::State for more configuration). 60 important global variables (see Coro::State for more configuration and
61 background info).
53 62
63 See also the "SEE ALSO" section at the end of this document - the Coro
64 module family is quite large.
65
66CORO THREAD LIFE CYCLE
67 During the long and exciting (or not) life of a coro thread, it goes
68 through a number of states:
69
70 1. Creation
71 The first thing in the life of a coro thread is it's creation -
72 obviously. The typical way to create a thread is to call the "async
73 BLOCK" function:
74
75 async {
76 # thread code goes here
77 };
78
79 You can also pass arguments, which are put in @_:
80
81 async {
82 print $_[1]; # prints 2
83 } 1, 2, 3;
84
85 This creates a new coro thread and puts it into the ready queue,
86 meaning it will run as soon as the CPU is free for it.
87
88 "async" will return a Coro object - you can store this for future
89 reference or ignore it - a thread that is running, ready to run or
90 waiting for some event is alive on it's own.
91
92 Another way to create a thread is to call the "new" constructor with
93 a code-reference:
94
95 new Coro sub {
96 # thread code goes here
97 }, @optional_arguments;
98
99 This is quite similar to calling "async", but the important
100 difference is that the new thread is not put into the ready queue,
101 so the thread will not run until somebody puts it there. "async" is,
102 therefore, identical to this sequence:
103
104 my $coro = new Coro sub {
105 # thread code goes here
106 };
107 $coro->ready;
108 return $coro;
109
110 2. Startup
111 When a new coro thread is created, only a copy of the code reference
112 and the arguments are stored, no extra memory for stacks and so on
113 is allocated, keeping the coro thread in a low-memory state.
114
115 Only when it actually starts executing will all the resources be
116 finally allocated.
117
118 The optional arguments specified at coro creation are available in
119 @_, similar to function calls.
120
121 3. Running / Blocking
122 A lot can happen after the coro thread has started running. Quite
123 usually, it will not run to the end in one go (because you could use
124 a function instead), but it will give up the CPU regularly because
125 it waits for external events.
126
127 As long as a coro thread runs, its Coro object is available in the
128 global variable $Coro::current.
129
130 The low-level way to give up the CPU is to call the scheduler, which
131 selects a new coro thread to run:
132
133 Coro::schedule;
134
135 Since running threads are not in the ready queue, calling the
136 scheduler without doing anything else will block the coro thread
137 forever - you need to arrange either for the coro to put woken up
138 (readied) by some other event or some other thread, or you can put
139 it into the ready queue before scheduling:
140
141 # this is exactly what Coro::cede does
142 $Coro::current->ready;
143 Coro::schedule;
144
145 All the higher-level synchronisation methods (Coro::Semaphore,
146 Coro::rouse_*...) are actually implemented via "->ready" and
147 "Coro::schedule".
148
149 While the coro thread is running it also might get assigned a
150 C-level thread, or the C-level thread might be unassigned from it,
151 as the Coro runtime wishes. A C-level thread needs to be assigned
152 when your perl thread calls into some C-level function and that
153 function in turn calls perl and perl then wants to switch
154 coroutines. This happens most often when you run an event loop and
155 block in the callback, or when perl itself calls some function such
156 as "AUTOLOAD" or methods via the "tie" mechanism.
157
158 4. Termination
159 Many threads actually terminate after some time. There are a number
160 of ways to terminate a coro thread, the simplest is returning from
161 the top-level code reference:
162
163 async {
164 # after returning from here, the coro thread is terminated
165 };
166
167 async {
168 return if 0.5 < rand; # terminate a little earlier, maybe
169 print "got a chance to print this\n";
170 # or here
171 };
172
173 Any values returned from the coroutine can be recovered using
174 "->join":
175
176 my $coro = async {
177 "hello, world\n" # return a string
178 };
179
180 my $hello_world = $coro->join;
181
182 print $hello_world;
183
184 Another way to terminate is to call "Coro::terminate", which at any
185 subroutine call nesting level:
186
187 async {
188 Coro::terminate "return value 1", "return value 2";
189 };
190
191 Yet another way is to "->cancel" (or "->safe_cancel") the coro
192 thread from another thread:
193
194 my $coro = async {
195 exit 1;
196 };
197
198 $coro->cancel; # also accepts values for ->join to retrieve
199
200 Cancellation *can* be dangerous - it's a bit like calling "exit"
201 without actually exiting, and might leave C libraries and XS modules
202 in a weird state. Unlike other thread implementations, however, Coro
203 is exceptionally safe with regards to cancellation, as perl will
204 always be in a consistent state, and for those cases where you want
205 to do truly marvellous things with your coro while it is being
206 cancelled - that is, make sure all cleanup code is executed from the
207 thread being cancelled - there is even a "->safe_cancel" method.
208
209 So, cancelling a thread that runs in an XS event loop might not be
210 the best idea, but any other combination that deals with perl only
211 (cancelling when a thread is in a "tie" method or an "AUTOLOAD" for
212 example) is safe.
213
214 Last not least, a coro thread object that isn't referenced is
215 "->cancel"'ed automatically - just like other objects in Perl. This
216 is not such a common case, however - a running thread is referencedy
217 by $Coro::current, a thread ready to run is referenced by the ready
218 queue, a thread waiting on a lock or semaphore is referenced by
219 being in some wait list and so on. But a thread that isn't in any of
220 those queues gets cancelled:
221
222 async {
223 schedule; # cede to other coros, don't go into the ready queue
224 };
225
226 cede;
227 # now the async above is destroyed, as it is not referenced by anything.
228
229 A slightly embellished example might make it clearer:
230
231 async {
232 my $guard = Guard::guard { print "destroyed\n" };
233 schedule while 1;
234 };
235
236 cede;
237
238 Superficially one might not expect any output - since the "async"
239 implements an endless loop, the $guard will not be cleaned up.
240 However, since the thread object returned by "async" is not stored
241 anywhere, the thread is initially referenced because it is in the
242 ready queue, when it runs it is referenced by $Coro::current, but
243 when it calls "schedule", it gets "cancel"ed causing the guard
244 object to be destroyed (see the next section), and printing it's
245 message.
246
247 If this seems a bit drastic, remember that this only happens when
248 nothing references the thread anymore, which means there is no way
249 to further execute it, ever. The only options at this point are
250 leaking the thread, or cleaning it up, which brings us to...
251
252 5. Cleanup
253 Threads will allocate various resources. Most but not all will be
254 returned when a thread terminates, during clean-up.
255
256 Cleanup is quite similar to throwing an uncaught exception: perl
257 will work it's way up through all subroutine calls and blocks. On
258 it's way, it will release all "my" variables, undo all "local"'s and
259 free any other resources truly local to the thread.
260
261 So, a common way to free resources is to keep them referenced only
262 by my variables:
263
264 async {
265 my $big_cache = new Cache ...;
266 };
267
268 If there are no other references, then the $big_cache object will be
269 freed when the thread terminates, regardless of how it does so.
270
271 What it does "NOT" do is unlock any Coro::Semaphores or similar
272 resources, but that's where the "guard" methods come in handy:
273
274 my $sem = new Coro::Semaphore;
275
276 async {
277 my $lock_guard = $sem->guard;
278 # if we return, or die or get cancelled, here,
279 # then the semaphore will be "up"ed.
280 };
281
282 The "Guard::guard" function comes in handy for any custom cleanup
283 you might want to do (but you cannot switch to other coroutines from
284 those code blocks):
285
286 async {
287 my $window = new Gtk2::Window "toplevel";
288 # The window will not be cleaned up automatically, even when $window
289 # gets freed, so use a guard to ensure it's destruction
290 # in case of an error:
291 my $window_guard = Guard::guard { $window->destroy };
292
293 # we are safe here
294 };
295
296 Last not least, "local" can often be handy, too, e.g. when
297 temporarily replacing the coro thread description:
298
299 sub myfunction {
300 local $Coro::current->{desc} = "inside myfunction(@_)";
301
302 # if we return or die here, the description will be restored
303 }
304
305 6. Viva La Zombie Muerte
306 Even after a thread has terminated and cleaned up its resources, the
307 Coro object still is there and stores the return values of the
308 thread.
309
310 When there are no other references, it will simply be cleaned up and
311 freed.
312
313 If there areany references, the Coro object will stay around, and
314 you can call "->join" as many times as you wish to retrieve the
315 result values:
316
317 async {
318 print "hi\n";
319 1
320 };
321
322 # run the async above, and free everything before returning
323 # from Coro::cede:
324 Coro::cede;
325
326 {
327 my $coro = async {
328 print "hi\n";
329 1
330 };
331
332 # run the async above, and clean up, but do not free the coro
333 # object:
334 Coro::cede;
335
336 # optionally retrieve the result values
337 my @results = $coro->join;
338
339 # now $coro goes out of scope, and presumably gets freed
340 };
341
342GLOBAL VARIABLES
54 $Coro::main 343 $Coro::main
55 This variable stores the coroutine object that represents the main 344 This variable stores the Coro object that represents the main
56 program. While you cna "ready" it and do most other things you can 345 program. While you can "ready" it and do most other things you can
57 do to coroutines, it is mainly useful to compare again 346 do to coro, it is mainly useful to compare again $Coro::current, to
58 $Coro::current, to see wether you are running in the main program or 347 see whether you are running in the main program or not.
59 not.
60 348
61 $Coro::current 349 $Coro::current
62 The coroutine object representing the current coroutine (the last 350 The Coro object representing the current coro (the last coro that
63 coroutine that the Coro scheduler switched to). The initial value is 351 the Coro scheduler switched to). The initial value is $Coro::main
64 $main (of course). 352 (of course).
65 353
66 This variable is strictly *read-only*. You can take copies of the 354 This variable is strictly *read-only*. You can take copies of the
67 value stored in it and use it as any other coroutine object, but you 355 value stored in it and use it as any other Coro object, but you must
68 must not otherwise modify the variable itself. 356 not otherwise modify the variable itself.
69 357
70 $Coro::idle 358 $Coro::idle
71 This variable is mainly useful to integrate Coro into event loops. 359 This variable is mainly useful to integrate Coro into event loops.
72 It is usually better to rely on Coro::AnyEvent or L"Coro::EV", as 360 It is usually better to rely on Coro::AnyEvent or Coro::EV, as this
73 this is pretty low-level functionality. 361 is pretty low-level functionality.
74 362
75 This variable stores a callback that is called whenever the 363 This variable stores a Coro object that is put into the ready queue
76 scheduler finds no ready coroutines to run. The default 364 when there are no other ready threads (without invoking any ready
77 implementation prints "FATAL: deadlock detected" and exits, because 365 hooks).
78 the program has no other way to continue.
79 366
367 The default implementation dies with "FATAL: deadlock detected.",
368 followed by a thread listing, because the program has no other way
369 to continue.
370
80 This hook is overwritten by modules such as "Coro::Timer" and 371 This hook is overwritten by modules such as "Coro::EV" and
81 "Coro::AnyEvent" to wait on an external event that hopefully wake up 372 "Coro::AnyEvent" to wait on an external event that hopefully wakes
82 a coroutine so the scheduler can run it. 373 up a coro so the scheduler can run it.
83 374
84 Note that the callback *must not*, under any circumstances, block
85 the current coroutine. Normally, this is achieved by having an "idle
86 coroutine" that calls the event loop and then blocks again, and then
87 readying that coroutine in the idle handler.
88
89 See Coro::Event or Coro::AnyEvent for examples of using this 375 See Coro::EV or Coro::AnyEvent for examples of using this technique.
90 technique.
91 376
92 Please note that if your callback recursively invokes perl (e.g. for
93 event handlers), then it must be prepared to be called recursively
94 itself.
95
96 SIMPLE COROUTINE CREATION 377SIMPLE CORO CREATION
97 async { ... } [@args...] 378 async { ... } [@args...]
98 Create a new coroutine and return it's coroutine object (usually 379 Create a new coro and return its Coro object (usually unused). The
99 unused). The coroutine will be put into the ready queue, so it will 380 coro will be put into the ready queue, so it will start running
100 start running automatically on the next scheduler run. 381 automatically on the next scheduler run.
101 382
102 The first argument is a codeblock/closure that should be executed in 383 The first argument is a codeblock/closure that should be executed in
103 the coroutine. When it returns argument returns the coroutine is 384 the coro. When it returns argument returns the coro is automatically
104 automatically terminated. 385 terminated.
105 386
106 The remaining arguments are passed as arguments to the closure. 387 The remaining arguments are passed as arguments to the closure.
107 388
108 See the "Coro::State::new" constructor for info about the coroutine 389 See the "Coro::State::new" constructor for info about the coro
109 environment in which coroutines are executed. 390 environment in which coro are executed.
110 391
111 Calling "exit" in a coroutine will do the same as calling exit 392 Calling "exit" in a coro will do the same as calling exit outside
112 outside the coroutine. Likewise, when the coroutine dies, the 393 the coro. Likewise, when the coro dies, the program will exit, just
113 program will exit, just as it would in the main program. 394 as it would in the main program.
114 395
115 If you do not want that, you can provide a default "die" handler, or 396 If you do not want that, you can provide a default "die" handler, or
116 simply avoid dieing (by use of "eval"). 397 simply avoid dieing (by use of "eval").
117 398
118 Example: Create a new coroutine that just prints its arguments. 399 Example: Create a new coro that just prints its arguments.
119 400
120 async { 401 async {
121 print "@_\n"; 402 print "@_\n";
122 } 1,2,3,4; 403 } 1,2,3,4;
123 404
124 async_pool { ... } [@args...] 405 async_pool { ... } [@args...]
125 Similar to "async", but uses a coroutine pool, so you should not 406 Similar to "async", but uses a coro pool, so you should not call
126 call terminate or join on it (although you are allowed to), and you 407 terminate or join on it (although you are allowed to), and you get a
127 get a coroutine that might have executed other code already (which 408 coro that might have executed other code already (which can be good
128 can be good or bad :). 409 or bad :).
129 410
130 On the plus side, this function is faster than creating (and 411 On the plus side, this function is about twice as fast as creating
131 destroying) a completely new coroutine, so if you need a lot of 412 (and destroying) a completely new coro, so if you need a lot of
132 generic coroutines in quick successsion, use "async_pool", not 413 generic coros in quick successsion, use "async_pool", not "async".
133 "async".
134 414
135 The code block is executed in an "eval" context and a warning will 415 The code block is executed in an "eval" context and a warning will
136 be issued in case of an exception instead of terminating the 416 be issued in case of an exception instead of terminating the
137 program, as "async" does. As the coroutine is being reused, stuff 417 program, as "async" does. As the coro is being reused, stuff like
138 like "on_destroy" will not work in the expected way, unless you call 418 "on_destroy" will not work in the expected way, unless you call
139 terminate or cancel, which somehow defeats the purpose of pooling 419 terminate or cancel, which somehow defeats the purpose of pooling
140 (but is fine in the exceptional case). 420 (but is fine in the exceptional case).
141 421
142 The priority will be reset to 0 after each run, tracing will be 422 The priority will be reset to 0 after each run, all "swap_sv" calls
143 disabled, the description will be reset and the default output 423 will be undone, tracing will be disabled, the description will be
144 filehandle gets restored, so you can change all these. Otherwise the 424 reset and the default output filehandle gets restored, so you can
145 coroutine will be re-used "as-is": most notably if you change other 425 change all these. Otherwise the coro will be re-used "as-is": most
146 per-coroutine global stuff such as $/ you *must needs* to revert 426 notably if you change other per-coro global stuff such as $/ you
147 that change, which is most simply done by using local as in: " local 427 *must needs* revert that change, which is most simply done by using
148 $/ ". 428 local as in: "local $/".
149 429
150 The pool size is limited to 8 idle coroutines (this can be adjusted 430 The idle pool size is limited to 8 idle coros (this can be adjusted
151 by changing $Coro::POOL_SIZE), and there can be as many non-idle 431 by changing $Coro::POOL_SIZE), but there can be as many non-idle
152 coros as required. 432 coros as required.
153 433
154 If you are concerned about pooled coroutines growing a lot because a 434 If you are concerned about pooled coros growing a lot because a
155 single "async_pool" used a lot of stackspace you can e.g. 435 single "async_pool" used a lot of stackspace you can e.g.
156 "async_pool { terminate }" once per second or so to slowly replenish 436 "async_pool { terminate }" once per second or so to slowly replenish
157 the pool. In addition to that, when the stacks used by a handler 437 the pool. In addition to that, when the stacks used by a handler
158 grows larger than 16kb (adjustable via $Coro::POOL_RSS) it will also 438 grows larger than 32kb (adjustable via $Coro::POOL_RSS) it will also
159 be destroyed. 439 be destroyed.
160 440
161 STATIC METHODS 441STATIC METHODS
162 Static methods are actually functions that operate on the current 442 Static methods are actually functions that implicitly operate on the
163 coroutine. 443 current coro.
164 444
165 schedule 445 schedule
166 Calls the scheduler. The scheduler will find the next coroutine that 446 Calls the scheduler. The scheduler will find the next coro that is
167 is to be run from the ready queue and switches to it. The next 447 to be run from the ready queue and switches to it. The next coro to
168 coroutine to be run is simply the one with the highest priority that 448 be run is simply the one with the highest priority that is longest
169 is longest in its ready queue. If there is no coroutine ready, it 449 in its ready queue. If there is no coro ready, it will call the
170 will clal the $Coro::idle hook. 450 $Coro::idle hook.
171 451
172 Please note that the current coroutine will *not* be put into the 452 Please note that the current coro will *not* be put into the ready
173 ready queue, so calling this function usually means you will never 453 queue, so calling this function usually means you will never be
174 be called again unless something else (e.g. an event handler) calls 454 called again unless something else (e.g. an event handler) calls
175 "->ready", thus waking you up. 455 "->ready", thus waking you up.
176 456
177 This makes "schedule" *the* generic method to use to block the 457 This makes "schedule" *the* generic method to use to block the
178 current coroutine and wait for events: first you remember the 458 current coro and wait for events: first you remember the current
179 current coroutine in a variable, then arrange for some callback of 459 coro in a variable, then arrange for some callback of yours to call
180 yours to call "->ready" on that once some event happens, and last 460 "->ready" on that once some event happens, and last you call
181 you call "schedule" to put yourself to sleep. Note that a lot of 461 "schedule" to put yourself to sleep. Note that a lot of things can
182 things can wake your coroutine up, so you need to check wether the 462 wake your coro up, so you need to check whether the event indeed
183 event indeed happened, e.g. by storing the status in a variable. 463 happened, e.g. by storing the status in a variable.
184 464
185 The canonical way to wait on external events is this: 465 See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for
186 466 callbacks.
187 {
188 # remember current coroutine
189 my $current = $Coro::current;
190
191 # register a hypothetical event handler
192 on_event_invoke sub {
193 # wake up sleeping coroutine
194 $current->ready;
195 undef $current;
196 };
197
198 # call schedule until event occurred.
199 # in case we are woken up for other reasons
200 # (current still defined), loop.
201 Coro::schedule while $current;
202 }
203 467
204 cede 468 cede
205 "Cede" to other coroutines. This function puts the current coroutine 469 "Cede" to other coros. This function puts the current coro into the
206 into the ready queue and calls "schedule", which has the effect of 470 ready queue and calls "schedule", which has the effect of giving up
207 giving up the current "timeslice" to other coroutines of the same or 471 the current "timeslice" to other coros of the same or higher
208 higher priority. Once your coroutine gets its turn again it will 472 priority. Once your coro gets its turn again it will automatically
209 automatically be resumed. 473 be resumed.
210 474
211 This function is often called "yield" in other languages. 475 This function is often called "yield" in other languages.
212 476
213 Coro::cede_notself 477 Coro::cede_notself
214 Works like cede, but is not exported by default and will cede to 478 Works like cede, but is not exported by default and will cede to
215 *any* coroutine, regardless of priority. This is useful sometimes to 479 *any* coro, regardless of priority. This is useful sometimes to
216 ensure progress is made. 480 ensure progress is made.
217 481
218 terminate [arg...] 482 terminate [arg...]
219 Terminates the current coroutine with the given status values (see 483 Terminates the current coro with the given status values (see
220 cancel). 484 cancel). The values will not be copied, but referenced directly.
485
486 Coro::on_enter BLOCK, Coro::on_leave BLOCK
487 These function install enter and leave winders in the current scope.
488 The enter block will be executed when on_enter is called and
489 whenever the current coro is re-entered by the scheduler, while the
490 leave block is executed whenever the current coro is blocked by the
491 scheduler, and also when the containing scope is exited (by whatever
492 means, be it exit, die, last etc.).
493
494 *Neither invoking the scheduler, nor exceptions, are allowed within
495 those BLOCKs*. That means: do not even think about calling "die"
496 without an eval, and do not even think of entering the scheduler in
497 any way.
498
499 Since both BLOCKs are tied to the current scope, they will
500 automatically be removed when the current scope exits.
501
502 These functions implement the same concept as "dynamic-wind" in
503 scheme does, and are useful when you want to localise some resource
504 to a specific coro.
505
506 They slow down thread switching considerably for coros that use them
507 (about 40% for a BLOCK with a single assignment, so thread switching
508 is still reasonably fast if the handlers are fast).
509
510 These functions are best understood by an example: The following
511 function will change the current timezone to
512 "Antarctica/South_Pole", which requires a call to "tzset", but by
513 using "on_enter" and "on_leave", which remember/change the current
514 timezone and restore the previous value, respectively, the timezone
515 is only changed for the coro that installed those handlers.
516
517 use POSIX qw(tzset);
518
519 async {
520 my $old_tz; # store outside TZ value here
521
522 Coro::on_enter {
523 $old_tz = $ENV{TZ}; # remember the old value
524
525 $ENV{TZ} = "Antarctica/South_Pole";
526 tzset; # enable new value
527 };
528
529 Coro::on_leave {
530 $ENV{TZ} = $old_tz;
531 tzset; # restore old value
532 };
533
534 # at this place, the timezone is Antarctica/South_Pole,
535 # without disturbing the TZ of any other coro.
536 };
537
538 This can be used to localise about any resource (locale, uid,
539 current working directory etc.) to a block, despite the existence of
540 other coros.
541
542 Another interesting example implements time-sliced multitasking
543 using interval timers (this could obviously be optimised, but does
544 the job):
545
546 # "timeslice" the given block
547 sub timeslice(&) {
548 use Time::HiRes ();
549
550 Coro::on_enter {
551 # on entering the thread, we set an VTALRM handler to cede
552 $SIG{VTALRM} = sub { cede };
553 # and then start the interval timer
554 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
555 };
556 Coro::on_leave {
557 # on leaving the thread, we stop the interval timer again
558 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
559 };
560
561 &{+shift};
562 }
563
564 # use like this:
565 timeslice {
566 # The following is an endless loop that would normally
567 # monopolise the process. Since it runs in a timesliced
568 # environment, it will regularly cede to other threads.
569 while () { }
570 };
221 571
222 killall 572 killall
223 Kills/terminates/cancels all coroutines except the currently running 573 Kills/terminates/cancels all coros except the currently running one.
224 one. This is useful after a fork, either in the child or the parent,
225 as usually only one of them should inherit the running coroutines.
226 574
227 Note that while this will try to free some of the main programs 575 Note that while this will try to free some of the main interpreter
228 resources, you cnanot free all of them, so if a coroutine that is 576 resources if the calling coro isn't the main coro, but one cannot
229 not the main program calls this function, there will be some 577 free all of them, so if a coro that is not the main coro calls this
230 one-time resource leak. 578 function, there will be some one-time resource leak.
231 579
232 COROUTINE METHODS 580CORO OBJECT METHODS
233 These are the methods you can call on coroutine objects (or to create 581 These are the methods you can call on coro objects (or to create them).
234 them).
235 582
236 new Coro \&sub [, @args...] 583 new Coro \&sub [, @args...]
237 Create a new coroutine and return it. When the sub returns, the 584 Create a new coro and return it. When the sub returns, the coro
238 coroutine automatically terminates as if "terminate" with the 585 automatically terminates as if "terminate" with the returned values
239 returned values were called. To make the coroutine run you must 586 were called. To make the coro run you must first put it into the
240 first put it into the ready queue by calling the ready method. 587 ready queue by calling the ready method.
241 588
242 See "async" and "Coro::State::new" for additional info about the 589 See "async" and "Coro::State::new" for additional info about the
243 coroutine environment. 590 coro environment.
244 591
245 $success = $coroutine->ready 592 $success = $coro->ready
246 Put the given coroutine into the end of its ready queue (there is 593 Put the given coro into the end of its ready queue (there is one
247 one queue for each priority) and return true. If the coroutine is 594 queue for each priority) and return true. If the coro is already in
248 already in the ready queue, do nothing and return false. 595 the ready queue, do nothing and return false.
249 596
250 This ensures that the scheduler will resume this coroutine 597 This ensures that the scheduler will resume this coro automatically
251 automatically once all the coroutines of higher priority and all 598 once all the coro of higher priority and all coro of the same
252 coroutines of the same priority that were put into the ready queue 599 priority that were put into the ready queue earlier have been
253 earlier have been resumed. 600 resumed.
254 601
602 $coro->suspend
603 Suspends the specified coro. A suspended coro works just like any
604 other coro, except that the scheduler will not select a suspended
605 coro for execution.
606
607 Suspending a coro can be useful when you want to keep the coro from
608 running, but you don't want to destroy it, or when you want to
609 temporarily freeze a coro (e.g. for debugging) to resume it later.
610
611 A scenario for the former would be to suspend all (other) coros
612 after a fork and keep them alive, so their destructors aren't
613 called, but new coros can be created.
614
615 $coro->resume
616 If the specified coro was suspended, it will be resumed. Note that
617 when the coro was in the ready queue when it was suspended, it might
618 have been unreadied by the scheduler, so an activation might have
619 been lost.
620
621 To avoid this, it is best to put a suspended coro into the ready
622 queue unconditionally, as every synchronisation mechanism must
623 protect itself against spurious wakeups, and the one in the Coro
624 family certainly do that.
625
626 $state->is_new
627 Returns true iff this Coro object is "new", i.e. has never been run
628 yet. Those states basically consist of only the code reference to
629 call and the arguments, but consumes very little other resources.
630 New states will automatically get assigned a perl interpreter when
631 they are transferred to.
632
633 $state->is_zombie
634 Returns true iff the Coro object has been cancelled, i.e. it's
635 resources freed because they were "cancel"'ed, "terminate"'d,
636 "safe_cancel"'ed or simply went out of scope.
637
638 The name "zombie" stems from UNIX culture, where a process that has
639 exited and only stores and exit status and no other resources is
640 called a "zombie".
641
255 $is_ready = $coroutine->is_ready 642 $is_ready = $coro->is_ready
256 Return wether the coroutine is currently the ready queue or not, 643 Returns true iff the Coro object is in the ready queue. Unless the
644 Coro object gets destroyed, it will eventually be scheduled by the
645 scheduler.
257 646
647 $is_running = $coro->is_running
648 Returns true iff the Coro object is currently running. Only one Coro
649 object can ever be in the running state (but it currently is
650 possible to have multiple running Coro::States).
651
652 $is_suspended = $coro->is_suspended
653 Returns true iff this Coro object has been suspended. Suspended
654 Coros will not ever be scheduled.
655
258 $coroutine->cancel (arg...) 656 $coro->cancel (arg...)
259 Terminates the given coroutine and makes it return the given 657 Terminates the given Coro thread and makes it return the given
260 arguments as status (default: the empty list). Never returns if the 658 arguments as status (default: an empty list). Never returns if the
261 coroutine is the current coroutine. 659 Coro is the current Coro.
262 660
263 $coroutine->join 661 This is a rather brutal way to free a coro, with some limitations -
264 Wait until the coroutine terminates and return any values given to 662 if the thread is inside a C callback that doesn't expect to be
265 the "terminate" or "cancel" functions. "join" can be called 663 canceled, bad things can happen, or if the cancelled thread insists
266 concurrently from multiple coroutines, and all will be resumed and 664 on running complicated cleanup handlers that rely on its thread
267 given the status return once the $coroutine terminates. 665 context, things will not work.
268 666
269 $coroutine->on_destroy (\&cb) 667 Any cleanup code being run (e.g. from "guard" blocks, destructors
270 Registers a callback that is called when this coroutine gets 668 and so on) will be run without a thread context, and is not allowed
271 destroyed, but before it is joined. The callback gets passed the 669 to switch to other threads. A common mistake is to call "->cancel"
272 terminate arguments, if any, and *must not* die, under any 670 from a destructor called by die'ing inside the thread to be
273 circumstances. 671 cancelled for example.
274 672
275 $oldprio = $coroutine->prio ($newprio) 673 On the plus side, "->cancel" will always clean up the thread, no
276 Sets (or gets, if the argument is missing) the priority of the 674 matter what. If your cleanup code is complex or you want to avoid
277 coroutine. Higher priority coroutines get run before lower priority 675 cancelling a C-thread that doesn't know how to clean up itself, it
278 coroutines. Priorities are small signed integers (currently -4 .. 676 can be better to "->throw" an exception, or use "->safe_cancel".
279 +3), that you can refer to using PRIO_xxx constants (use the import
280 tag :prio to get then):
281 677
282 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN 678 The arguments to "->cancel" are not copied, but instead will be
283 3 > 1 > 0 > -1 > -3 > -4 679 referenced directly (e.g. if you pass $var and after the call change
680 that variable, then you might change the return values passed to
681 e.g. "join", so don't do that).
284 682
285 # set priority to HIGH 683 The resources of the Coro are usually freed (or destructed) before
286 current->prio(PRIO_HIGH); 684 this call returns, but this can be delayed for an indefinite amount
685 of time, as in some cases the manager thread has to run first to
686 actually destruct the Coro object.
287 687
288 The idle coroutine ($Coro::idle) always has a lower priority than 688 $coro->safe_cancel ($arg...)
289 any existing coroutine. 689 Works mostly like "->cancel", but is inherently "safer", and
690 consequently, can fail with an exception in cases the thread is not
691 in a cancellable state. Essentially, "->safe_cancel" is a "->cancel"
692 with extra checks before canceling.
290 693
291 Changing the priority of the current coroutine will take effect 694 It works a bit like throwing an exception that cannot be caught -
292 immediately, but changing the priority of coroutines in the ready 695 specifically, it will clean up the thread from within itself, so all
293 queue (but not running) will only take effect after the next 696 cleanup handlers (e.g. "guard" blocks) are run with full thread
294 schedule (of that coroutine). This is a bug that will be fixed in 697 context and can block if they wish. The downside is that there is no
295 some future version. 698 guarantee that the thread can be cancelled when you call this
699 method, and therefore, it might fail. It is also considerably slower
700 than "cancel" or "terminate".
296 701
297 $newprio = $coroutine->nice ($change) 702 A thread is in a safe-cancellable state if it either hasn't been run
298 Similar to "prio", but subtract the given value from the priority 703 yet, or it has no C context attached and is inside an SLF function.
299 (i.e. higher values mean lower priority, just as in unix).
300 704
301 $olddesc = $coroutine->desc ($newdesc) 705 The latter two basically mean that the thread isn't currently inside
302 Sets (or gets in case the argument is missing) the description for 706 a perl callback called from some C function (usually via some XS
303 this coroutine. This is just a free-form string you can associate 707 modules) and isn't currently executing inside some C function itself
304 with a coroutine. 708 (via Coro's XS API).
305 709
306 This method simply sets the "$coroutine->{desc}" member to the given 710 This call returns true when it could cancel the thread, or croaks
307 string. You can modify this member directly if you wish. 711 with an error otherwise (i.e. it either returns true or doesn't
712 return at all).
308 713
714 Why the weird interface? Well, there are two common models on how
715 and when to cancel things. In the first, you have the expectation
716 that your coro thread can be cancelled when you want to cancel it -
717 if the thread isn't cancellable, this would be a bug somewhere, so
718 "->safe_cancel" croaks to notify of the bug.
719
720 In the second model you sometimes want to ask nicely to cancel a
721 thread, but if it's not a good time, well, then don't cancel. This
722 can be done relatively easy like this:
723
724 if (! eval { $coro->safe_cancel }) {
725 warn "unable to cancel thread: $@";
726 }
727
728 However, what you never should do is first try to cancel "safely"
729 and if that fails, cancel the "hard" way with "->cancel". That makes
730 no sense: either you rely on being able to execute cleanup code in
731 your thread context, or you don't. If you do, then "->safe_cancel"
732 is the only way, and if you don't, then "->cancel" is always faster
733 and more direct.
734
735 $coro->schedule_to
736 Puts the current coro to sleep (like "Coro::schedule"), but instead
737 of continuing with the next coro from the ready queue, always switch
738 to the given coro object (regardless of priority etc.). The
739 readyness state of that coro isn't changed.
740
741 This is an advanced method for special cases - I'd love to hear
742 about any uses for this one.
743
744 $coro->cede_to
745 Like "schedule_to", but puts the current coro into the ready queue.
746 This has the effect of temporarily switching to the given coro, and
747 continuing some time later.
748
749 This is an advanced method for special cases - I'd love to hear
750 about any uses for this one.
751
309 $coroutine->throw ([$scalar]) 752 $coro->throw ([$scalar])
310 If $throw is specified and defined, it will be thrown as an 753 If $throw is specified and defined, it will be thrown as an
311 exception inside the coroutine at the next convinient point in time 754 exception inside the coro at the next convenient point in time.
312 (usually after it gains control at the next schedule/transfer/cede).
313 Otherwise clears the exception object. 755 Otherwise clears the exception object.
756
757 Coro will check for the exception each time a schedule-like-function
758 returns, i.e. after each "schedule", "cede",
759 "Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most of
760 those functions (all that are part of Coro itself) detect this case
761 and return early in case an exception is pending.
314 762
315 The exception object will be thrown "as is" with the specified 763 The exception object will be thrown "as is" with the specified
316 scalar in $@, i.e. if it is a string, no line number or newline will 764 scalar in $@, i.e. if it is a string, no line number or newline will
317 be appended (unlike with "die"). 765 be appended (unlike with "die").
318 766
319 This can be used as a softer means than "cancel" to ask a coroutine 767 This can be used as a softer means than either "cancel" or
320 to end itself, although there is no guarentee that the exception 768 "safe_cancel "to ask a coro to end itself, although there is no
321 will lead to termination, and if the exception isn't caught it might 769 guarantee that the exception will lead to termination, and if the
322 well end the whole program. 770 exception isn't caught it might well end the whole program.
323 771
772 You might also think of "throw" as being the moral equivalent of
773 "kill"ing a coro with a signal (in this case, a scalar).
774
775 $coro->join
776 Wait until the coro terminates and return any values given to the
777 "terminate" or "cancel" functions. "join" can be called concurrently
778 from multiple threads, and all will be resumed and given the status
779 return once the $coro terminates.
780
781 $coro->on_destroy (\&cb)
782 Registers a callback that is called when this coro thread gets
783 destroyed, that is, after it's resources have been freed but before
784 it is joined. The callback gets passed the terminate/cancel
785 arguments, if any, and *must not* die, under any circumstances.
786
787 There can be any number of "on_destroy" callbacks per coro, and
788 there is currently no way to remove a callback once added.
789
790 $oldprio = $coro->prio ($newprio)
791 Sets (or gets, if the argument is missing) the priority of the coro
792 thread. Higher priority coro get run before lower priority coros.
793 Priorities are small signed integers (currently -4 .. +3), that you
794 can refer to using PRIO_xxx constants (use the import tag :prio to
795 get then):
796
797 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
798 3 > 1 > 0 > -1 > -3 > -4
799
800 # set priority to HIGH
801 current->prio (PRIO_HIGH);
802
803 The idle coro thread ($Coro::idle) always has a lower priority than
804 any existing coro.
805
806 Changing the priority of the current coro will take effect
807 immediately, but changing the priority of a coro in the ready queue
808 (but not running) will only take effect after the next schedule (of
809 that coro). This is a bug that will be fixed in some future version.
810
811 $newprio = $coro->nice ($change)
812 Similar to "prio", but subtract the given value from the priority
813 (i.e. higher values mean lower priority, just as in UNIX's nice
814 command).
815
816 $olddesc = $coro->desc ($newdesc)
817 Sets (or gets in case the argument is missing) the description for
818 this coro thread. This is just a free-form string you can associate
819 with a coro.
820
821 This method simply sets the "$coro->{desc}" member to the given
822 string. You can modify this member directly if you wish, and in
823 fact, this is often preferred to indicate major processing states
824 that can then be seen for example in a Coro::Debug session:
825
826 sub my_long_function {
827 local $Coro::current->{desc} = "now in my_long_function";
828 ...
829 $Coro::current->{desc} = "my_long_function: phase 1";
830 ...
831 $Coro::current->{desc} = "my_long_function: phase 2";
832 ...
833 }
834
324 GLOBAL FUNCTIONS 835GLOBAL FUNCTIONS
325 Coro::nready 836 Coro::nready
326 Returns the number of coroutines that are currently in the ready 837 Returns the number of coro that are currently in the ready state,
327 state, i.e. that can be switched to by calling "schedule" directory 838 i.e. that can be switched to by calling "schedule" directory or
328 or indirectly. The value 0 means that the only runnable coroutine is 839 indirectly. The value 0 means that the only runnable coro is the
329 the currently running one, so "cede" would have no effect, and 840 currently running one, so "cede" would have no effect, and
330 "schedule" would cause a deadlock unless there is an idle handler 841 "schedule" would cause a deadlock unless there is an idle handler
331 that wakes up some coroutines. 842 that wakes up some coro.
332 843
333 my $guard = Coro::guard { ... } 844 my $guard = Coro::guard { ... }
334 This creates and returns a guard object. Nothing happens until the 845 This function still exists, but is deprecated. Please use the
335 object gets destroyed, in which case the codeblock given as argument 846 "Guard::guard" function instead.
336 will be executed. This is useful to free locks or other resources in
337 case of a runtime error or when the coroutine gets canceled, as in
338 both cases the guard block will be executed. The guard object
339 supports only one method, "->cancel", which will keep the codeblock
340 from being executed.
341
342 Example: set some flag and clear it again when the coroutine gets
343 canceled or the function returns:
344
345 sub do_something {
346 my $guard = Coro::guard { $busy = 0 };
347 $busy = 1;
348
349 # do something that requires $busy to be true
350 }
351 847
352 unblock_sub { ... } 848 unblock_sub { ... }
353 This utility function takes a BLOCK or code reference and "unblocks" 849 This utility function takes a BLOCK or code reference and "unblocks"
354 it, returning a new coderef. Unblocking means that calling the new 850 it, returning a new coderef. Unblocking means that calling the new
355 coderef will return immediately without blocking, returning nothing, 851 coderef will return immediately without blocking, returning nothing,
356 while the original code ref will be called (with parameters) from 852 while the original code ref will be called (with parameters) from
357 within another coroutine. 853 within another coro.
358 854
359 The reason this function exists is that many event libraries (such 855 The reason this function exists is that many event libraries (such
360 as the venerable Event module) are not coroutine-safe (a weaker form 856 as the venerable Event module) are not thread-safe (a weaker form of
361 of thread-safety). This means you must not block within event 857 reentrancy). This means you must not block within event callbacks,
362 callbacks, otherwise you might suffer from crashes or worse. The 858 otherwise you might suffer from crashes or worse. The only event
363 only event library currently known that is safe to use without 859 library currently known that is safe to use without "unblock_sub" is
364 "unblock_sub" is EV. 860 EV (but you might still run into deadlocks if all event loops are
861 blocked).
862
863 Coro will try to catch you when you block in the event loop ("FATAL:
864 $Coro::idle blocked itself"), but this is just best effort and only
865 works when you do not run your own event loop.
365 866
366 This function allows your callbacks to block by executing them in 867 This function allows your callbacks to block by executing them in
367 another coroutine where it is safe to block. One example where 868 another coro where it is safe to block. One example where blocking
368 blocking is handy is when you use the Coro::AIO functions to save 869 is handy is when you use the Coro::AIO functions to save results to
369 results to disk, for example. 870 disk, for example.
370 871
371 In short: simply use "unblock_sub { ... }" instead of "sub { ... }" 872 In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
372 when creating event callbacks that want to block. 873 when creating event callbacks that want to block.
373 874
374 If your handler does not plan to block (e.g. simply sends a message 875 If your handler does not plan to block (e.g. simply sends a message
375 to another coroutine, or puts some other coroutine into the ready 876 to another coro, or puts some other coro into the ready queue),
376 queue), there is no reason to use "unblock_sub". 877 there is no reason to use "unblock_sub".
377 878
378 Note that you also need to use "unblock_sub" for any other callbacks 879 Note that you also need to use "unblock_sub" for any other callbacks
379 that are indirectly executed by any C-based event loop. For example, 880 that are indirectly executed by any C-based event loop. For example,
380 when you use a module that uses AnyEvent (and you use 881 when you use a module that uses AnyEvent (and you use
381 Coro::AnyEvent) and it provides callbacks that are the result of 882 Coro::AnyEvent) and it provides callbacks that are the result of
382 some event callback, then you must not block either, or use 883 some event callback, then you must not block either, or use
383 "unblock_sub". 884 "unblock_sub".
384 885
886 $cb = rouse_cb
887 Create and return a "rouse callback". That's a code reference that,
888 when called, will remember a copy of its arguments and notify the
889 owner coro of the callback.
890
891 See the next function.
892
893 @args = rouse_wait [$cb]
894 Wait for the specified rouse callback (or the last one that was
895 created in this coro).
896
897 As soon as the callback is invoked (or when the callback was invoked
898 before "rouse_wait"), it will return the arguments originally passed
899 to the rouse callback. In scalar context, that means you get the
900 *last* argument, just as if "rouse_wait" had a "return ($a1, $a2,
901 $a3...)" statement at the end.
902
903 See the section HOW TO WAIT FOR A CALLBACK for an actual usage
904 example.
905
906HOW TO WAIT FOR A CALLBACK
907 It is very common for a coro to wait for some callback to be called.
908 This occurs naturally when you use coro in an otherwise event-based
909 program, or when you use event-based libraries.
910
911 These typically register a callback for some event, and call that
912 callback when the event occurred. In a coro, however, you typically want
913 to just wait for the event, simplyifying things.
914
915 For example "AnyEvent->child" registers a callback to be called when a
916 specific child has exited:
917
918 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
919
920 But from within a coro, you often just want to write this:
921
922 my $status = wait_for_child $pid;
923
924 Coro offers two functions specifically designed to make this easy,
925 "rouse_cb" and "rouse_wait".
926
927 The first function, "rouse_cb", generates and returns a callback that,
928 when invoked, will save its arguments and notify the coro that created
929 the callback.
930
931 The second function, "rouse_wait", waits for the callback to be called
932 (by calling "schedule" to go to sleep) and returns the arguments
933 originally passed to the callback.
934
935 Using these functions, it becomes easy to write the "wait_for_child"
936 function mentioned above:
937
938 sub wait_for_child($) {
939 my ($pid) = @_;
940
941 my $watcher = AnyEvent->child (pid => $pid, cb => rouse_cb);
942
943 my ($rpid, $rstatus) = rouse_wait;
944 $rstatus
945 }
946
947 In the case where "rouse_cb" and "rouse_wait" are not flexible enough,
948 you can roll your own, using "schedule" and "ready":
949
950 sub wait_for_child($) {
951 my ($pid) = @_;
952
953 # store the current coro in $current,
954 # and provide result variables for the closure passed to ->child
955 my $current = $Coro::current;
956 my ($done, $rstatus);
957
958 # pass a closure to ->child
959 my $watcher = AnyEvent->child (pid => $pid, cb => sub {
960 $rstatus = $_[1]; # remember rstatus
961 $done = 1; # mark $rstatus as valid
962 $current->ready; # wake up the waiting thread
963 });
964
965 # wait until the closure has been called
966 schedule while !$done;
967
968 $rstatus
969 }
970
385BUGS/LIMITATIONS 971BUGS/LIMITATIONS
972 fork with pthread backend
973 When Coro is compiled using the pthread backend (which isn't
974 recommended but required on many BSDs as their libcs are completely
975 broken), then coro will not survive a fork. There is no known
976 workaround except to fix your libc and use a saner backend.
977
978 perl process emulation ("threads")
386 This module is not perl-pseudo-thread-safe. You should only ever use 979 This module is not perl-pseudo-thread-safe. You should only ever use
387 this module from the same thread (this requirement might be removed in 980 this module from the first thread (this requirement might be removed
388 the future to allow per-thread schedulers, but Coro::State does not yet 981 in the future to allow per-thread schedulers, but Coro::State does
389 allow this). I recommend disabling thread support and using processes, 982 not yet allow this). I recommend disabling thread support and using
390 as this is much faster and uses less memory. 983 processes, as having the windows process emulation enabled under
984 unix roughly halves perl performance, even when not used.
985
986 Attempts to use threads created in another emulated process will
987 crash ("cleanly", with a null pointer exception).
988
989 coro switching is not signal safe
990 You must not switch to another coro from within a signal handler
991 (only relevant with %SIG - most event libraries provide safe
992 signals), *unless* you are sure you are not interrupting a Coro
993 function.
994
995 That means you *MUST NOT* call any function that might "block" the
996 current coro - "cede", "schedule" "Coro::Semaphore->down" or
997 anything that calls those. Everything else, including calling
998 "ready", works.
999
1000WINDOWS PROCESS EMULATION
1001 A great many people seem to be confused about ithreads (for example,
1002 Chip Salzenberg called me unintelligent, incapable, stupid and gullible,
1003 while in the same mail making rather confused statements about perl
1004 ithreads (for example, that memory or files would be shared), showing
1005 his lack of understanding of this area - if it is hard to understand for
1006 Chip, it is probably not obvious to everybody).
1007
1008 What follows is an ultra-condensed version of my talk about threads in
1009 scripting languages given on the perl workshop 2009:
1010
1011 The so-called "ithreads" were originally implemented for two reasons:
1012 first, to (badly) emulate unix processes on native win32 perls, and
1013 secondly, to replace the older, real thread model ("5.005-threads").
1014
1015 It does that by using threads instead of OS processes. The difference
1016 between processes and threads is that threads share memory (and other
1017 state, such as files) between threads within a single process, while
1018 processes do not share anything (at least not semantically). That means
1019 that modifications done by one thread are seen by others, while
1020 modifications by one process are not seen by other processes.
1021
1022 The "ithreads" work exactly like that: when creating a new ithreads
1023 process, all state is copied (memory is copied physically, files and
1024 code is copied logically). Afterwards, it isolates all modifications. On
1025 UNIX, the same behaviour can be achieved by using operating system
1026 processes, except that UNIX typically uses hardware built into the
1027 system to do this efficiently, while the windows process emulation
1028 emulates this hardware in software (rather efficiently, but of course it
1029 is still much slower than dedicated hardware).
1030
1031 As mentioned before, loading code, modifying code, modifying data
1032 structures and so on is only visible in the ithreads process doing the
1033 modification, not in other ithread processes within the same OS process.
1034
1035 This is why "ithreads" do not implement threads for perl at all, only
1036 processes. What makes it so bad is that on non-windows platforms, you
1037 can actually take advantage of custom hardware for this purpose (as
1038 evidenced by the forks module, which gives you the (i-) threads API,
1039 just much faster).
1040
1041 Sharing data is in the i-threads model is done by transferring data
1042 structures between threads using copying semantics, which is very slow -
1043 shared data simply does not exist. Benchmarks using i-threads which are
1044 communication-intensive show extremely bad behaviour with i-threads (in
1045 fact, so bad that Coro, which cannot take direct advantage of multiple
1046 CPUs, is often orders of magnitude faster because it shares data using
1047 real threads, refer to my talk for details).
1048
1049 As summary, i-threads *use* threads to implement processes, while the
1050 compatible forks module *uses* processes to emulate, uhm, processes.
1051 I-threads slow down every perl program when enabled, and outside of
1052 windows, serve no (or little) practical purpose, but disadvantages every
1053 single-threaded Perl program.
1054
1055 This is the reason that I try to avoid the name "ithreads", as it is
1056 misleading as it implies that it implements some kind of thread model
1057 for perl, and prefer the name "windows process emulation", which
1058 describes the actual use and behaviour of it much better.
391 1059
392SEE ALSO 1060SEE ALSO
393 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event. 1061 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event.
394 1062
395 Debugging: Coro::Debug. 1063 Debugging: Coro::Debug.
396 1064
397 Support/Utility: Coro::Specific, Coro::Util. 1065 Support/Utility: Coro::Specific, Coro::Util.
398 1066
399 Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, 1067 Locking and IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,
400 Coro::SemaphoreSet, Coro::RWLock. 1068 Coro::SemaphoreSet, Coro::RWLock.
401 1069
402 IO/Timers: Coro::Timer, Coro::Handle, Coro::Socket, Coro::AIO. 1070 I/O and Timers: Coro::Timer, Coro::Handle, Coro::Socket, Coro::AIO.
403 1071
404 Compatibility: Coro::LWP, Coro::BDB, Coro::Storable, Coro::Select. 1072 Compatibility with other modules: Coro::LWP (but see also AnyEvent::HTTP
1073 for a better-working alternative), Coro::BDB, Coro::Storable,
1074 Coro::Select.
405 1075
406 XS API: Coro::MakeMaker. 1076 XS API: Coro::MakeMaker.
407 1077
408 Low level Configuration, Coroutine Environment: Coro::State. 1078 Low level Configuration, Thread Environment, Continuations: Coro::State.
409 1079
410AUTHOR 1080AUTHOR/SUPPORT/CONTACT
411 Marc Lehmann <schmorp@schmorp.de> 1081 Marc A. Lehmann <schmorp@schmorp.de>
412 http://home.schmorp.de/ 1082 http://software.schmorp.de/pkg/Coro.html
413 1083

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines