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

Comparing Coro/README (file contents):
Revision 1.20 by root, Tue Nov 25 20:48:41 2008 UTC vs.
Revision 1.29 by root, Sat Feb 19 06:51:22 2011 UTC

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

Diff Legend

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