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.26 by root, Sun Oct 4 12:55:21 2009 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's threads are fast, too: disabling the
45 emulation code in your perl and using Coro can easily result in a two to 46 Windows process emulation code in your perl and using Coro can easily
46 four times speed increase for your programs. 47 result in a two to four times speed increase for your programs. A
48 parallel matrix multiplication benchmark runs over 300 times faster on a
49 single core than perl's pseudo-threads on a quad core using all four
50 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
62GLOBAL VARIABLES 67GLOBAL VARIABLES
63 $Coro::main 68 $Coro::main
64 This variable stores the coroutine object that represents the main 69 This variable stores the Coro object that represents the main
65 program. While you cna "ready" it and do most other things you can 70 program. While you cna "ready" it and do most other things you can
66 do to coroutines, it is mainly useful to compare again 71 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 72 see whether you are running in the main program or not.
68 or not.
69 73
70 $Coro::current 74 $Coro::current
71 The coroutine object representing the current coroutine (the last 75 The Coro object representing the current coro (the last coro that
72 coroutine that the Coro scheduler switched to). The initial value is 76 the Coro scheduler switched to). The initial value is $Coro::main
73 $Coro::main (of course). 77 (of course).
74 78
75 This variable is strictly *read-only*. You can take copies of the 79 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 80 value stored in it and use it as any other Coro object, but you must
77 must not otherwise modify the variable itself. 81 not otherwise modify the variable itself.
78 82
79 $Coro::idle 83 $Coro::idle
80 This variable is mainly useful to integrate Coro into event loops. 84 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 85 It is usually better to rely on Coro::AnyEvent or Coro::EV, as this
82 is pretty low-level functionality. 86 is pretty low-level functionality.
83 87
84 This variable stores either a coroutine or a callback. 88 This variable stores a Coro object that is put into the ready queue
89 when there are no other ready threads (without invoking any ready
90 hooks).
85 91
86 If it is a callback, the it is called whenever the scheduler finds 92 The default implementation dies with "FATAL: deadlock detected.",
87 no ready coroutines to run. The default implementation prints 93 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. 94 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 95
95 This hook is overwritten by modules such as "Coro::EV" and 96 This hook is overwritten by modules such as "Coro::EV" and
96 "Coro::AnyEvent" to wait on an external event that hopefully wake up 97 "Coro::AnyEvent" to wait on an external event that hopefully wake up
97 a coroutine so the scheduler can run it. 98 a coro so the scheduler can run it.
98 99
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 100 See Coro::EV or Coro::AnyEvent for examples of using this technique.
106 technique.
107 101
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 102SIMPLE CORO CREATION
113 async { ... } [@args...] 103 async { ... } [@args...]
114 Create a new coroutine and return its coroutine object (usually 104 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 105 coro will be put into the ready queue, so it will start running
116 start running automatically on the next scheduler run. 106 automatically on the next scheduler run.
117 107
118 The first argument is a codeblock/closure that should be executed in 108 The first argument is a codeblock/closure that should be executed in
119 the coroutine. When it returns argument returns the coroutine is 109 the coro. When it returns argument returns the coro is automatically
120 automatically terminated. 110 terminated.
121 111
122 The remaining arguments are passed as arguments to the closure. 112 The remaining arguments are passed as arguments to the closure.
123 113
124 See the "Coro::State::new" constructor for info about the coroutine 114 See the "Coro::State::new" constructor for info about the coro
125 environment in which coroutines are executed. 115 environment in which coro are executed.
126 116
127 Calling "exit" in a coroutine will do the same as calling exit 117 Calling "exit" in a coro will do the same as calling exit outside
128 outside the coroutine. Likewise, when the coroutine dies, the 118 the coro. Likewise, when the coro dies, the program will exit, just
129 program will exit, just as it would in the main program. 119 as it would in the main program.
130 120
131 If you do not want that, you can provide a default "die" handler, or 121 If you do not want that, you can provide a default "die" handler, or
132 simply avoid dieing (by use of "eval"). 122 simply avoid dieing (by use of "eval").
133 123
134 Example: Create a new coroutine that just prints its arguments. 124 Example: Create a new coro that just prints its arguments.
135 125
136 async { 126 async {
137 print "@_\n"; 127 print "@_\n";
138 } 1,2,3,4; 128 } 1,2,3,4;
139 129
140 async_pool { ... } [@args...] 130 async_pool { ... } [@args...]
141 Similar to "async", but uses a coroutine pool, so you should not 131 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 132 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 133 coro that might have executed other code already (which can be good
144 can be good or bad :). 134 or bad :).
145 135
146 On the plus side, this function is about twice as fast as creating 136 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 137 (and destroying) a completely new coro, so if you need a lot of
148 generic coroutines in quick successsion, use "async_pool", not 138 generic coros in quick successsion, use "async_pool", not "async".
149 "async".
150 139
151 The code block is executed in an "eval" context and a warning will 140 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 141 be issued in case of an exception instead of terminating the
153 program, as "async" does. As the coroutine is being reused, stuff 142 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 143 "on_destroy" will not work in the expected way, unless you call
155 terminate or cancel, which somehow defeats the purpose of pooling 144 terminate or cancel, which somehow defeats the purpose of pooling
156 (but is fine in the exceptional case). 145 (but is fine in the exceptional case).
157 146
158 The priority will be reset to 0 after each run, tracing will be 147 The priority will be reset to 0 after each run, tracing will be
159 disabled, the description will be reset and the default output 148 disabled, the description will be reset and the default output
160 filehandle gets restored, so you can change all these. Otherwise the 149 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 150 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 151 per-coro global stuff such as $/ you *must needs* revert that
163 change, which is most simply done by using local as in: "local $/". 152 change, which is most simply done by using local as in: "local $/".
164 153
165 The idle pool size is limited to 8 idle coroutines (this can be 154 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 155 by changing $Coro::POOL_SIZE), but there can be as many non-idle
167 non-idle coros as required. 156 coros as required.
168 157
169 If you are concerned about pooled coroutines growing a lot because a 158 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. 159 single "async_pool" used a lot of stackspace you can e.g.
171 "async_pool { terminate }" once per second or so to slowly replenish 160 "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 161 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 162 grows larger than 32kb (adjustable via $Coro::POOL_RSS) it will also
174 be destroyed. 163 be destroyed.
175 164
176STATIC METHODS 165STATIC METHODS
177 Static methods are actually functions that implicitly operate on the 166 Static methods are actually functions that implicitly operate on the
178 current coroutine. 167 current coro.
179 168
180 schedule 169 schedule
181 Calls the scheduler. The scheduler will find the next coroutine that 170 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 171 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 172 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 173 in its ready queue. If there is no coro ready, it will call the
185 will clal the $Coro::idle hook. 174 $Coro::idle hook.
186 175
187 Please note that the current coroutine will *not* be put into the 176 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 177 queue, so calling this function usually means you will never be
189 be called again unless something else (e.g. an event handler) calls 178 called again unless something else (e.g. an event handler) calls
190 "->ready", thus waking you up. 179 "->ready", thus waking you up.
191 180
192 This makes "schedule" *the* generic method to use to block the 181 This makes "schedule" *the* generic method to use to block the
193 current coroutine and wait for events: first you remember the 182 current coro and wait for events: first you remember the current
194 current coroutine in a variable, then arrange for some callback of 183 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 184 "->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 185 "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 186 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. 187 happened, e.g. by storing the status in a variable.
199 188
200 See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for 189 See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for
201 callbacks. 190 callbacks.
202 191
203 cede 192 cede
204 "Cede" to other coroutines. This function puts the current coroutine 193 "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 194 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 195 the current "timeslice" to other coros of the same or higher
207 higher priority. Once your coroutine gets its turn again it will 196 priority. Once your coro gets its turn again it will automatically
208 automatically be resumed. 197 be resumed.
209 198
210 This function is often called "yield" in other languages. 199 This function is often called "yield" in other languages.
211 200
212 Coro::cede_notself 201 Coro::cede_notself
213 Works like cede, but is not exported by default and will cede to 202 Works like cede, but is not exported by default and will cede to
214 *any* coroutine, regardless of priority. This is useful sometimes to 203 *any* coro, regardless of priority. This is useful sometimes to
215 ensure progress is made. 204 ensure progress is made.
216 205
217 terminate [arg...] 206 terminate [arg...]
218 Terminates the current coroutine with the given status values (see 207 Terminates the current coro with the given status values (see
219 cancel). 208 cancel).
220 209
210 Coro::on_enter BLOCK, Coro::on_leave BLOCK
211 These function install enter and leave winders in the current scope.
212 The enter block will be executed when on_enter is called and
213 whenever the current coro is re-entered by the scheduler, while the
214 leave block is executed whenever the current coro is blocked by the
215 scheduler, and also when the containing scope is exited (by whatever
216 means, be it exit, die, last etc.).
217
218 *Neither invoking the scheduler, nor exceptions, are allowed within
219 those BLOCKs*. That means: do not even think about calling "die"
220 without an eval, and do not even think of entering the scheduler in
221 any way.
222
223 Since both BLOCKs are tied to the current scope, they will
224 automatically be removed when the current scope exits.
225
226 These functions implement the same concept as "dynamic-wind" in
227 scheme does, and are useful when you want to localise some resource
228 to a specific coro.
229
230 They slow down thread switching considerably for coros that use them
231 (about 40% for a BLOCK with a single assignment, so thread switching
232 is still reasonably fast if the handlers are fast).
233
234 These functions are best understood by an example: The following
235 function will change the current timezone to
236 "Antarctica/South_Pole", which requires a call to "tzset", but by
237 using "on_enter" and "on_leave", which remember/change the current
238 timezone and restore the previous value, respectively, the timezone
239 is only changed for the coro that installed those handlers.
240
241 use POSIX qw(tzset);
242
243 async {
244 my $old_tz; # store outside TZ value here
245
246 Coro::on_enter {
247 $old_tz = $ENV{TZ}; # remember the old value
248
249 $ENV{TZ} = "Antarctica/South_Pole";
250 tzset; # enable new value
251 };
252
253 Coro::on_leave {
254 $ENV{TZ} = $old_tz;
255 tzset; # restore old value
256 };
257
258 # at this place, the timezone is Antarctica/South_Pole,
259 # without disturbing the TZ of any other coro.
260 };
261
262 This can be used to localise about any resource (locale, uid,
263 current working directory etc.) to a block, despite the existance of
264 other coros.
265
266 Another interesting example implements time-sliced multitasking
267 using interval timers (this could obviously be optimised, but does
268 the job):
269
270 # "timeslice" the given block
271 sub timeslice(&) {
272 use Time::HiRes ();
273
274 Coro::on_enter {
275 # on entering the thread, we set an VTALRM handler to cede
276 $SIG{VTALRM} = sub { cede };
277 # and then start the interval timer
278 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0.01, 0.01;
279 };
280 Coro::on_leave {
281 # on leaving the thread, we stop the interval timer again
282 Time::HiRes::setitimer &Time::HiRes::ITIMER_VIRTUAL, 0, 0;
283 };
284
285 &{+shift};
286 }
287
288 # use like this:
289 timeslice {
290 # The following is an endless loop that would normally
291 # monopolise the process. Since it runs in a timesliced
292 # environment, it will regularly cede to other threads.
293 while () { }
294 };
295
221 killall 296 killall
222 Kills/terminates/cancels all coroutines except the currently running 297 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 298
226 Note that while this will try to free some of the main programs 299 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 300 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 301 free all of them, so if a coro that is not the main coro calls this
229 one-time resource leak. 302 function, there will be some one-time resource leak.
230 303
231COROUTINE OBJECT METHODS 304CORO OBJECT METHODS
232 These are the methods you can call on coroutine objects (or to create 305 These are the methods you can call on coro objects (or to create them).
233 them).
234 306
235 new Coro \&sub [, @args...] 307 new Coro \&sub [, @args...]
236 Create a new coroutine and return it. When the sub returns, the 308 Create a new coro and return it. When the sub returns, the coro
237 coroutine automatically terminates as if "terminate" with the 309 automatically terminates as if "terminate" with the returned values
238 returned values were called. To make the coroutine run you must 310 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. 311 ready queue by calling the ready method.
240 312
241 See "async" and "Coro::State::new" for additional info about the 313 See "async" and "Coro::State::new" for additional info about the
242 coroutine environment. 314 coro environment.
243 315
244 $success = $coroutine->ready 316 $success = $coro->ready
245 Put the given coroutine into the end of its ready queue (there is 317 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 318 queue for each priority) and return true. If the coro is already in
247 already in the ready queue, do nothing and return false. 319 the ready queue, do nothing and return false.
248 320
249 This ensures that the scheduler will resume this coroutine 321 This ensures that the scheduler will resume this coro automatically
250 automatically once all the coroutines of higher priority and all 322 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 323 priority that were put into the ready queue earlier have been
252 earlier have been resumed. 324 resumed.
253 325
326 $coro->suspend
327 Suspends the specified coro. A suspended coro works just like any
328 other coro, except that the scheduler will not select a suspended
329 coro for execution.
330
331 Suspending a coro can be useful when you want to keep the coro from
332 running, but you don't want to destroy it, or when you want to
333 temporarily freeze a coro (e.g. for debugging) to resume it later.
334
335 A scenario for the former would be to suspend all (other) coros
336 after a fork and keep them alive, so their destructors aren't
337 called, but new coros can be created.
338
339 $coro->resume
340 If the specified coro was suspended, it will be resumed. Note that
341 when the coro was in the ready queue when it was suspended, it might
342 have been unreadied by the scheduler, so an activation might have
343 been lost.
344
345 To avoid this, it is best to put a suspended coro into the ready
346 queue unconditionally, as every synchronisation mechanism must
347 protect itself against spurious wakeups, and the one in the Coro
348 family certainly do that.
349
254 $is_ready = $coroutine->is_ready 350 $is_ready = $coro->is_ready
255 Return whether the coroutine is currently the ready queue or not, 351 Returns true iff the Coro object is in the ready queue. Unless the
352 Coro object gets destroyed, it will eventually be scheduled by the
353 scheduler.
256 354
355 $is_running = $coro->is_running
356 Returns true iff the Coro object is currently running. Only one Coro
357 object can ever be in the running state (but it currently is
358 possible to have multiple running Coro::States).
359
360 $is_suspended = $coro->is_suspended
361 Returns true iff this Coro object has been suspended. Suspended
362 Coros will not ever be scheduled.
363
257 $coroutine->cancel (arg...) 364 $coro->cancel (arg...)
258 Terminates the given coroutine and makes it return the given 365 Terminates the given Coro and makes it return the given arguments as
259 arguments as status (default: the empty list). Never returns if the 366 status (default: the empty list). Never returns if the Coro is the
260 coroutine is the current coroutine. 367 current Coro.
261 368
262 $coroutine->schedule_to 369 $coro->schedule_to
263 Puts the current coroutine to sleep (like "Coro::schedule"), but 370 Puts the current coro to sleep (like "Coro::schedule"), but instead
264 instead of continuing with the next coro from the ready queue, 371 of continuing with the next coro from the ready queue, always switch
265 always switch to the given coroutine object (regardless of priority 372 to the given coro object (regardless of priority etc.). The
266 etc.). The readyness state of that coroutine isn't changed. 373 readyness state of that coro isn't changed.
267 374
268 This is an advanced method for special cases - I'd love to hear 375 This is an advanced method for special cases - I'd love to hear
269 about any uses for this one. 376 about any uses for this one.
270 377
271 $coroutine->cede_to 378 $coro->cede_to
272 Like "schedule_to", but puts the current coroutine into the ready 379 Like "schedule_to", but puts the current coro into the ready queue.
273 queue. This has the effect of temporarily switching to the given 380 This has the effect of temporarily switching to the given coro, and
274 coroutine, and continuing some time later. 381 continuing some time later.
275 382
276 This is an advanced method for special cases - I'd love to hear 383 This is an advanced method for special cases - I'd love to hear
277 about any uses for this one. 384 about any uses for this one.
278 385
279 $coroutine->throw ([$scalar]) 386 $coro->throw ([$scalar])
280 If $throw is specified and defined, it will be thrown as an 387 If $throw is specified and defined, it will be thrown as an
281 exception inside the coroutine at the next convenient point in time. 388 exception inside the coro at the next convenient point in time.
282 Otherwise clears the exception object. 389 Otherwise clears the exception object.
283 390
284 Coro will check for the exception each time a schedule-like-function 391 Coro will check for the exception each time a schedule-like-function
285 returns, i.e. after each "schedule", "cede", 392 returns, i.e. after each "schedule", "cede",
286 "Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most of 393 "Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most of
… …
289 396
290 The exception object will be thrown "as is" with the specified 397 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 398 scalar in $@, i.e. if it is a string, no line number or newline will
292 be appended (unlike with "die"). 399 be appended (unlike with "die").
293 400
294 This can be used as a softer means than "cancel" to ask a coroutine 401 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 402 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 403 lead to termination, and if the exception isn't caught it might well
297 well end the whole program. 404 end the whole program.
298 405
299 You might also think of "throw" as being the moral equivalent of 406 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). 407 "kill"ing a coro with a signal (in this case, a scalar).
301 408
302 $coroutine->join 409 $coro->join
303 Wait until the coroutine terminates and return any values given to 410 Wait until the coro terminates and return any values given to the
304 the "terminate" or "cancel" functions. "join" can be called 411 "terminate" or "cancel" functions. "join" can be called concurrently
305 concurrently from multiple coroutines, and all will be resumed and 412 from multiple coro, and all will be resumed and given the status
306 given the status return once the $coroutine terminates. 413 return once the $coro terminates.
307 414
308 $coroutine->on_destroy (\&cb) 415 $coro->on_destroy (\&cb)
309 Registers a callback that is called when this coroutine gets 416 Registers a callback that is called when this coro gets destroyed,
310 destroyed, but before it is joined. The callback gets passed the 417 but before it is joined. The callback gets passed the terminate
311 terminate arguments, if any, and *must not* die, under any 418 arguments, if any, and *must not* die, under any circumstances.
312 circumstances.
313 419
314 $oldprio = $coroutine->prio ($newprio) 420 $oldprio = $coro->prio ($newprio)
315 Sets (or gets, if the argument is missing) the priority of the 421 Sets (or gets, if the argument is missing) the priority of the coro.
316 coroutine. Higher priority coroutines get run before lower priority 422 Higher priority coro get run before lower priority coro. Priorities
317 coroutines. Priorities are small signed integers (currently -4 .. 423 are small signed integers (currently -4 .. +3), that you can refer
318 +3), that you can refer to using PRIO_xxx constants (use the import 424 to using PRIO_xxx constants (use the import tag :prio to get then):
319 tag :prio to get then):
320 425
321 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN 426 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
322 3 > 1 > 0 > -1 > -3 > -4 427 3 > 1 > 0 > -1 > -3 > -4
323 428
324 # set priority to HIGH 429 # set priority to HIGH
325 current->prio(PRIO_HIGH); 430 current->prio (PRIO_HIGH);
326 431
327 The idle coroutine ($Coro::idle) always has a lower priority than 432 The idle coro ($Coro::idle) always has a lower priority than any
328 any existing coroutine. 433 existing coro.
329 434
330 Changing the priority of the current coroutine will take effect 435 Changing the priority of the current coro will take effect
331 immediately, but changing the priority of coroutines in the ready 436 immediately, but changing the priority of coro in the ready queue
332 queue (but not running) will only take effect after the next 437 (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 438 that coro). This is a bug that will be fixed in some future version.
334 some future version.
335 439
336 $newprio = $coroutine->nice ($change) 440 $newprio = $coro->nice ($change)
337 Similar to "prio", but subtract the given value from the priority 441 Similar to "prio", but subtract the given value from the priority
338 (i.e. higher values mean lower priority, just as in unix). 442 (i.e. higher values mean lower priority, just as in unix).
339 443
340 $olddesc = $coroutine->desc ($newdesc) 444 $olddesc = $coro->desc ($newdesc)
341 Sets (or gets in case the argument is missing) the description for 445 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 446 this coro. This is just a free-form string you can associate with a
343 with a coroutine. 447 coro.
344 448
345 This method simply sets the "$coroutine->{desc}" member to the given 449 This method simply sets the "$coro->{desc}" member to the given
346 string. You can modify this member directly if you wish. 450 string. You can modify this member directly if you wish.
347 451
348GLOBAL FUNCTIONS 452GLOBAL FUNCTIONS
349 Coro::nready 453 Coro::nready
350 Returns the number of coroutines that are currently in the ready 454 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 455 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 456 indirectly. The value 0 means that the only runnable coro is the
353 the currently running one, so "cede" would have no effect, and 457 currently running one, so "cede" would have no effect, and
354 "schedule" would cause a deadlock unless there is an idle handler 458 "schedule" would cause a deadlock unless there is an idle handler
355 that wakes up some coroutines. 459 that wakes up some coro.
356 460
357 my $guard = Coro::guard { ... } 461 my $guard = Coro::guard { ... }
358 This creates and returns a guard object. Nothing happens until the 462 This function still exists, but is deprecated. Please use the
359 object gets destroyed, in which case the codeblock given as argument 463 "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 464
376 unblock_sub { ... } 465 unblock_sub { ... }
377 This utility function takes a BLOCK or code reference and "unblocks" 466 This utility function takes a BLOCK or code reference and "unblocks"
378 it, returning a new coderef. Unblocking means that calling the new 467 it, returning a new coderef. Unblocking means that calling the new
379 coderef will return immediately without blocking, returning nothing, 468 coderef will return immediately without blocking, returning nothing,
380 while the original code ref will be called (with parameters) from 469 while the original code ref will be called (with parameters) from
381 within another coroutine. 470 within another coro.
382 471
383 The reason this function exists is that many event libraries (such 472 The reason this function exists is that many event libraries (such
384 as the venerable Event module) are not coroutine-safe (a weaker form 473 as the venerable Event module) are not thread-safe (a weaker form of
385 of reentrancy). This means you must not block within event 474 reentrancy). This means you must not block within event callbacks,
386 callbacks, otherwise you might suffer from crashes or worse. The 475 otherwise you might suffer from crashes or worse. The only event
387 only event library currently known that is safe to use without 476 library currently known that is safe to use without "unblock_sub" is
388 "unblock_sub" is EV. 477 EV.
389 478
390 This function allows your callbacks to block by executing them in 479 This function allows your callbacks to block by executing them in
391 another coroutine where it is safe to block. One example where 480 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 481 is handy is when you use the Coro::AIO functions to save results to
393 results to disk, for example. 482 disk, for example.
394 483
395 In short: simply use "unblock_sub { ... }" instead of "sub { ... }" 484 In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
396 when creating event callbacks that want to block. 485 when creating event callbacks that want to block.
397 486
398 If your handler does not plan to block (e.g. simply sends a message 487 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 488 to another coro, or puts some other coro into the ready queue),
400 queue), there is no reason to use "unblock_sub". 489 there is no reason to use "unblock_sub".
401 490
402 Note that you also need to use "unblock_sub" for any other callbacks 491 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, 492 that are indirectly executed by any C-based event loop. For example,
404 when you use a module that uses AnyEvent (and you use 493 when you use a module that uses AnyEvent (and you use
405 Coro::AnyEvent) and it provides callbacks that are the result of 494 Coro::AnyEvent) and it provides callbacks that are the result of
406 some event callback, then you must not block either, or use 495 some event callback, then you must not block either, or use
407 "unblock_sub". 496 "unblock_sub".
408 497
409 $cb = Coro::rouse_cb 498 $cb = rouse_cb
410 Create and return a "rouse callback". That's a code reference that, 499 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 500 when called, will remember a copy of its arguments and notify the
412 owner coroutine of the callback. 501 owner coro of the callback.
413 502
414 See the next function. 503 See the next function.
415 504
416 @args = Coro::rouse_wait [$cb] 505 @args = rouse_wait [$cb]
417 Wait for the specified rouse callback (or the last one that was 506 Wait for the specified rouse callback (or the last one that was
418 created in this coroutine). 507 created in this coro).
419 508
420 As soon as the callback is invoked (or when the callback was invoked 509 As soon as the callback is invoked (or when the callback was invoked
421 before "rouse_wait"), it will return the arguments originally passed 510 before "rouse_wait"), it will return the arguments originally passed
422 to the rouse callback. 511 to the rouse callback. In scalar context, that means you get the
512 *last* argument, just as if "rouse_wait" had a "return ($a1, $a2,
513 $a3...)" statement at the end.
423 514
424 See the section HOW TO WAIT FOR A CALLBACK for an actual usage 515 See the section HOW TO WAIT FOR A CALLBACK for an actual usage
425 example. 516 example.
426 517
427HOW TO WAIT FOR A CALLBACK 518HOW TO WAIT FOR A CALLBACK
428 It is very common for a coroutine to wait for some callback to be 519 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 520 This occurs naturally when you use coro in an otherwise event-based
430 event-based program, or when you use event-based libraries. 521 program, or when you use event-based libraries.
431 522
432 These typically register a callback for some event, and call that 523 These typically register a callback for some event, and call that
433 callback when the event occured. In a coroutine, however, you typically 524 callback when the event occured. In a coro, however, you typically want
434 want to just wait for the event, simplyifying things. 525 to just wait for the event, simplyifying things.
435 526
436 For example "AnyEvent->child" registers a callback to be called when a 527 For example "AnyEvent->child" registers a callback to be called when a
437 specific child has exited: 528 specific child has exited:
438 529
439 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... }); 530 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
440 531
441 But from withina coroutine, you often just want to write this: 532 But from within a coro, you often just want to write this:
442 533
443 my $status = wait_for_child $pid; 534 my $status = wait_for_child $pid;
444 535
445 Coro offers two functions specifically designed to make this easy, 536 Coro offers two functions specifically designed to make this easy,
446 "Coro::rouse_cb" and "Coro::rouse_wait". 537 "Coro::rouse_cb" and "Coro::rouse_wait".
447 538
448 The first function, "rouse_cb", generates and returns a callback that, 539 The first function, "rouse_cb", generates and returns a callback that,
449 when invoked, will save its arguments and notify the coroutine that 540 when invoked, will save its arguments and notify the coro that created
450 created the callback. 541 the callback.
451 542
452 The second function, "rouse_wait", waits for the callback to be called 543 The second function, "rouse_wait", waits for the callback to be called
453 (by calling "schedule" to go to sleep) and returns the arguments 544 (by calling "schedule" to go to sleep) and returns the arguments
454 originally passed to the callback. 545 originally passed to the callback.
455 546
… …
469 you can roll your own, using "schedule": 560 you can roll your own, using "schedule":
470 561
471 sub wait_for_child($) { 562 sub wait_for_child($) {
472 my ($pid) = @_; 563 my ($pid) = @_;
473 564
474 # store the current coroutine in $current, 565 # store the current coro in $current,
475 # and provide result variables for the closure passed to ->child 566 # and provide result variables for the closure passed to ->child
476 my $current = $Coro::current; 567 my $current = $Coro::current;
477 my ($done, $rstatus); 568 my ($done, $rstatus);
478 569
479 # pass a closure to ->child 570 # pass a closure to ->child
… …
490 581
491BUGS/LIMITATIONS 582BUGS/LIMITATIONS
492 fork with pthread backend 583 fork with pthread backend
493 When Coro is compiled using the pthread backend (which isn't 584 When Coro is compiled using the pthread backend (which isn't
494 recommended but required on many BSDs as their libcs are completely 585 recommended but required on many BSDs as their libcs are completely
495 broken), then coroutines will not survive a fork. There is no known 586 broken), then coro will not survive a fork. There is no known
496 workaround except to fix your libc and use a saner backend. 587 workaround except to fix your libc and use a saner backend.
497 588
498 perl process emulation ("threads") 589 perl process emulation ("threads")
499 This module is not perl-pseudo-thread-safe. You should only ever use 590 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 591 this module from the first thread (this requirement might be removed
501 in the future to allow per-thread schedulers, but Coro::State does 592 in the future to allow per-thread schedulers, but Coro::State does
502 not yet allow this). I recommend disabling thread support and using 593 not yet allow this). I recommend disabling thread support and using
503 processes, as having the windows process emulation enabled under 594 processes, as having the windows process emulation enabled under
504 unix roughly halves perl performance, even when not used. 595 unix roughly halves perl performance, even when not used.
505 596
506 coroutine switching not signal safe 597 coro switching is not signal safe
507 You must not switch to another coroutine from within a signal 598 You must not switch to another coro from within a signal handler
508 handler (only relevant with %SIG - most event libraries provide safe 599 (only relevant with %SIG - most event libraries provide safe
509 signals). 600 signals).
510 601
511 That means you *MUST NOT* call any function that might "block" the 602 That means you *MUST NOT* call any function that might "block" the
512 current coroutine - "cede", "schedule" "Coro::Semaphore->down" or 603 current coro - "cede", "schedule" "Coro::Semaphore->down" or
513 anything that calls those. Everything else, including calling 604 anything that calls those. Everything else, including calling
514 "ready", works. 605 "ready", works.
606
607WINDOWS PROCESS EMULATION
608 A great many people seem to be confused about ithreads (for example,
609 Chip Salzenberg called me unintelligent, incapable, stupid and gullible,
610 while in the same mail making rather confused statements about perl
611 ithreads (for example, that memory or files would be shared), showing
612 his lack of understanding of this area - if it is hard to understand for
613 Chip, it is probably not obvious to everybody).
614
615 What follows is an ultra-condensed version of my talk about threads in
616 scripting languages given onthe perl workshop 2009:
617
618 The so-called "ithreads" were originally implemented for two reasons:
619 first, to (badly) emulate unix processes on native win32 perls, and
620 secondly, to replace the older, real thread model ("5.005-threads").
621
622 It does that by using threads instead of OS processes. The difference
623 between processes and threads is that threads share memory (and other
624 state, such as files) between threads within a single process, while
625 processes do not share anything (at least not semantically). That means
626 that modifications done by one thread are seen by others, while
627 modifications by one process are not seen by other processes.
628
629 The "ithreads" work exactly like that: when creating a new ithreads
630 process, all state is copied (memory is copied physically, files and
631 code is copied logically). Afterwards, it isolates all modifications. On
632 UNIX, the same behaviour can be achieved by using operating system
633 processes, except that UNIX typically uses hardware built into the
634 system to do this efficiently, while the windows process emulation
635 emulates this hardware in software (rather efficiently, but of course it
636 is still much slower than dedicated hardware).
637
638 As mentioned before, loading code, modifying code, modifying data
639 structures and so on is only visible in the ithreads process doing the
640 modification, not in other ithread processes within the same OS process.
641
642 This is why "ithreads" do not implement threads for perl at all, only
643 processes. What makes it so bad is that on non-windows platforms, you
644 can actually take advantage of custom hardware for this purpose (as
645 evidenced by the forks module, which gives you the (i-) threads API,
646 just much faster).
647
648 Sharing data is in the i-threads model is done by transfering data
649 structures between threads using copying semantics, which is very slow -
650 shared data simply does not exist. Benchmarks using i-threads which are
651 communication-intensive show extremely bad behaviour with i-threads (in
652 fact, so bad that Coro, which cannot take direct advantage of multiple
653 CPUs, is often orders of magnitude faster because it shares data using
654 real threads, refer to my talk for details).
655
656 As summary, i-threads *use* threads to implement processes, while the
657 compatible forks module *uses* processes to emulate, uhm, processes.
658 I-threads slow down every perl program when enabled, and outside of
659 windows, serve no (or little) practical purpose, but disadvantages every
660 single-threaded Perl program.
661
662 This is the reason that I try to avoid the name "ithreads", as it is
663 misleading as it implies that it implements some kind of thread model
664 for perl, and prefer the name "windows process emulation", which
665 describes the actual use and behaviour of it much better.
515 666
516SEE ALSO 667SEE ALSO
517 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event. 668 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event.
518 669
519 Debugging: Coro::Debug. 670 Debugging: Coro::Debug.

Diff Legend

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