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.21 by root, Mon Dec 15 20:52:04 2008 UTC

… …
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;
… …
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 ported to unix, and as such act
43 full shared address space, which makes communication between threads 43 as processes), Coro provides a full shared address space, which makes
44 very easy. And threads are fast, too: disabling the Windows process 44 communication between threads very easy. And Coro's threads are fast,
45 emulation code in your perl and using Coro can easily result in a two to 45 too: disabling the Windows process emulation code in your perl and using
46 four times speed increase for your programs. 46 Coro can easily result in a two to four times speed increase for your
47 programs. A parallel matrix multiplication benchmark runs over 300 times
48 faster on a single core than perl's pseudo-threads on a quad core using
49 all four cores.
47 50
48 Coro achieves that by supporting multiple running interpreters that 51 Coro achieves that by supporting multiple running interpreters that
49 share data, which is especially useful to code pseudo-parallel processes 52 share data, which is especially useful to code pseudo-parallel processes
50 and for event-based programming, such as multiple HTTP-GET requests 53 and for event-based programming, such as multiple HTTP-GET requests
51 running concurrently. See Coro::AnyEvent to learn more on how to 54 running concurrently. See Coro::AnyEvent to learn more on how to
52 integrate Coro into an event-based environment. 55 integrate Coro into an event-based environment.
53 56
54 In this module, a thread is defined as "callchain + lexical variables + 57 In this module, a thread is defined as "callchain + lexical variables +
55 @_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain, 58 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 59 callchain, its own set of lexicals and its own set of perls most
57 variables (see Coro::State for more configuration and background info). 60 important global variables (see Coro::State for more configuration and
61 background info).
58 62
59 See also the "SEE ALSO" section at the end of this document - the Coro 63 See also the "SEE ALSO" section at the end of this document - the Coro
60 module family is quite large. 64 module family is quite large.
61 65
62GLOBAL VARIABLES 66GLOBAL VARIABLES
63 $Coro::main 67 $Coro::main
64 This variable stores the coroutine object that represents the main 68 This variable stores the Coro object that represents the main
65 program. While you cna "ready" it and do most other things you can 69 program. While you cna "ready" it and do most other things you can
66 do to coroutines, it is mainly useful to compare again 70 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 71 see whether you are running in the main program or not.
68 or not.
69 72
70 $Coro::current 73 $Coro::current
71 The coroutine object representing the current coroutine (the last 74 The Coro object representing the current coro (the last coro that
72 coroutine that the Coro scheduler switched to). The initial value is 75 the Coro scheduler switched to). The initial value is $Coro::main
73 $Coro::main (of course). 76 (of course).
74 77
75 This variable is strictly *read-only*. You can take copies of the 78 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 79 value stored in it and use it as any other Coro object, but you must
77 must not otherwise modify the variable itself. 80 not otherwise modify the variable itself.
78 81
79 $Coro::idle 82 $Coro::idle
80 This variable is mainly useful to integrate Coro into event loops. 83 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 84 It is usually better to rely on Coro::AnyEvent or Coro::EV, as this
82 is pretty low-level functionality. 85 is pretty low-level functionality.
83 86
84 This variable stores either a coroutine or a callback. 87 This variable stores either a Coro object or a callback.
85 88
86 If it is a callback, the it is called whenever the scheduler finds 89 If it is a callback, the it is called whenever the scheduler finds
87 no ready coroutines to run. The default implementation prints 90 no ready coros to run. The default implementation prints "FATAL:
88 "FATAL: deadlock detected" and exits, because the program has no 91 deadlock detected" and exits, because the program has no other way
89 other way to continue. 92 to continue.
90 93
91 If it is a coroutine object, then this object will be readied 94 If it is a coro object, then this object will be readied (without
92 (without invoking any ready hooks, however) when the scheduler finds 95 invoking any ready hooks, however) when the scheduler finds no other
93 no other ready coroutines to run. 96 ready coros to run.
94 97
95 This hook is overwritten by modules such as "Coro::EV" and 98 This hook is overwritten by modules such as "Coro::EV" and
96 "Coro::AnyEvent" to wait on an external event that hopefully wake up 99 "Coro::AnyEvent" to wait on an external event that hopefully wake up
97 a coroutine so the scheduler can run it. 100 a coro so the scheduler can run it.
98 101
99 Note that the callback *must not*, under any circumstances, block 102 Note that the callback *must not*, under any circumstances, block
100 the current coroutine. Normally, this is achieved by having an "idle 103 the current coro. Normally, this is achieved by having an "idle
101 coroutine" that calls the event loop and then blocks again, and then 104 coro" that calls the event loop and then blocks again, and then
102 readying that coroutine in the idle handler, or by simply placing 105 readying that coro in the idle handler, or by simply placing the
103 the idle coroutine in this variable. 106 idle coro in this variable.
104 107
105 See Coro::Event or Coro::AnyEvent for examples of using this 108 See Coro::Event or Coro::AnyEvent for examples of using this
106 technique. 109 technique.
107 110
108 Please note that if your callback recursively invokes perl (e.g. for 111 Please note that if your callback recursively invokes perl (e.g. for
109 event handlers), then it must be prepared to be called recursively 112 event handlers), then it must be prepared to be called recursively
110 itself. 113 itself.
111 114
112SIMPLE COROUTINE CREATION 115SIMPLE CORO CREATION
113 async { ... } [@args...] 116 async { ... } [@args...]
114 Create a new coroutine and return its coroutine object (usually 117 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 118 coro will be put into the ready queue, so it will start running
116 start running automatically on the next scheduler run. 119 automatically on the next scheduler run.
117 120
118 The first argument is a codeblock/closure that should be executed in 121 The first argument is a codeblock/closure that should be executed in
119 the coroutine. When it returns argument returns the coroutine is 122 the coro. When it returns argument returns the coro is automatically
120 automatically terminated. 123 terminated.
121 124
122 The remaining arguments are passed as arguments to the closure. 125 The remaining arguments are passed as arguments to the closure.
123 126
124 See the "Coro::State::new" constructor for info about the coroutine 127 See the "Coro::State::new" constructor for info about the coro
125 environment in which coroutines are executed. 128 environment in which coro are executed.
126 129
127 Calling "exit" in a coroutine will do the same as calling exit 130 Calling "exit" in a coro will do the same as calling exit outside
128 outside the coroutine. Likewise, when the coroutine dies, the 131 the coro. Likewise, when the coro dies, the program will exit, just
129 program will exit, just as it would in the main program. 132 as it would in the main program.
130 133
131 If you do not want that, you can provide a default "die" handler, or 134 If you do not want that, you can provide a default "die" handler, or
132 simply avoid dieing (by use of "eval"). 135 simply avoid dieing (by use of "eval").
133 136
134 Example: Create a new coroutine that just prints its arguments. 137 Example: Create a new coro that just prints its arguments.
135 138
136 async { 139 async {
137 print "@_\n"; 140 print "@_\n";
138 } 1,2,3,4; 141 } 1,2,3,4;
139 142
140 async_pool { ... } [@args...] 143 async_pool { ... } [@args...]
141 Similar to "async", but uses a coroutine pool, so you should not 144 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 145 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 146 coro that might have executed other code already (which can be good
144 can be good or bad :). 147 or bad :).
145 148
146 On the plus side, this function is about twice as fast as creating 149 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 150 (and destroying) a completely new coro, so if you need a lot of
148 generic coroutines in quick successsion, use "async_pool", not 151 generic coros in quick successsion, use "async_pool", not "async".
149 "async".
150 152
151 The code block is executed in an "eval" context and a warning will 153 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 154 be issued in case of an exception instead of terminating the
153 program, as "async" does. As the coroutine is being reused, stuff 155 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 156 "on_destroy" will not work in the expected way, unless you call
155 terminate or cancel, which somehow defeats the purpose of pooling 157 terminate or cancel, which somehow defeats the purpose of pooling
156 (but is fine in the exceptional case). 158 (but is fine in the exceptional case).
157 159
158 The priority will be reset to 0 after each run, tracing will be 160 The priority will be reset to 0 after each run, tracing will be
159 disabled, the description will be reset and the default output 161 disabled, the description will be reset and the default output
160 filehandle gets restored, so you can change all these. Otherwise the 162 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 163 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 164 per-coro global stuff such as $/ you *must needs* revert that
163 change, which is most simply done by using local as in: "local $/". 165 change, which is most simply done by using local as in: "local $/".
164 166
165 The idle pool size is limited to 8 idle coroutines (this can be 167 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 168 by changing $Coro::POOL_SIZE), but there can be as many non-idle
167 non-idle coros as required. 169 coros as required.
168 170
169 If you are concerned about pooled coroutines growing a lot because a 171 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. 172 single "async_pool" used a lot of stackspace you can e.g.
171 "async_pool { terminate }" once per second or so to slowly replenish 173 "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 174 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 175 grows larger than 32kb (adjustable via $Coro::POOL_RSS) it will also
174 be destroyed. 176 be destroyed.
175 177
176STATIC METHODS 178STATIC METHODS
177 Static methods are actually functions that implicitly operate on the 179 Static methods are actually functions that implicitly operate on the
178 current coroutine. 180 current coro.
179 181
180 schedule 182 schedule
181 Calls the scheduler. The scheduler will find the next coroutine that 183 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 184 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 185 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 186 in its ready queue. If there is no coro ready, it will clal the
185 will clal the $Coro::idle hook. 187 $Coro::idle hook.
186 188
187 Please note that the current coroutine will *not* be put into the 189 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 190 queue, so calling this function usually means you will never be
189 be called again unless something else (e.g. an event handler) calls 191 called again unless something else (e.g. an event handler) calls
190 "->ready", thus waking you up. 192 "->ready", thus waking you up.
191 193
192 This makes "schedule" *the* generic method to use to block the 194 This makes "schedule" *the* generic method to use to block the
193 current coroutine and wait for events: first you remember the 195 current coro and wait for events: first you remember the current
194 current coroutine in a variable, then arrange for some callback of 196 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 197 "->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 198 "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 199 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. 200 happened, e.g. by storing the status in a variable.
199 201
200 See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for 202 See HOW TO WAIT FOR A CALLBACK, below, for some ways to wait for
201 callbacks. 203 callbacks.
202 204
203 cede 205 cede
204 "Cede" to other coroutines. This function puts the current coroutine 206 "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 207 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 208 the current "timeslice" to other coros of the same or higher
207 higher priority. Once your coroutine gets its turn again it will 209 priority. Once your coro gets its turn again it will automatically
208 automatically be resumed. 210 be resumed.
209 211
210 This function is often called "yield" in other languages. 212 This function is often called "yield" in other languages.
211 213
212 Coro::cede_notself 214 Coro::cede_notself
213 Works like cede, but is not exported by default and will cede to 215 Works like cede, but is not exported by default and will cede to
214 *any* coroutine, regardless of priority. This is useful sometimes to 216 *any* coro, regardless of priority. This is useful sometimes to
215 ensure progress is made. 217 ensure progress is made.
216 218
217 terminate [arg...] 219 terminate [arg...]
218 Terminates the current coroutine with the given status values (see 220 Terminates the current coro with the given status values (see
219 cancel). 221 cancel).
220 222
223 Coro::on_enter BLOCK, Coro::on_leave BLOCK
224 These function install enter and leave winders in the current scope.
225 The enter block will be executed when on_enter is called and
226 whenever the current coro is re-entered by the scheduler, while the
227 leave block is executed whenever the current coro is blocked by the
228 scheduler, and also when the containing scope is exited (by whatever
229 means, be it exit, die, last etc.).
230
231 *Neither invoking the scheduler, nor exceptions, are allowed within
232 those BLOCKs*. That means: do not even think about calling "die"
233 without an eval, and do not even think of entering the scheduler in
234 any way.
235
236 Since both BLOCKs are tied to the current scope, they will
237 automatically be removed when the current scope exits.
238
239 These functions implement the same concept as "dynamic-wind" in
240 scheme does, and are useful when you want to localise some resource
241 to a specific coro.
242
243 They slow down coro switching considerably for coros that use them
244 (But coro switching is still reasonably fast if the handlers are
245 fast).
246
247 These functions are best understood by an example: The following
248 function will change the current timezone to
249 "Antarctica/South_Pole", which requires a call to "tzset", but by
250 using "on_enter" and "on_leave", which remember/change the current
251 timezone and restore the previous value, respectively, the timezone
252 is only changes for the coro that installed those handlers.
253
254 use POSIX qw(tzset);
255
256 async {
257 my $old_tz; # store outside TZ value here
258
259 Coro::on_enter {
260 $old_tz = $ENV{TZ}; # remember the old value
261
262 $ENV{TZ} = "Antarctica/South_Pole";
263 tzset; # enable new value
264 };
265
266 Coro::on_leave {
267 $ENV{TZ} = $old_tz;
268 tzset; # restore old value
269 };
270
271 # at this place, the timezone is Antarctica/South_Pole,
272 # without disturbing the TZ of any other coro.
273 };
274
275 This can be used to localise about any resource (locale, uid,
276 current working directory etc.) to a block, despite the existance of
277 other coros.
278
221 killall 279 killall
222 Kills/terminates/cancels all coroutines except the currently running 280 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 281
226 Note that while this will try to free some of the main programs 282 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 283 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 284 free all of them, so if a coro that is not the main coro calls this
229 one-time resource leak. 285 function, there will be some one-time resource leak.
230 286
231COROUTINE OBJECT METHODS 287CORO OBJECT METHODS
232 These are the methods you can call on coroutine objects (or to create 288 These are the methods you can call on coro objects (or to create them).
233 them).
234 289
235 new Coro \&sub [, @args...] 290 new Coro \&sub [, @args...]
236 Create a new coroutine and return it. When the sub returns, the 291 Create a new coro and return it. When the sub returns, the coro
237 coroutine automatically terminates as if "terminate" with the 292 automatically terminates as if "terminate" with the returned values
238 returned values were called. To make the coroutine run you must 293 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. 294 ready queue by calling the ready method.
240 295
241 See "async" and "Coro::State::new" for additional info about the 296 See "async" and "Coro::State::new" for additional info about the
242 coroutine environment. 297 coro environment.
243 298
244 $success = $coroutine->ready 299 $success = $coro->ready
245 Put the given coroutine into the end of its ready queue (there is 300 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 301 queue for each priority) and return true. If the coro is already in
247 already in the ready queue, do nothing and return false. 302 the ready queue, do nothing and return false.
248 303
249 This ensures that the scheduler will resume this coroutine 304 This ensures that the scheduler will resume this coro automatically
250 automatically once all the coroutines of higher priority and all 305 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 306 priority that were put into the ready queue earlier have been
252 earlier have been resumed. 307 resumed.
253 308
254 $is_ready = $coroutine->is_ready 309 $is_ready = $coro->is_ready
255 Return whether the coroutine is currently the ready queue or not, 310 Returns true iff the Coro object is in the ready queue. Unless the
311 Coro object gets destroyed, it will eventually be scheduled by the
312 scheduler.
256 313
314 $is_running = $coro->is_running
315 Returns true iff the Coro object is currently running. Only one Coro
316 object can ever be in the running state (but it currently is
317 possible to have multiple running Coro::States).
318
319 $is_suspended = $coro->is_suspended
320 Returns true iff this Coro object has been suspended. Suspended
321 Coros will not ever be scheduled.
322
257 $coroutine->cancel (arg...) 323 $coro->cancel (arg...)
258 Terminates the given coroutine and makes it return the given 324 Terminates the given Coro and makes it return the given arguments as
259 arguments as status (default: the empty list). Never returns if the 325 status (default: the empty list). Never returns if the Coro is the
260 coroutine is the current coroutine. 326 current Coro.
261 327
262 $coroutine->schedule_to 328 $coro->schedule_to
263 Puts the current coroutine to sleep (like "Coro::schedule"), but 329 Puts the current coro to sleep (like "Coro::schedule"), but instead
264 instead of continuing with the next coro from the ready queue, 330 of continuing with the next coro from the ready queue, always switch
265 always switch to the given coroutine object (regardless of priority 331 to the given coro object (regardless of priority etc.). The
266 etc.). The readyness state of that coroutine isn't changed. 332 readyness state of that coro isn't changed.
267 333
268 This is an advanced method for special cases - I'd love to hear 334 This is an advanced method for special cases - I'd love to hear
269 about any uses for this one. 335 about any uses for this one.
270 336
271 $coroutine->cede_to 337 $coro->cede_to
272 Like "schedule_to", but puts the current coroutine into the ready 338 Like "schedule_to", but puts the current coro into the ready queue.
273 queue. This has the effect of temporarily switching to the given 339 This has the effect of temporarily switching to the given coro, and
274 coroutine, and continuing some time later. 340 continuing some time later.
275 341
276 This is an advanced method for special cases - I'd love to hear 342 This is an advanced method for special cases - I'd love to hear
277 about any uses for this one. 343 about any uses for this one.
278 344
279 $coroutine->throw ([$scalar]) 345 $coro->throw ([$scalar])
280 If $throw is specified and defined, it will be thrown as an 346 If $throw is specified and defined, it will be thrown as an
281 exception inside the coroutine at the next convenient point in time. 347 exception inside the coro at the next convenient point in time.
282 Otherwise clears the exception object. 348 Otherwise clears the exception object.
283 349
284 Coro will check for the exception each time a schedule-like-function 350 Coro will check for the exception each time a schedule-like-function
285 returns, i.e. after each "schedule", "cede", 351 returns, i.e. after each "schedule", "cede",
286 "Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most of 352 "Coro::Semaphore->down", "Coro::Handle->readable" and so on. Most of
… …
289 355
290 The exception object will be thrown "as is" with the specified 356 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 357 scalar in $@, i.e. if it is a string, no line number or newline will
292 be appended (unlike with "die"). 358 be appended (unlike with "die").
293 359
294 This can be used as a softer means than "cancel" to ask a coroutine 360 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 361 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 362 lead to termination, and if the exception isn't caught it might well
297 well end the whole program. 363 end the whole program.
298 364
299 You might also think of "throw" as being the moral equivalent of 365 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). 366 "kill"ing a coro with a signal (in this case, a scalar).
301 367
302 $coroutine->join 368 $coro->join
303 Wait until the coroutine terminates and return any values given to 369 Wait until the coro terminates and return any values given to the
304 the "terminate" or "cancel" functions. "join" can be called 370 "terminate" or "cancel" functions. "join" can be called concurrently
305 concurrently from multiple coroutines, and all will be resumed and 371 from multiple coro, and all will be resumed and given the status
306 given the status return once the $coroutine terminates. 372 return once the $coro terminates.
307 373
308 $coroutine->on_destroy (\&cb) 374 $coro->on_destroy (\&cb)
309 Registers a callback that is called when this coroutine gets 375 Registers a callback that is called when this coro gets destroyed,
310 destroyed, but before it is joined. The callback gets passed the 376 but before it is joined. The callback gets passed the terminate
311 terminate arguments, if any, and *must not* die, under any 377 arguments, if any, and *must not* die, under any circumstances.
312 circumstances.
313 378
314 $oldprio = $coroutine->prio ($newprio) 379 $oldprio = $coro->prio ($newprio)
315 Sets (or gets, if the argument is missing) the priority of the 380 Sets (or gets, if the argument is missing) the priority of the coro.
316 coroutine. Higher priority coroutines get run before lower priority 381 Higher priority coro get run before lower priority coro. Priorities
317 coroutines. Priorities are small signed integers (currently -4 .. 382 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 383 to using PRIO_xxx constants (use the import tag :prio to get then):
319 tag :prio to get then):
320 384
321 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN 385 PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
322 3 > 1 > 0 > -1 > -3 > -4 386 3 > 1 > 0 > -1 > -3 > -4
323 387
324 # set priority to HIGH 388 # set priority to HIGH
325 current->prio(PRIO_HIGH); 389 current->prio (PRIO_HIGH);
326 390
327 The idle coroutine ($Coro::idle) always has a lower priority than 391 The idle coro ($Coro::idle) always has a lower priority than any
328 any existing coroutine. 392 existing coro.
329 393
330 Changing the priority of the current coroutine will take effect 394 Changing the priority of the current coro will take effect
331 immediately, but changing the priority of coroutines in the ready 395 immediately, but changing the priority of coro in the ready queue
332 queue (but not running) will only take effect after the next 396 (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 397 that coro). This is a bug that will be fixed in some future version.
334 some future version.
335 398
336 $newprio = $coroutine->nice ($change) 399 $newprio = $coro->nice ($change)
337 Similar to "prio", but subtract the given value from the priority 400 Similar to "prio", but subtract the given value from the priority
338 (i.e. higher values mean lower priority, just as in unix). 401 (i.e. higher values mean lower priority, just as in unix).
339 402
340 $olddesc = $coroutine->desc ($newdesc) 403 $olddesc = $coro->desc ($newdesc)
341 Sets (or gets in case the argument is missing) the description for 404 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 405 this coro. This is just a free-form string you can associate with a
343 with a coroutine. 406 coro.
344 407
345 This method simply sets the "$coroutine->{desc}" member to the given 408 This method simply sets the "$coro->{desc}" member to the given
346 string. You can modify this member directly if you wish. 409 string. You can modify this member directly if you wish.
347 410
348GLOBAL FUNCTIONS 411GLOBAL FUNCTIONS
349 Coro::nready 412 Coro::nready
350 Returns the number of coroutines that are currently in the ready 413 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 414 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 415 indirectly. The value 0 means that the only runnable coro is the
353 the currently running one, so "cede" would have no effect, and 416 currently running one, so "cede" would have no effect, and
354 "schedule" would cause a deadlock unless there is an idle handler 417 "schedule" would cause a deadlock unless there is an idle handler
355 that wakes up some coroutines. 418 that wakes up some coro.
356 419
357 my $guard = Coro::guard { ... } 420 my $guard = Coro::guard { ... }
358 This creates and returns a guard object. Nothing happens until the 421 This function still exists, but is deprecated. Please use the
359 object gets destroyed, in which case the codeblock given as argument 422 "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 423
376 unblock_sub { ... } 424 unblock_sub { ... }
377 This utility function takes a BLOCK or code reference and "unblocks" 425 This utility function takes a BLOCK or code reference and "unblocks"
378 it, returning a new coderef. Unblocking means that calling the new 426 it, returning a new coderef. Unblocking means that calling the new
379 coderef will return immediately without blocking, returning nothing, 427 coderef will return immediately without blocking, returning nothing,
380 while the original code ref will be called (with parameters) from 428 while the original code ref will be called (with parameters) from
381 within another coroutine. 429 within another coro.
382 430
383 The reason this function exists is that many event libraries (such 431 The reason this function exists is that many event libraries (such
384 as the venerable Event module) are not coroutine-safe (a weaker form 432 as the venerable Event module) are not thread-safe (a weaker form of
385 of reentrancy). This means you must not block within event 433 reentrancy). This means you must not block within event callbacks,
386 callbacks, otherwise you might suffer from crashes or worse. The 434 otherwise you might suffer from crashes or worse. The only event
387 only event library currently known that is safe to use without 435 library currently known that is safe to use without "unblock_sub" is
388 "unblock_sub" is EV. 436 EV.
389 437
390 This function allows your callbacks to block by executing them in 438 This function allows your callbacks to block by executing them in
391 another coroutine where it is safe to block. One example where 439 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 440 is handy is when you use the Coro::AIO functions to save results to
393 results to disk, for example. 441 disk, for example.
394 442
395 In short: simply use "unblock_sub { ... }" instead of "sub { ... }" 443 In short: simply use "unblock_sub { ... }" instead of "sub { ... }"
396 when creating event callbacks that want to block. 444 when creating event callbacks that want to block.
397 445
398 If your handler does not plan to block (e.g. simply sends a message 446 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 447 to another coro, or puts some other coro into the ready queue),
400 queue), there is no reason to use "unblock_sub". 448 there is no reason to use "unblock_sub".
401 449
402 Note that you also need to use "unblock_sub" for any other callbacks 450 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, 451 that are indirectly executed by any C-based event loop. For example,
404 when you use a module that uses AnyEvent (and you use 452 when you use a module that uses AnyEvent (and you use
405 Coro::AnyEvent) and it provides callbacks that are the result of 453 Coro::AnyEvent) and it provides callbacks that are the result of
… …
407 "unblock_sub". 455 "unblock_sub".
408 456
409 $cb = Coro::rouse_cb 457 $cb = Coro::rouse_cb
410 Create and return a "rouse callback". That's a code reference that, 458 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 459 when called, will remember a copy of its arguments and notify the
412 owner coroutine of the callback. 460 owner coro of the callback.
413 461
414 See the next function. 462 See the next function.
415 463
416 @args = Coro::rouse_wait [$cb] 464 @args = Coro::rouse_wait [$cb]
417 Wait for the specified rouse callback (or the last one that was 465 Wait for the specified rouse callback (or the last one that was
418 created in this coroutine). 466 created in this coro).
419 467
420 As soon as the callback is invoked (or when the callback was invoked 468 As soon as the callback is invoked (or when the callback was invoked
421 before "rouse_wait"), it will return the arguments originally passed 469 before "rouse_wait"), it will return the arguments originally passed
422 to the rouse callback. 470 to the rouse callback.
423 471
424 See the section HOW TO WAIT FOR A CALLBACK for an actual usage 472 See the section HOW TO WAIT FOR A CALLBACK for an actual usage
425 example. 473 example.
426 474
427HOW TO WAIT FOR A CALLBACK 475HOW TO WAIT FOR A CALLBACK
428 It is very common for a coroutine to wait for some callback to be 476 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 477 This occurs naturally when you use coro in an otherwise event-based
430 event-based program, or when you use event-based libraries. 478 program, or when you use event-based libraries.
431 479
432 These typically register a callback for some event, and call that 480 These typically register a callback for some event, and call that
433 callback when the event occured. In a coroutine, however, you typically 481 callback when the event occured. In a coro, however, you typically want
434 want to just wait for the event, simplyifying things. 482 to just wait for the event, simplyifying things.
435 483
436 For example "AnyEvent->child" registers a callback to be called when a 484 For example "AnyEvent->child" registers a callback to be called when a
437 specific child has exited: 485 specific child has exited:
438 486
439 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... }); 487 my $child_watcher = AnyEvent->child (pid => $pid, cb => sub { ... });
440 488
441 But from withina coroutine, you often just want to write this: 489 But from within a coro, you often just want to write this:
442 490
443 my $status = wait_for_child $pid; 491 my $status = wait_for_child $pid;
444 492
445 Coro offers two functions specifically designed to make this easy, 493 Coro offers two functions specifically designed to make this easy,
446 "Coro::rouse_cb" and "Coro::rouse_wait". 494 "Coro::rouse_cb" and "Coro::rouse_wait".
447 495
448 The first function, "rouse_cb", generates and returns a callback that, 496 The first function, "rouse_cb", generates and returns a callback that,
449 when invoked, will save its arguments and notify the coroutine that 497 when invoked, will save its arguments and notify the coro that created
450 created the callback. 498 the callback.
451 499
452 The second function, "rouse_wait", waits for the callback to be called 500 The second function, "rouse_wait", waits for the callback to be called
453 (by calling "schedule" to go to sleep) and returns the arguments 501 (by calling "schedule" to go to sleep) and returns the arguments
454 originally passed to the callback. 502 originally passed to the callback.
455 503
… …
469 you can roll your own, using "schedule": 517 you can roll your own, using "schedule":
470 518
471 sub wait_for_child($) { 519 sub wait_for_child($) {
472 my ($pid) = @_; 520 my ($pid) = @_;
473 521
474 # store the current coroutine in $current, 522 # store the current coro in $current,
475 # and provide result variables for the closure passed to ->child 523 # and provide result variables for the closure passed to ->child
476 my $current = $Coro::current; 524 my $current = $Coro::current;
477 my ($done, $rstatus); 525 my ($done, $rstatus);
478 526
479 # pass a closure to ->child 527 # pass a closure to ->child
… …
490 538
491BUGS/LIMITATIONS 539BUGS/LIMITATIONS
492 fork with pthread backend 540 fork with pthread backend
493 When Coro is compiled using the pthread backend (which isn't 541 When Coro is compiled using the pthread backend (which isn't
494 recommended but required on many BSDs as their libcs are completely 542 recommended but required on many BSDs as their libcs are completely
495 broken), then coroutines will not survive a fork. There is no known 543 broken), then coro will not survive a fork. There is no known
496 workaround except to fix your libc and use a saner backend. 544 workaround except to fix your libc and use a saner backend.
497 545
498 perl process emulation ("threads") 546 perl process emulation ("threads")
499 This module is not perl-pseudo-thread-safe. You should only ever use 547 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 548 this module from the first thread (this requirement might be removed
501 in the future to allow per-thread schedulers, but Coro::State does 549 in the future to allow per-thread schedulers, but Coro::State does
502 not yet allow this). I recommend disabling thread support and using 550 not yet allow this). I recommend disabling thread support and using
503 processes, as having the windows process emulation enabled under 551 processes, as having the windows process emulation enabled under
504 unix roughly halves perl performance, even when not used. 552 unix roughly halves perl performance, even when not used.
505 553
506 coroutine switching not signal safe 554 coro switching is not signal safe
507 You must not switch to another coroutine from within a signal 555 You must not switch to another coro from within a signal handler
508 handler (only relevant with %SIG - most event libraries provide safe 556 (only relevant with %SIG - most event libraries provide safe
509 signals). 557 signals).
510 558
511 That means you *MUST NOT* call any function that might "block" the 559 That means you *MUST NOT* call any function that might "block" the
512 current coroutine - "cede", "schedule" "Coro::Semaphore->down" or 560 current coro - "cede", "schedule" "Coro::Semaphore->down" or
513 anything that calls those. Everything else, including calling 561 anything that calls those. Everything else, including calling
514 "ready", works. 562 "ready", works.
515 563
516SEE ALSO 564SEE ALSO
517 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event. 565 Event-Loop integration: Coro::AnyEvent, Coro::EV, Coro::Event.

Diff Legend

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