… | |
… | |
14 | cede; # yield to coroutine |
14 | cede; # yield to coroutine |
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 | my $lock = new Coro::Semaphore; |
20 | my $lock = new Coro::Semaphore; |
20 | my $locked; |
21 | my $locked; |
21 | |
22 | |
22 | $lock->down; |
23 | $lock->down; |
23 | $locked = 1; |
24 | $locked = 1; |
… | |
… | |
53 | |
54 | |
54 | $Coro::main |
55 | $Coro::main |
55 | This variable stores the coroutine object that represents the main |
56 | This variable stores the coroutine object that represents the main |
56 | program. While you cna "ready" it and do most other things you can |
57 | program. While you cna "ready" it and do most other things you can |
57 | do to coroutines, it is mainly useful to compare again |
58 | do to coroutines, it is mainly useful to compare again |
58 | $Coro::current, to see wether you are running in the main program or |
59 | $Coro::current, to see whether you are running in the main program |
59 | not. |
60 | or not. |
60 | |
61 | |
61 | $Coro::current |
62 | $Coro::current |
62 | The coroutine object representing the current coroutine (the last |
63 | The coroutine object representing the current coroutine (the last |
63 | coroutine that the Coro scheduler switched to). The initial value is |
64 | coroutine that the Coro scheduler switched to). The initial value is |
64 | $main (of course). |
65 | $main (of course). |
… | |
… | |
126 | call terminate or join on it (although you are allowed to), and you |
127 | call terminate or join on it (although you are allowed to), and you |
127 | get a coroutine that might have executed other code already (which |
128 | get a coroutine that might have executed other code already (which |
128 | can be good or bad :). |
129 | can be good or bad :). |
129 | |
130 | |
130 | On the plus side, this function is faster than creating (and |
131 | On the plus side, this function is faster than creating (and |
131 | destroying) a completely new coroutine, so if you need a lot of |
132 | destroying) a completly new coroutine, so if you need a lot of |
132 | generic coroutines in quick successsion, use "async_pool", not |
133 | generic coroutines in quick successsion, use "async_pool", not |
133 | "async". |
134 | "async". |
134 | |
135 | |
135 | The code block is executed in an "eval" context and a warning will |
136 | The code block is executed in an "eval" context and a warning will |
136 | be issued in case of an exception instead of terminating the |
137 | be issued in case of an exception instead of terminating the |
… | |
… | |
141 | |
142 | |
142 | The priority will be reset to 0 after each run, tracing will be |
143 | The priority will be reset to 0 after each run, tracing will be |
143 | disabled, the description will be reset and the default output |
144 | disabled, the description will be reset and the default output |
144 | filehandle gets restored, so you can change all these. Otherwise the |
145 | filehandle gets restored, so you can change all these. Otherwise the |
145 | coroutine will be re-used "as-is": most notably if you change other |
146 | coroutine will be re-used "as-is": most notably if you change other |
146 | per-coroutine global stuff such as $/ you *must needs* to revert |
147 | per-coroutine global stuff such as $/ you *must needs* revert that |
147 | that change, which is most simply done by using local as in: " local |
148 | change, which is most simply done by using local as in: "local $/". |
148 | $/ ". |
|
|
149 | |
149 | |
150 | The pool size is limited to 8 idle coroutines (this can be adjusted |
150 | The idle pool size is limited to 8 idle coroutines (this can be |
151 | by changing $Coro::POOL_SIZE), and there can be as many non-idle |
151 | adjusted by changing $Coro::POOL_SIZE), but there can be as many |
152 | coros as required. |
152 | non-idle coros as required. |
153 | |
153 | |
154 | If you are concerned about pooled coroutines growing a lot because a |
154 | If you are concerned about pooled coroutines growing a lot because a |
155 | single "async_pool" used a lot of stackspace you can e.g. |
155 | single "async_pool" used a lot of stackspace you can e.g. |
156 | "async_pool { terminate }" once per second or so to slowly replenish |
156 | "async_pool { terminate }" once per second or so to slowly replenish |
157 | the pool. In addition to that, when the stacks used by a handler |
157 | the pool. In addition to that, when the stacks used by a handler |
… | |
… | |
177 | This makes "schedule" *the* generic method to use to block the |
177 | This makes "schedule" *the* generic method to use to block the |
178 | current coroutine and wait for events: first you remember the |
178 | current coroutine and wait for events: first you remember the |
179 | current coroutine in a variable, then arrange for some callback of |
179 | current coroutine in a variable, then arrange for some callback of |
180 | yours to call "->ready" on that once some event happens, and last |
180 | yours to call "->ready" on that once some event happens, and last |
181 | you call "schedule" to put yourself to sleep. Note that a lot of |
181 | you call "schedule" to put yourself to sleep. Note that a lot of |
182 | things can wake your coroutine up, so you need to check wether the |
182 | things can wake your coroutine up, so you need to check whether the |
183 | event indeed happened, e.g. by storing the status in a variable. |
183 | event indeed happened, e.g. by storing the status in a variable. |
184 | |
184 | |
185 | The canonical way to wait on external events is this: |
185 | The canonical way to wait on external events is this: |
186 | |
186 | |
187 | { |
187 | { |
… | |
… | |
223 | Kills/terminates/cancels all coroutines except the currently running |
223 | Kills/terminates/cancels all coroutines except the currently running |
224 | one. This is useful after a fork, either in the child or the parent, |
224 | one. This is useful after a fork, either in the child or the parent, |
225 | as usually only one of them should inherit the running coroutines. |
225 | as usually only one of them should inherit the running coroutines. |
226 | |
226 | |
227 | Note that while this will try to free some of the main programs |
227 | Note that while this will try to free some of the main programs |
228 | resources, you cnanot free all of them, so if a coroutine that is |
228 | resources, you cannot free all of them, so if a coroutine that is |
229 | not the main program calls this function, there will be some |
229 | not the main program calls this function, there will be some |
230 | one-time resource leak. |
230 | one-time resource leak. |
231 | |
231 | |
232 | COROUTINE METHODS |
232 | COROUTINE METHODS |
233 | These are the methods you can call on coroutine objects (or to create |
233 | These are the methods you can call on coroutine objects (or to create |
… | |
… | |
251 | automatically once all the coroutines of higher priority and all |
251 | automatically once all the coroutines of higher priority and all |
252 | coroutines of the same priority that were put into the ready queue |
252 | coroutines of the same priority that were put into the ready queue |
253 | earlier have been resumed. |
253 | earlier have been resumed. |
254 | |
254 | |
255 | $is_ready = $coroutine->is_ready |
255 | $is_ready = $coroutine->is_ready |
256 | Return wether the coroutine is currently the ready queue or not, |
256 | Return whether the coroutine is currently the ready queue or not, |
257 | |
257 | |
258 | $coroutine->cancel (arg...) |
258 | $coroutine->cancel (arg...) |
259 | Terminates the given coroutine and makes it return the given |
259 | Terminates the given coroutine and makes it return the given |
260 | arguments as status (default: the empty list). Never returns if the |
260 | arguments as status (default: the empty list). Never returns if the |
261 | coroutine is the current coroutine. |
261 | coroutine is the current coroutine. |
|
|
262 | |
|
|
263 | $coroutine->throw ([$scalar]) |
|
|
264 | If $throw is specified and defined, it will be thrown as an |
|
|
265 | exception inside the coroutine at the next convenient point in time |
|
|
266 | (usually after it gains control at the next schedule/transfer/cede). |
|
|
267 | Otherwise clears the exception object. |
|
|
268 | |
|
|
269 | The exception object will be thrown "as is" with the specified |
|
|
270 | scalar in $@, i.e. if it is a string, no line number or newline will |
|
|
271 | be appended (unlike with "die"). |
|
|
272 | |
|
|
273 | This can be used as a softer means than "cancel" to ask a coroutine |
|
|
274 | to end itself, although there is no guarantee that the exception |
|
|
275 | will lead to termination, and if the exception isn't caught it might |
|
|
276 | well end the whole program. |
|
|
277 | |
|
|
278 | You might also think of "throw" as being the moral equivalent of |
|
|
279 | "kill"ing a coroutine with a signal (in this case, a scalar). |
262 | |
280 | |
263 | $coroutine->join |
281 | $coroutine->join |
264 | Wait until the coroutine terminates and return any values given to |
282 | Wait until the coroutine terminates and return any values given to |
265 | the "terminate" or "cancel" functions. "join" can be called |
283 | the "terminate" or "cancel" functions. "join" can be called |
266 | concurrently from multiple coroutines, and all will be resumed and |
284 | concurrently from multiple coroutines, and all will be resumed and |
… | |
… | |
303 | this coroutine. This is just a free-form string you can associate |
321 | this coroutine. This is just a free-form string you can associate |
304 | with a coroutine. |
322 | with a coroutine. |
305 | |
323 | |
306 | This method simply sets the "$coroutine->{desc}" member to the given |
324 | This method simply sets the "$coroutine->{desc}" member to the given |
307 | string. You can modify this member directly if you wish. |
325 | string. You can modify this member directly if you wish. |
308 | |
|
|
309 | $coroutine->throw ([$scalar]) |
|
|
310 | If $throw is specified and defined, it will be thrown as an |
|
|
311 | exception inside the coroutine at the next convinient point in time |
|
|
312 | (usually after it gains control at the next schedule/transfer/cede). |
|
|
313 | Otherwise clears the exception object. |
|
|
314 | |
|
|
315 | The exception object will be thrown "as is" with the specified |
|
|
316 | scalar in $@, i.e. if it is a string, no line number or newline will |
|
|
317 | be appended (unlike with "die"). |
|
|
318 | |
|
|
319 | This can be used as a softer means than "cancel" to ask a coroutine |
|
|
320 | to end itself, although there is no guarentee that the exception |
|
|
321 | will lead to termination, and if the exception isn't caught it might |
|
|
322 | well end the whole program. |
|
|
323 | |
326 | |
324 | GLOBAL FUNCTIONS |
327 | GLOBAL FUNCTIONS |
325 | Coro::nready |
328 | Coro::nready |
326 | Returns the number of coroutines that are currently in the ready |
329 | Returns the number of coroutines that are currently in the ready |
327 | state, i.e. that can be switched to by calling "schedule" directory |
330 | state, i.e. that can be switched to by calling "schedule" directory |