… | |
… | |
4 | SYNOPSIS |
4 | SYNOPSIS |
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"; |
|
|
10 | cede; # yield back to main |
|
|
11 | print "4\n"; |
9 | }; |
12 | }; |
|
|
13 | print "1\n"; |
|
|
14 | cede; # yield to coroutine |
|
|
15 | print "3\n"; |
|
|
16 | cede; # and again |
10 | |
17 | |
11 | # alternatively create an async coroutine like this: |
18 | # use locking |
|
|
19 | my $lock = new Coro::Semaphore; |
|
|
20 | my $locked; |
12 | |
21 | |
13 | sub some_func : Coro { |
22 | $lock->down; |
14 | # some more async code |
23 | $locked = 1; |
15 | } |
24 | $lock->up; |
16 | |
|
|
17 | cede; |
|
|
18 | |
25 | |
19 | DESCRIPTION |
26 | DESCRIPTION |
20 | This module collection manages coroutines. Coroutines are similar to |
27 | This module collection manages coroutines. Coroutines are similar to |
21 | threads but don't run in parallel at the same time even on SMP machines. |
28 | threads but don't run in parallel at the same time even on SMP machines. |
22 | The specific flavor of coroutine used in this module also guarantees you |
29 | The specific flavor of coroutine used in this module also guarantees you |
… | |
… | |
31 | else). |
38 | else). |
32 | |
39 | |
33 | In this module, coroutines are defined as "callchain + lexical variables |
40 | In this module, coroutines are defined as "callchain + lexical variables |
34 | + @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own |
41 | + @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own |
35 | callchain, its own set of lexicals and its own set of perls most |
42 | callchain, its own set of lexicals and its own set of perls most |
36 | important global variables. |
43 | important global variables (see Coro::State for more configuration). |
37 | |
44 | |
38 | $main |
45 | $main |
39 | This coroutine represents the main program. |
46 | This coroutine represents the main program. |
40 | |
47 | |
41 | $current (or as function: current) |
48 | $current (or as function: current) |
… | |
… | |
55 | This hook is overwritten by modules such as "Coro::Timer" and |
62 | This hook is overwritten by modules such as "Coro::Timer" and |
56 | "Coro::Event" to wait on an external event that hopefully wake up a |
63 | "Coro::Event" to wait on an external event that hopefully wake up a |
57 | coroutine so the scheduler can run it. |
64 | coroutine so the scheduler can run it. |
58 | |
65 | |
59 | Please note that if your callback recursively invokes perl (e.g. for |
66 | Please note that if your callback recursively invokes perl (e.g. for |
60 | event handlers), then it must be prepared to be called recursively. |
67 | event handlers), then it must be prepared to be called recursively |
|
|
68 | itself. |
61 | |
69 | |
62 | STATIC METHODS |
70 | STATIC METHODS |
63 | Static methods are actually functions that operate on the current |
71 | Static methods are actually functions that operate on the current |
64 | coroutine only. |
72 | coroutine only. |
65 | |
73 | |
… | |
… | |
67 | Create a new asynchronous coroutine and return it's coroutine object |
75 | Create a new asynchronous coroutine and return it's coroutine object |
68 | (usually unused). When the sub returns the new coroutine is |
76 | (usually unused). When the sub returns the new coroutine is |
69 | automatically terminated. |
77 | automatically terminated. |
70 | |
78 | |
71 | See the "Coro::State::new" constructor for info about the coroutine |
79 | See the "Coro::State::new" constructor for info about the coroutine |
72 | environment. |
80 | environment in which coroutines run. |
73 | |
81 | |
74 | Calling "exit" in a coroutine will do the same as calling exit |
82 | Calling "exit" in a coroutine will do the same as calling exit |
75 | outside the coroutine. Likewise, when the coroutine dies, the |
83 | outside the coroutine. Likewise, when the coroutine dies, the |
76 | program will exit, just as it would in the main program. |
84 | program will exit, just as it would in the main program. |
77 | |
85 | |
… | |
… | |
139 | "Cede" to other coroutines. This function puts the current coroutine |
147 | "Cede" to other coroutines. This function puts the current coroutine |
140 | into the ready queue and calls "schedule", which has the effect of |
148 | into the ready queue and calls "schedule", which has the effect of |
141 | giving up the current "timeslice" to other coroutines of the same or |
149 | giving up the current "timeslice" to other coroutines of the same or |
142 | higher priority. |
150 | higher priority. |
143 | |
151 | |
144 | Returns true if at least one coroutine switch has happened. |
|
|
145 | |
|
|
146 | Coro::cede_notself |
152 | Coro::cede_notself |
147 | Works like cede, but is not exported by default and will cede to any |
153 | Works like cede, but is not exported by default and will cede to any |
148 | coroutine, regardless of priority, once. |
154 | coroutine, regardless of priority, once. |
149 | |
|
|
150 | Returns true if at least one coroutine switch has happened. |
|
|
151 | |
155 | |
152 | terminate [arg...] |
156 | terminate [arg...] |
153 | Terminates the current coroutine with the given status values (see |
157 | Terminates the current coroutine with the given status values (see |
154 | cancel). |
158 | cancel). |
155 | |
159 | |
… | |
… | |
226 | this coroutine. This is just a free-form string you can associate |
230 | this coroutine. This is just a free-form string you can associate |
227 | with a coroutine. |
231 | with a coroutine. |
228 | |
232 | |
229 | This method simply sets the "$coroutine->{desc}" member to the given |
233 | This method simply sets the "$coroutine->{desc}" member to the given |
230 | string. You can modify this member directly if you wish. |
234 | string. You can modify this member directly if you wish. |
|
|
235 | |
|
|
236 | $coroutine->throw ([$scalar]) |
|
|
237 | If $throw is specified and defined, it will be thrown as an |
|
|
238 | exception inside the coroutine at the next convinient point in time |
|
|
239 | (usually after it gains control at the next schedule/transfer/cede). |
|
|
240 | Otherwise clears the exception object. |
|
|
241 | |
|
|
242 | The exception object will be thrown "as is" with the specified |
|
|
243 | scalar in $@, i.e. if it is a string, no line number or newline will |
|
|
244 | be appended (unlike with "die"). |
|
|
245 | |
|
|
246 | This can be used as a softer means than "cancel" to ask a coroutine |
|
|
247 | to end itself, although there is no guarentee that the exception |
|
|
248 | will lead to termination, and if the exception isn't caught it might |
|
|
249 | well end the whole program. |
231 | |
250 | |
232 | GLOBAL FUNCTIONS |
251 | GLOBAL FUNCTIONS |
233 | Coro::nready |
252 | Coro::nready |
234 | Returns the number of coroutines that are currently in the ready |
253 | Returns the number of coroutines that are currently in the ready |
235 | state, i.e. that can be switched to. The value 0 means that the only |
254 | state, i.e. that can be switched to. The value 0 means that the only |
… | |
… | |
284 | from the same thread (this requirement might be loosened in the future |
303 | from the same thread (this requirement might be loosened in the future |
285 | to allow per-thread schedulers, but Coro::State does not yet allow |
304 | to allow per-thread schedulers, but Coro::State does not yet allow |
286 | this). |
305 | this). |
287 | |
306 | |
288 | SEE ALSO |
307 | SEE ALSO |
|
|
308 | Lower level Configuration, Coroutine Environment: Coro::State. |
|
|
309 | |
|
|
310 | Debugging: Coro::Debug. |
|
|
311 | |
289 | Support/Utility: Coro::Specific, Coro::State, Coro::Util. |
312 | Support/Utility: Coro::Specific, Coro::Util. |
290 | |
313 | |
291 | Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, |
314 | Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, |
292 | Coro::SemaphoreSet, Coro::RWLock. |
315 | Coro::SemaphoreSet, Coro::RWLock. |
293 | |
316 | |
294 | Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket, |
317 | Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket. |
295 | Coro::Select. |
|
|
296 | |
318 | |
|
|
319 | Compatibility: Coro::LWP, Coro::Storable, Coro::Select. |
|
|
320 | |
297 | Embedding: <Coro:MakeMaker> |
321 | Embedding: Coro::MakeMaker. |
298 | |
322 | |
299 | AUTHOR |
323 | AUTHOR |
300 | Marc Lehmann <schmorp@schmorp.de> |
324 | Marc Lehmann <schmorp@schmorp.de> |
301 | http://home.schmorp.de/ |
325 | http://home.schmorp.de/ |
302 | |
326 | |