… | |
… | |
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 | |
66 | async { ... } [@args...] |
74 | async { ... } [@args...] |
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. |
|
|
78 | |
|
|
79 | See the "Coro::State::new" constructor for info about the coroutine |
|
|
80 | environment in which coroutines run. |
70 | |
81 | |
71 | 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 |
72 | outside the coroutine. Likewise, when the coroutine dies, the |
83 | outside the coroutine. Likewise, when the coroutine dies, the |
73 | program will exit, just as it would in the main program. |
84 | program will exit, just as it would in the main program. |
74 | |
85 | |
… | |
… | |
87 | be issued in case of an exception instead of terminating the |
98 | be issued in case of an exception instead of terminating the |
88 | program, as "async" does. As the coroutine is being reused, stuff |
99 | program, as "async" does. As the coroutine is being reused, stuff |
89 | like "on_destroy" will not work in the expected way, unless you call |
100 | like "on_destroy" will not work in the expected way, unless you call |
90 | terminate or cancel, which somehow defeats the purpose of pooling. |
101 | terminate or cancel, which somehow defeats the purpose of pooling. |
91 | |
102 | |
92 | The priority will be reset to 0 after each job, otherwise the |
103 | The priority will be reset to 0 after each job, tracing will be |
93 | coroutine will be re-used "as-is". |
104 | disabled, the description will be reset and the default output |
|
|
105 | filehandle gets restored, so you can change alkl these. Otherwise |
|
|
106 | the coroutine will be re-used "as-is": most notably if you change |
|
|
107 | other per-coroutine global stuff such as $/ you need to revert that |
|
|
108 | change, which is most simply done by using local as in " local $/ ". |
94 | |
109 | |
95 | The pool size is limited to 8 idle coroutines (this can be adjusted |
110 | The pool size is limited to 8 idle coroutines (this can be adjusted |
96 | by changing $Coro::POOL_SIZE), and there can be as many non-idle |
111 | by changing $Coro::POOL_SIZE), and there can be as many non-idle |
97 | coros as required. |
112 | coros as required. |
98 | |
113 | |
99 | If you are concerned about pooled coroutines growing a lot because a |
114 | If you are concerned about pooled coroutines growing a lot because a |
100 | single "async_pool" used a lot of stackspace you can e.g. |
115 | single "async_pool" used a lot of stackspace you can e.g. |
101 | "async_pool { terminate }" once per second or so to slowly replenish |
116 | "async_pool { terminate }" once per second or so to slowly replenish |
102 | the pool. |
117 | the pool. In addition to that, when the stacks used by a handler |
|
|
118 | grows larger than 16kb (adjustable with $Coro::POOL_RSS) it will |
|
|
119 | also exit. |
103 | |
120 | |
104 | schedule |
121 | schedule |
105 | Calls the scheduler. Please note that the current coroutine will not |
122 | Calls the scheduler. Please note that the current coroutine will not |
106 | be put into the ready queue, so calling this function usually means |
123 | be put into the ready queue, so calling this function usually means |
107 | you will never be called again unless something else (e.g. an event |
124 | you will never be called again unless something else (e.g. an event |
… | |
… | |
130 | "Cede" to other coroutines. This function puts the current coroutine |
147 | "Cede" to other coroutines. This function puts the current coroutine |
131 | 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 |
132 | 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 |
133 | higher priority. |
150 | higher priority. |
134 | |
151 | |
135 | Returns true if at least one coroutine switch has happened. |
|
|
136 | |
|
|
137 | Coro::cede_notself |
152 | Coro::cede_notself |
138 | 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 |
139 | coroutine, regardless of priority, once. |
154 | coroutine, regardless of priority, once. |
140 | |
155 | |
141 | Returns true if at least one coroutine switch has happened. |
|
|
142 | |
|
|
143 | terminate [arg...] |
156 | terminate [arg...] |
144 | Terminates the current coroutine with the given status values (see |
157 | Terminates the current coroutine with the given status values (see |
145 | cancel). |
158 | cancel). |
|
|
159 | |
|
|
160 | killall |
|
|
161 | Kills/terminates/cancels all coroutines except the currently running |
|
|
162 | one. This is useful after a fork, either in the child or the parent, |
|
|
163 | as usually only one of them should inherit the running coroutines. |
146 | |
164 | |
147 | # dynamic methods |
165 | # dynamic methods |
148 | |
166 | |
149 | COROUTINE METHODS |
167 | COROUTINE METHODS |
150 | These are the methods you can call on coroutine objects. |
168 | These are the methods you can call on coroutine objects. |
… | |
… | |
153 | Create a new coroutine and return it. When the sub returns the |
171 | Create a new coroutine and return it. When the sub returns the |
154 | coroutine automatically terminates as if "terminate" with the |
172 | coroutine automatically terminates as if "terminate" with the |
155 | returned values were called. To make the coroutine run you must |
173 | returned values were called. To make the coroutine run you must |
156 | first put it into the ready queue by calling the ready method. |
174 | first put it into the ready queue by calling the ready method. |
157 | |
175 | |
158 | See "async" for additional discussion. |
176 | See "async" and "Coro::State::new" for additional info about the |
|
|
177 | coroutine environment. |
159 | |
178 | |
160 | $success = $coroutine->ready |
179 | $success = $coroutine->ready |
161 | Put the given coroutine into the ready queue (according to it's |
180 | Put the given coroutine into the ready queue (according to it's |
162 | priority) and return true. If the coroutine is already in the ready |
181 | priority) and return true. If the coroutine is already in the ready |
163 | queue, do nothing and return false. |
182 | queue, do nothing and return false. |
… | |
… | |
170 | arguments as status (default: the empty list). Never returns if the |
189 | arguments as status (default: the empty list). Never returns if the |
171 | coroutine is the current coroutine. |
190 | coroutine is the current coroutine. |
172 | |
191 | |
173 | $coroutine->join |
192 | $coroutine->join |
174 | Wait until the coroutine terminates and return any values given to |
193 | Wait until the coroutine terminates and return any values given to |
175 | the "terminate" or "cancel" functions. "join" can be called multiple |
194 | the "terminate" or "cancel" functions. "join" can be called |
176 | times from multiple coroutine. |
195 | concurrently from multiple coroutines. |
177 | |
196 | |
178 | $coroutine->on_destroy (\&cb) |
197 | $coroutine->on_destroy (\&cb) |
179 | Registers a callback that is called when this coroutine gets |
198 | Registers a callback that is called when this coroutine gets |
180 | destroyed, but before it is joined. The callback gets passed the |
199 | destroyed, but before it is joined. The callback gets passed the |
181 | terminate arguments, if any. |
200 | terminate arguments, if any. |
… | |
… | |
208 | |
227 | |
209 | $olddesc = $coroutine->desc ($newdesc) |
228 | $olddesc = $coroutine->desc ($newdesc) |
210 | Sets (or gets in case the argument is missing) the description for |
229 | Sets (or gets in case the argument is missing) the description for |
211 | 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 |
212 | with a coroutine. |
231 | with a coroutine. |
|
|
232 | |
|
|
233 | This method simply sets the "$coroutine->{desc}" member to the given |
|
|
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. |
213 | |
250 | |
214 | GLOBAL FUNCTIONS |
251 | GLOBAL FUNCTIONS |
215 | Coro::nready |
252 | Coro::nready |
216 | Returns the number of coroutines that are currently in the ready |
253 | Returns the number of coroutines that are currently in the ready |
217 | 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 |
… | |
… | |
266 | 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 |
267 | 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 |
268 | this). |
305 | this). |
269 | |
306 | |
270 | SEE ALSO |
307 | SEE ALSO |
|
|
308 | Lower level Configuration, Coroutine Environment: Coro::State. |
|
|
309 | |
|
|
310 | Debugging: Coro::Debug. |
|
|
311 | |
271 | Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util. |
312 | Support/Utility: Coro::Specific, Coro::Util. |
272 | |
313 | |
273 | Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, |
314 | Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, |
274 | Coro::SemaphoreSet, Coro::RWLock. |
315 | Coro::SemaphoreSet, Coro::RWLock. |
275 | |
316 | |
276 | Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket, |
317 | Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket. |
277 | Coro::Select. |
|
|
278 | |
318 | |
|
|
319 | Compatibility: Coro::LWP, Coro::Storable, Coro::Select. |
|
|
320 | |
279 | Embedding: <Coro:MakeMaker> |
321 | Embedding: <Coro:MakeMaker>. |
280 | |
322 | |
281 | AUTHOR |
323 | AUTHOR |
282 | Marc Lehmann <schmorp@schmorp.de> |
324 | Marc Lehmann <schmorp@schmorp.de> |
283 | http://home.schmorp.de/ |
325 | http://home.schmorp.de/ |
284 | |
326 | |