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 |
|
|
}; |
10 |
|
|
|
11 |
root |
1.4 |
# alternatively create an async coroutine like this: |
12 |
root |
1.1 |
|
13 |
|
|
sub some_func : Coro { |
14 |
|
|
# some more async code |
15 |
|
|
} |
16 |
|
|
|
17 |
|
|
cede; |
18 |
|
|
|
19 |
|
|
DESCRIPTION |
20 |
|
|
This module collection manages coroutines. Coroutines are similar to |
21 |
|
|
threads but don't run in parallel. |
22 |
|
|
|
23 |
|
|
In this module, coroutines are defined as "callchain + lexical variables |
24 |
|
|
+ @_ + $_ + $@ + $^W + C stack), that is, a coroutine has it's own |
25 |
|
|
callchain, it's own set of lexicals and it's own set of perl's most |
26 |
|
|
important global variables. |
27 |
|
|
|
28 |
|
|
$main |
29 |
|
|
This coroutine represents the main program. |
30 |
|
|
|
31 |
|
|
$current (or as function: current) |
32 |
|
|
The current coroutine (the last coroutine switched to). The initial |
33 |
|
|
value is $main (of course). |
34 |
|
|
|
35 |
root |
1.4 |
This variable is strictly *read-only*. It is provided for |
36 |
|
|
performance reasons. If performance is not essentiel you are |
37 |
|
|
encouraged to use the "Coro::current" function instead. |
38 |
|
|
|
39 |
root |
1.1 |
$idle |
40 |
root |
1.4 |
A callback that is called whenever the scheduler finds no ready |
41 |
|
|
coroutines to run. The default implementation prints "FATAL: |
42 |
|
|
deadlock detected" and exits, because the program has no other way |
43 |
|
|
to continue. |
44 |
|
|
|
45 |
|
|
This hook is overwritten by modules such as "Coro::Timer" and |
46 |
|
|
"Coro::Event" to wait on an external event that hopefully wake up a |
47 |
|
|
coroutine so the scheduler can run it. |
48 |
|
|
|
49 |
|
|
Please note that if your callback recursively invokes perl (e.g. for |
50 |
|
|
event handlers), then it must be prepared to be called recursively. |
51 |
root |
1.1 |
|
52 |
|
|
STATIC METHODS |
53 |
|
|
Static methods are actually functions that operate on the current |
54 |
root |
1.4 |
coroutine only. |
55 |
root |
1.1 |
|
56 |
|
|
async { ... } [@args...] |
57 |
root |
1.4 |
Create a new asynchronous coroutine and return it's coroutine object |
58 |
|
|
(usually unused). When the sub returns the new coroutine is |
59 |
root |
1.1 |
automatically terminated. |
60 |
|
|
|
61 |
root |
1.4 |
Calling "exit" in a coroutine will not work correctly, so do not do |
62 |
|
|
that. |
63 |
|
|
|
64 |
root |
1.3 |
When the coroutine dies, the program will exit, just as in the main |
65 |
|
|
program. |
66 |
|
|
|
67 |
root |
1.1 |
# create a new coroutine that just prints its arguments |
68 |
|
|
async { |
69 |
|
|
print "@_\n"; |
70 |
|
|
} 1,2,3,4; |
71 |
|
|
|
72 |
|
|
schedule |
73 |
root |
1.4 |
Calls the scheduler. Please note that the current coroutine will not |
74 |
root |
1.1 |
be put into the ready queue, so calling this function usually means |
75 |
root |
1.4 |
you will never be called again unless something else (e.g. an event |
76 |
|
|
handler) calls ready. |
77 |
|
|
|
78 |
|
|
The canonical way to wait on external events is this: |
79 |
|
|
|
80 |
|
|
{ |
81 |
|
|
# remember current coroutine |
82 |
|
|
my $current = $Coro::current; |
83 |
|
|
|
84 |
|
|
# register a hypothetical event handler |
85 |
|
|
on_event_invoke sub { |
86 |
|
|
# wake up sleeping coroutine |
87 |
|
|
$current->ready; |
88 |
|
|
undef $current; |
89 |
|
|
}; |
90 |
|
|
|
91 |
|
|
# call schedule until event occured. |
92 |
|
|
# in case we are woken up for other reasons |
93 |
|
|
# (current still defined), loop. |
94 |
|
|
Coro::schedule while $current; |
95 |
|
|
} |
96 |
root |
1.1 |
|
97 |
|
|
cede |
98 |
root |
1.4 |
"Cede" to other coroutines. This function puts the current coroutine |
99 |
root |
1.1 |
into the ready queue and calls "schedule", which has the effect of |
100 |
|
|
giving up the current "timeslice" to other coroutines of the same or |
101 |
|
|
higher priority. |
102 |
|
|
|
103 |
|
|
terminate [arg...] |
104 |
root |
1.4 |
Terminates the current coroutine with the given status values (see |
105 |
root |
1.1 |
cancel). |
106 |
|
|
|
107 |
|
|
# dynamic methods |
108 |
|
|
|
109 |
root |
1.4 |
COROUTINE METHODS |
110 |
|
|
These are the methods you can call on coroutine objects. |
111 |
root |
1.1 |
|
112 |
|
|
new Coro \&sub [, @args...] |
113 |
root |
1.4 |
Create a new coroutine and return it. When the sub returns the |
114 |
|
|
coroutine automatically terminates as if "terminate" with the |
115 |
|
|
returned values were called. To make the coroutine run you must |
116 |
|
|
first put it into the ready queue by calling the ready method. |
117 |
|
|
|
118 |
|
|
Calling "exit" in a coroutine will not work correctly, so do not do |
119 |
|
|
that. |
120 |
|
|
|
121 |
|
|
$success = $coroutine->ready |
122 |
|
|
Put the given coroutine into the ready queue (according to it's |
123 |
|
|
priority) and return true. If the coroutine is already in the ready |
124 |
|
|
queue, do nothing and return false. |
125 |
|
|
|
126 |
|
|
$is_ready = $coroutine->is_ready |
127 |
|
|
Return wether the coroutine is currently the ready queue or not, |
128 |
|
|
|
129 |
|
|
$coroutine->cancel (arg...) |
130 |
|
|
Terminates the given coroutine and makes it return the given |
131 |
|
|
arguments as status (default: the empty list). |
132 |
root |
1.1 |
|
133 |
root |
1.4 |
$coroutine->join |
134 |
root |
1.1 |
Wait until the coroutine terminates and return any values given to |
135 |
|
|
the "terminate" or "cancel" functions. "join" can be called multiple |
136 |
root |
1.4 |
times from multiple coroutine. |
137 |
root |
1.1 |
|
138 |
root |
1.4 |
$oldprio = $coroutine->prio ($newprio) |
139 |
root |
1.1 |
Sets (or gets, if the argument is missing) the priority of the |
140 |
root |
1.4 |
coroutine. Higher priority coroutines get run before lower priority |
141 |
|
|
coroutines. Priorities are small signed integers (currently -4 .. |
142 |
root |
1.1 |
+3), that you can refer to using PRIO_xxx constants (use the import |
143 |
|
|
tag :prio to get then): |
144 |
|
|
|
145 |
|
|
PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN |
146 |
|
|
3 > 1 > 0 > -1 > -3 > -4 |
147 |
|
|
|
148 |
|
|
# set priority to HIGH |
149 |
|
|
current->prio(PRIO_HIGH); |
150 |
|
|
|
151 |
|
|
The idle coroutine ($Coro::idle) always has a lower priority than |
152 |
|
|
any existing coroutine. |
153 |
|
|
|
154 |
root |
1.4 |
Changing the priority of the current coroutine will take effect |
155 |
|
|
immediately, but changing the priority of coroutines in the ready |
156 |
root |
1.1 |
queue (but not running) will only take effect after the next |
157 |
root |
1.4 |
schedule (of that coroutine). This is a bug that will be fixed in |
158 |
|
|
some future version. |
159 |
root |
1.1 |
|
160 |
root |
1.4 |
$newprio = $coroutine->nice ($change) |
161 |
root |
1.1 |
Similar to "prio", but subtract the given value from the priority |
162 |
|
|
(i.e. higher values mean lower priority, just as in unix). |
163 |
|
|
|
164 |
root |
1.4 |
$olddesc = $coroutine->desc ($newdesc) |
165 |
root |
1.1 |
Sets (or gets in case the argument is missing) the description for |
166 |
root |
1.4 |
this coroutine. This is just a free-form string you can associate |
167 |
|
|
with a coroutine. |
168 |
|
|
|
169 |
|
|
UTILITY FUNCTIONS |
170 |
|
|
unblock_sub { ... } |
171 |
|
|
This utility function takes a BLOCK or code reference and "unblocks" |
172 |
|
|
it, returning the new coderef. This means that the new coderef will |
173 |
|
|
return immediately without blocking, returning nothing, while the |
174 |
|
|
original code ref will be called (with parameters) from within its |
175 |
|
|
own coroutine. |
176 |
|
|
|
177 |
|
|
The reason this fucntion exists is that many event libraries (such |
178 |
|
|
as the venerable Event module) are not coroutine-safe (a weaker form |
179 |
|
|
of thread-safety). This means you must not block within event |
180 |
|
|
callbacks, otherwise you might suffer from crashes or worse. |
181 |
|
|
|
182 |
|
|
This function allows your callbacks to block by executing them in |
183 |
|
|
another coroutine where it is safe to block. One example where |
184 |
|
|
blocking is handy is when you use the Coro::AIO functions to save |
185 |
|
|
results to disk. |
186 |
|
|
|
187 |
|
|
In short: simply use "unblock_sub { ... }" instead of "sub { ... }" |
188 |
|
|
when creating event callbacks that want to block. |
189 |
root |
1.1 |
|
190 |
|
|
BUGS/LIMITATIONS |
191 |
|
|
- you must make very sure that no coro is still active on global |
192 |
|
|
destruction. very bad things might happen otherwise (usually segfaults). |
193 |
|
|
|
194 |
|
|
- this module is not thread-safe. You should only ever use this module |
195 |
|
|
from the same thread (this requirement might be losened in the future |
196 |
|
|
to allow per-thread schedulers, but Coro::State does not yet allow |
197 |
|
|
this). |
198 |
|
|
|
199 |
|
|
SEE ALSO |
200 |
root |
1.2 |
Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util. |
201 |
|
|
|
202 |
|
|
Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, |
203 |
|
|
Coro::SemaphoreSet, Coro::RWLock. |
204 |
|
|
|
205 |
|
|
Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket, |
206 |
|
|
Coro::Select. |
207 |
|
|
|
208 |
|
|
Embedding: <Coro:MakeMaker> |
209 |
root |
1.1 |
|
210 |
|
|
AUTHOR |
211 |
|
|
Marc Lehmann <schmorp@schmorp.de> |
212 |
|
|
http://home.schmorp.de/ |
213 |
|
|
|