1 |
root |
1.1 |
NAME |
2 |
|
|
Coro - coroutine process abstraction |
3 |
|
|
|
4 |
|
|
SYNOPSIS |
5 |
|
|
use Coro; |
6 |
|
|
|
7 |
|
|
async { |
8 |
|
|
# some asynchronous thread of execution |
9 |
root |
1.12 |
print "2\n"; |
10 |
|
|
cede; # yield back to main |
11 |
|
|
print "4\n"; |
12 |
root |
1.1 |
}; |
13 |
root |
1.12 |
print "1\n"; |
14 |
|
|
cede; # yield to coroutine |
15 |
|
|
print "3\n"; |
16 |
|
|
cede; # and again |
17 |
|
|
|
18 |
|
|
# use locking |
19 |
|
|
my $lock = new Coro::Semaphore; |
20 |
|
|
my $locked; |
21 |
|
|
|
22 |
|
|
$lock->down; |
23 |
|
|
$locked = 1; |
24 |
|
|
$lock->up; |
25 |
root |
1.1 |
|
26 |
|
|
DESCRIPTION |
27 |
|
|
This module collection manages coroutines. Coroutines are similar to |
28 |
root |
1.5 |
threads but don't run in parallel at the same time even on SMP machines. |
29 |
root |
1.8 |
The specific flavor of coroutine used in this module also guarantees you |
30 |
root |
1.5 |
that it will not switch between coroutines unless necessary, at |
31 |
|
|
easily-identified points in your program, so locking and parallel access |
32 |
|
|
are rarely an issue, making coroutine programming much safer than |
33 |
|
|
threads programming. |
34 |
|
|
|
35 |
|
|
(Perl, however, does not natively support real threads but instead does |
36 |
|
|
a very slow and memory-intensive emulation of processes using threads. |
37 |
|
|
This is a performance win on Windows machines, and a loss everywhere |
38 |
|
|
else). |
39 |
root |
1.1 |
|
40 |
|
|
In this module, coroutines are defined as "callchain + lexical variables |
41 |
root |
1.5 |
+ @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own |
42 |
|
|
callchain, its own set of lexicals and its own set of perls most |
43 |
root |
1.12 |
important global variables (see Coro::State for more configuration). |
44 |
root |
1.1 |
|
45 |
|
|
$main |
46 |
|
|
This coroutine represents the main program. |
47 |
|
|
|
48 |
|
|
$current (or as function: current) |
49 |
|
|
The current coroutine (the last coroutine switched to). The initial |
50 |
|
|
value is $main (of course). |
51 |
|
|
|
52 |
root |
1.4 |
This variable is strictly *read-only*. It is provided for |
53 |
root |
1.8 |
performance reasons. If performance is not essential you are |
54 |
root |
1.4 |
encouraged to use the "Coro::current" function instead. |
55 |
|
|
|
56 |
root |
1.1 |
$idle |
57 |
root |
1.4 |
A callback that is called whenever the scheduler finds no ready |
58 |
|
|
coroutines to run. The default implementation prints "FATAL: |
59 |
|
|
deadlock detected" and exits, because the program has no other way |
60 |
|
|
to continue. |
61 |
|
|
|
62 |
|
|
This hook is overwritten by modules such as "Coro::Timer" and |
63 |
|
|
"Coro::Event" to wait on an external event that hopefully wake up a |
64 |
|
|
coroutine so the scheduler can run it. |
65 |
|
|
|
66 |
|
|
Please note that if your callback recursively invokes perl (e.g. for |
67 |
root |
1.12 |
event handlers), then it must be prepared to be called recursively |
68 |
|
|
itself. |
69 |
root |
1.1 |
|
70 |
|
|
STATIC METHODS |
71 |
|
|
Static methods are actually functions that operate on the current |
72 |
root |
1.4 |
coroutine only. |
73 |
root |
1.1 |
|
74 |
|
|
async { ... } [@args...] |
75 |
root |
1.4 |
Create a new asynchronous coroutine and return it's coroutine object |
76 |
|
|
(usually unused). When the sub returns the new coroutine is |
77 |
root |
1.1 |
automatically terminated. |
78 |
|
|
|
79 |
root |
1.10 |
See the "Coro::State::new" constructor for info about the coroutine |
80 |
root |
1.12 |
environment in which coroutines run. |
81 |
root |
1.10 |
|
82 |
root |
1.7 |
Calling "exit" in a coroutine will do the same as calling exit |
83 |
|
|
outside the coroutine. Likewise, when the coroutine dies, the |
84 |
|
|
program will exit, just as it would in the main program. |
85 |
root |
1.3 |
|
86 |
root |
1.1 |
# create a new coroutine that just prints its arguments |
87 |
|
|
async { |
88 |
|
|
print "@_\n"; |
89 |
|
|
} 1,2,3,4; |
90 |
|
|
|
91 |
root |
1.6 |
async_pool { ... } [@args...] |
92 |
|
|
Similar to "async", but uses a coroutine pool, so you should not |
93 |
|
|
call terminate or join (although you are allowed to), and you get a |
94 |
|
|
coroutine that might have executed other code already (which can be |
95 |
|
|
good or bad :). |
96 |
|
|
|
97 |
|
|
Also, the block is executed in an "eval" context and a warning will |
98 |
|
|
be issued in case of an exception instead of terminating the |
99 |
|
|
program, as "async" does. As the coroutine is being reused, stuff |
100 |
|
|
like "on_destroy" will not work in the expected way, unless you call |
101 |
|
|
terminate or cancel, which somehow defeats the purpose of pooling. |
102 |
|
|
|
103 |
root |
1.10 |
The priority will be reset to 0 after each job, tracing will be |
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 $/ ". |
109 |
root |
1.6 |
|
110 |
|
|
The pool size is limited to 8 idle coroutines (this can be adjusted |
111 |
|
|
by changing $Coro::POOL_SIZE), and there can be as many non-idle |
112 |
|
|
coros as required. |
113 |
|
|
|
114 |
|
|
If you are concerned about pooled coroutines growing a lot because a |
115 |
|
|
single "async_pool" used a lot of stackspace you can e.g. |
116 |
|
|
"async_pool { terminate }" once per second or so to slowly replenish |
117 |
root |
1.9 |
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. |
120 |
root |
1.6 |
|
121 |
root |
1.1 |
schedule |
122 |
root |
1.4 |
Calls the scheduler. Please note that the current coroutine will not |
123 |
root |
1.1 |
be put into the ready queue, so calling this function usually means |
124 |
root |
1.4 |
you will never be called again unless something else (e.g. an event |
125 |
|
|
handler) calls ready. |
126 |
|
|
|
127 |
|
|
The canonical way to wait on external events is this: |
128 |
|
|
|
129 |
|
|
{ |
130 |
|
|
# remember current coroutine |
131 |
|
|
my $current = $Coro::current; |
132 |
|
|
|
133 |
|
|
# register a hypothetical event handler |
134 |
|
|
on_event_invoke sub { |
135 |
|
|
# wake up sleeping coroutine |
136 |
|
|
$current->ready; |
137 |
|
|
undef $current; |
138 |
|
|
}; |
139 |
|
|
|
140 |
root |
1.8 |
# call schedule until event occurred. |
141 |
root |
1.4 |
# in case we are woken up for other reasons |
142 |
|
|
# (current still defined), loop. |
143 |
|
|
Coro::schedule while $current; |
144 |
|
|
} |
145 |
root |
1.1 |
|
146 |
|
|
cede |
147 |
root |
1.4 |
"Cede" to other coroutines. This function puts the current coroutine |
148 |
root |
1.1 |
into the ready queue and calls "schedule", which has the effect of |
149 |
|
|
giving up the current "timeslice" to other coroutines of the same or |
150 |
|
|
higher priority. |
151 |
|
|
|
152 |
root |
1.6 |
Coro::cede_notself |
153 |
|
|
Works like cede, but is not exported by default and will cede to any |
154 |
|
|
coroutine, regardless of priority, once. |
155 |
|
|
|
156 |
root |
1.1 |
terminate [arg...] |
157 |
root |
1.4 |
Terminates the current coroutine with the given status values (see |
158 |
root |
1.1 |
cancel). |
159 |
|
|
|
160 |
root |
1.10 |
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. |
164 |
|
|
|
165 |
root |
1.1 |
# dynamic methods |
166 |
|
|
|
167 |
root |
1.4 |
COROUTINE METHODS |
168 |
|
|
These are the methods you can call on coroutine objects. |
169 |
root |
1.1 |
|
170 |
|
|
new Coro \&sub [, @args...] |
171 |
root |
1.4 |
Create a new coroutine and return it. When the sub returns the |
172 |
|
|
coroutine automatically terminates as if "terminate" with the |
173 |
|
|
returned values were called. To make the coroutine run you must |
174 |
|
|
first put it into the ready queue by calling the ready method. |
175 |
|
|
|
176 |
root |
1.10 |
See "async" and "Coro::State::new" for additional info about the |
177 |
|
|
coroutine environment. |
178 |
root |
1.4 |
|
179 |
|
|
$success = $coroutine->ready |
180 |
|
|
Put the given coroutine into the ready queue (according to it's |
181 |
|
|
priority) and return true. If the coroutine is already in the ready |
182 |
|
|
queue, do nothing and return false. |
183 |
|
|
|
184 |
|
|
$is_ready = $coroutine->is_ready |
185 |
|
|
Return wether the coroutine is currently the ready queue or not, |
186 |
|
|
|
187 |
|
|
$coroutine->cancel (arg...) |
188 |
|
|
Terminates the given coroutine and makes it return the given |
189 |
root |
1.6 |
arguments as status (default: the empty list). Never returns if the |
190 |
|
|
coroutine is the current coroutine. |
191 |
root |
1.1 |
|
192 |
root |
1.4 |
$coroutine->join |
193 |
root |
1.1 |
Wait until the coroutine terminates and return any values given to |
194 |
root |
1.10 |
the "terminate" or "cancel" functions. "join" can be called |
195 |
|
|
concurrently from multiple coroutines. |
196 |
root |
1.1 |
|
197 |
root |
1.6 |
$coroutine->on_destroy (\&cb) |
198 |
|
|
Registers a callback that is called when this coroutine gets |
199 |
|
|
destroyed, but before it is joined. The callback gets passed the |
200 |
|
|
terminate arguments, if any. |
201 |
|
|
|
202 |
root |
1.4 |
$oldprio = $coroutine->prio ($newprio) |
203 |
root |
1.1 |
Sets (or gets, if the argument is missing) the priority of the |
204 |
root |
1.4 |
coroutine. Higher priority coroutines get run before lower priority |
205 |
|
|
coroutines. Priorities are small signed integers (currently -4 .. |
206 |
root |
1.1 |
+3), that you can refer to using PRIO_xxx constants (use the import |
207 |
|
|
tag :prio to get then): |
208 |
|
|
|
209 |
|
|
PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN |
210 |
|
|
3 > 1 > 0 > -1 > -3 > -4 |
211 |
|
|
|
212 |
|
|
# set priority to HIGH |
213 |
|
|
current->prio(PRIO_HIGH); |
214 |
|
|
|
215 |
|
|
The idle coroutine ($Coro::idle) always has a lower priority than |
216 |
|
|
any existing coroutine. |
217 |
|
|
|
218 |
root |
1.4 |
Changing the priority of the current coroutine will take effect |
219 |
|
|
immediately, but changing the priority of coroutines in the ready |
220 |
root |
1.1 |
queue (but not running) will only take effect after the next |
221 |
root |
1.4 |
schedule (of that coroutine). This is a bug that will be fixed in |
222 |
|
|
some future version. |
223 |
root |
1.1 |
|
224 |
root |
1.4 |
$newprio = $coroutine->nice ($change) |
225 |
root |
1.1 |
Similar to "prio", but subtract the given value from the priority |
226 |
|
|
(i.e. higher values mean lower priority, just as in unix). |
227 |
|
|
|
228 |
root |
1.4 |
$olddesc = $coroutine->desc ($newdesc) |
229 |
root |
1.1 |
Sets (or gets in case the argument is missing) the description for |
230 |
root |
1.4 |
this coroutine. This is just a free-form string you can associate |
231 |
|
|
with a coroutine. |
232 |
|
|
|
233 |
root |
1.10 |
This method simply sets the "$coroutine->{desc}" member to the given |
234 |
|
|
string. You can modify this member directly if you wish. |
235 |
|
|
|
236 |
root |
1.11 |
$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. |
250 |
|
|
|
251 |
root |
1.5 |
GLOBAL FUNCTIONS |
252 |
|
|
Coro::nready |
253 |
|
|
Returns the number of coroutines that are currently in the ready |
254 |
root |
1.8 |
state, i.e. that can be switched to. The value 0 means that the only |
255 |
root |
1.5 |
runnable coroutine is the currently running one, so "cede" would |
256 |
|
|
have no effect, and "schedule" would cause a deadlock unless there |
257 |
|
|
is an idle handler that wakes up some coroutines. |
258 |
|
|
|
259 |
root |
1.6 |
my $guard = Coro::guard { ... } |
260 |
|
|
This creates and returns a guard object. Nothing happens until the |
261 |
root |
1.7 |
object gets destroyed, in which case the codeblock given as argument |
262 |
root |
1.6 |
will be executed. This is useful to free locks or other resources in |
263 |
|
|
case of a runtime error or when the coroutine gets canceled, as in |
264 |
|
|
both cases the guard block will be executed. The guard object |
265 |
|
|
supports only one method, "->cancel", which will keep the codeblock |
266 |
|
|
from being executed. |
267 |
|
|
|
268 |
|
|
Example: set some flag and clear it again when the coroutine gets |
269 |
|
|
canceled or the function returns: |
270 |
|
|
|
271 |
|
|
sub do_something { |
272 |
|
|
my $guard = Coro::guard { $busy = 0 }; |
273 |
|
|
$busy = 1; |
274 |
|
|
|
275 |
|
|
# do something that requires $busy to be true |
276 |
|
|
} |
277 |
|
|
|
278 |
root |
1.4 |
unblock_sub { ... } |
279 |
|
|
This utility function takes a BLOCK or code reference and "unblocks" |
280 |
|
|
it, returning the new coderef. This means that the new coderef will |
281 |
|
|
return immediately without blocking, returning nothing, while the |
282 |
|
|
original code ref will be called (with parameters) from within its |
283 |
|
|
own coroutine. |
284 |
|
|
|
285 |
root |
1.8 |
The reason this function exists is that many event libraries (such |
286 |
root |
1.4 |
as the venerable Event module) are not coroutine-safe (a weaker form |
287 |
|
|
of thread-safety). This means you must not block within event |
288 |
|
|
callbacks, otherwise you might suffer from crashes or worse. |
289 |
|
|
|
290 |
|
|
This function allows your callbacks to block by executing them in |
291 |
|
|
another coroutine where it is safe to block. One example where |
292 |
|
|
blocking is handy is when you use the Coro::AIO functions to save |
293 |
|
|
results to disk. |
294 |
|
|
|
295 |
|
|
In short: simply use "unblock_sub { ... }" instead of "sub { ... }" |
296 |
|
|
when creating event callbacks that want to block. |
297 |
root |
1.1 |
|
298 |
|
|
BUGS/LIMITATIONS |
299 |
|
|
- you must make very sure that no coro is still active on global |
300 |
|
|
destruction. very bad things might happen otherwise (usually segfaults). |
301 |
|
|
|
302 |
|
|
- this module is not thread-safe. You should only ever use this module |
303 |
root |
1.8 |
from the same thread (this requirement might be loosened in the future |
304 |
root |
1.1 |
to allow per-thread schedulers, but Coro::State does not yet allow |
305 |
|
|
this). |
306 |
|
|
|
307 |
|
|
SEE ALSO |
308 |
root |
1.12 |
Lower level Configuration, Coroutine Environment: Coro::State. |
309 |
|
|
|
310 |
|
|
Debugging: Coro::Debug. |
311 |
|
|
|
312 |
|
|
Support/Utility: Coro::Specific, Coro::Util. |
313 |
root |
1.2 |
|
314 |
|
|
Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, |
315 |
|
|
Coro::SemaphoreSet, Coro::RWLock. |
316 |
|
|
|
317 |
root |
1.12 |
Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket. |
318 |
|
|
|
319 |
|
|
Compatibility: Coro::LWP, Coro::Storable, Coro::Select. |
320 |
root |
1.2 |
|
321 |
root |
1.12 |
Embedding: <Coro:MakeMaker>. |
322 |
root |
1.1 |
|
323 |
|
|
AUTHOR |
324 |
|
|
Marc Lehmann <schmorp@schmorp.de> |
325 |
|
|
http://home.schmorp.de/ |
326 |
|
|
|