ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Coro/README
(Generate patch)

Comparing Coro/README (file contents):
Revision 1.5 by root, Mon Dec 4 22:06:02 2006 UTC vs.
Revision 1.12 by root, Thu Oct 11 00:38:37 2007 UTC

… …
4SYNOPSIS 4SYNOPSIS
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
19DESCRIPTION 26DESCRIPTION
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 use din this module also guarentees you 29 The specific flavor of coroutine used in this module also guarantees you
23 that it will not switch between coroutines unless necessary, at 30 that it will not switch between coroutines unless necessary, at
24 easily-identified points in your program, so locking and parallel access 31 easily-identified points in your program, so locking and parallel access
25 are rarely an issue, making coroutine programming much safer than 32 are rarely an issue, making coroutine programming much safer than
26 threads programming. 33 threads programming.
27 34
… …
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)
42 The current coroutine (the last coroutine switched to). The initial 49 The current coroutine (the last coroutine switched to). The initial
43 value is $main (of course). 50 value is $main (of course).
44 51
45 This variable is strictly *read-only*. It is provided for 52 This variable is strictly *read-only*. It is provided for
46 performance reasons. If performance is not essentiel you are 53 performance reasons. If performance is not essential you are
47 encouraged to use the "Coro::current" function instead. 54 encouraged to use the "Coro::current" function instead.
48 55
49 $idle 56 $idle
50 A callback that is called whenever the scheduler finds no ready 57 A callback that is called whenever the scheduler finds no ready
51 coroutines to run. The default implementation prints "FATAL: 58 coroutines to run. The default implementation prints "FATAL:
… …
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.
70 78
71 Calling "exit" in a coroutine will not work correctly, so do not do 79 See the "Coro::State::new" constructor for info about the coroutine
72 that. 80 environment in which coroutines run.
73 81
74 When the coroutine dies, the program will exit, just as in the main 82 Calling "exit" in a coroutine will do the same as calling exit
75 program. 83 outside the coroutine. Likewise, when the coroutine dies, the
84 program will exit, just as it would in the main program.
76 85
77 # create a new coroutine that just prints its arguments 86 # create a new coroutine that just prints its arguments
78 async { 87 async {
79 print "@_\n"; 88 print "@_\n";
80 } 1,2,3,4; 89 } 1,2,3,4;
90
91 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 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
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 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.
81 120
82 schedule 121 schedule
83 Calls the scheduler. Please note that the current coroutine will not 122 Calls the scheduler. Please note that the current coroutine will not
84 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
85 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
… …
96 # wake up sleeping coroutine 135 # wake up sleeping coroutine
97 $current->ready; 136 $current->ready;
98 undef $current; 137 undef $current;
99 }; 138 };
100 139
101 # call schedule until event occured. 140 # call schedule until event occurred.
102 # in case we are woken up for other reasons 141 # in case we are woken up for other reasons
103 # (current still defined), loop. 142 # (current still defined), loop.
104 Coro::schedule while $current; 143 Coro::schedule while $current;
105 } 144 }
106 145
… …
108 "Cede" to other coroutines. This function puts the current coroutine 147 "Cede" to other coroutines. This function puts the current coroutine
109 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
110 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
111 higher priority. 150 higher priority.
112 151
152 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
113 terminate [arg...] 156 terminate [arg...]
114 Terminates the current coroutine with the given status values (see 157 Terminates the current coroutine with the given status values (see
115 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.
116 164
117 # dynamic methods 165 # dynamic methods
118 166
119 COROUTINE METHODS 167 COROUTINE METHODS
120 These are the methods you can call on coroutine objects. 168 These are the methods you can call on coroutine objects.
… …
123 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
124 coroutine automatically terminates as if "terminate" with the 172 coroutine automatically terminates as if "terminate" with the
125 returned values were called. To make the coroutine run you must 173 returned values were called. To make the coroutine run you must
126 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.
127 175
128 Calling "exit" in a coroutine will not work correctly, so do not do 176 See "async" and "Coro::State::new" for additional info about the
129 that. 177 coroutine environment.
130 178
131 $success = $coroutine->ready 179 $success = $coroutine->ready
132 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
133 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
134 queue, do nothing and return false. 182 queue, do nothing and return false.
… …
136 $is_ready = $coroutine->is_ready 184 $is_ready = $coroutine->is_ready
137 Return wether the coroutine is currently the ready queue or not, 185 Return wether the coroutine is currently the ready queue or not,
138 186
139 $coroutine->cancel (arg...) 187 $coroutine->cancel (arg...)
140 Terminates the given coroutine and makes it return the given 188 Terminates the given coroutine and makes it return the given
141 arguments as status (default: the empty list). 189 arguments as status (default: the empty list). Never returns if the
190 coroutine is the current coroutine.
142 191
143 $coroutine->join 192 $coroutine->join
144 Wait until the coroutine terminates and return any values given to 193 Wait until the coroutine terminates and return any values given to
145 the "terminate" or "cancel" functions. "join" can be called multiple 194 the "terminate" or "cancel" functions. "join" can be called
146 times from multiple coroutine. 195 concurrently from multiple coroutines.
196
197 $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.
147 201
148 $oldprio = $coroutine->prio ($newprio) 202 $oldprio = $coroutine->prio ($newprio)
149 Sets (or gets, if the argument is missing) the priority of the 203 Sets (or gets, if the argument is missing) the priority of the
150 coroutine. Higher priority coroutines get run before lower priority 204 coroutine. Higher priority coroutines get run before lower priority
151 coroutines. Priorities are small signed integers (currently -4 .. 205 coroutines. Priorities are small signed integers (currently -4 ..
… …
174 $olddesc = $coroutine->desc ($newdesc) 228 $olddesc = $coroutine->desc ($newdesc)
175 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
176 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
177 with a coroutine. 231 with a coroutine.
178 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.
250
179 GLOBAL FUNCTIONS 251 GLOBAL FUNCTIONS
180 Coro::nready 252 Coro::nready
181 Returns the number of coroutines that are currently in the ready 253 Returns the number of coroutines that are currently in the ready
182 state, i.e. that can be swicthed to. The value 0 means that the only 254 state, i.e. that can be switched to. The value 0 means that the only
183 runnable coroutine is the currently running one, so "cede" would 255 runnable coroutine is the currently running one, so "cede" would
184 have no effect, and "schedule" would cause a deadlock unless there 256 have no effect, and "schedule" would cause a deadlock unless there
185 is an idle handler that wakes up some coroutines. 257 is an idle handler that wakes up some coroutines.
258
259 my $guard = Coro::guard { ... }
260 This creates and returns a guard object. Nothing happens until the
261 object gets destroyed, in which case the codeblock given as argument
262 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 }
186 277
187 unblock_sub { ... } 278 unblock_sub { ... }
188 This utility function takes a BLOCK or code reference and "unblocks" 279 This utility function takes a BLOCK or code reference and "unblocks"
189 it, returning the new coderef. This means that the new coderef will 280 it, returning the new coderef. This means that the new coderef will
190 return immediately without blocking, returning nothing, while the 281 return immediately without blocking, returning nothing, while the
191 original code ref will be called (with parameters) from within its 282 original code ref will be called (with parameters) from within its
192 own coroutine. 283 own coroutine.
193 284
194 The reason this fucntion exists is that many event libraries (such 285 The reason this function exists is that many event libraries (such
195 as the venerable Event module) are not coroutine-safe (a weaker form 286 as the venerable Event module) are not coroutine-safe (a weaker form
196 of thread-safety). This means you must not block within event 287 of thread-safety). This means you must not block within event
197 callbacks, otherwise you might suffer from crashes or worse. 288 callbacks, otherwise you might suffer from crashes or worse.
198 289
199 This function allows your callbacks to block by executing them in 290 This function allows your callbacks to block by executing them in
… …
207BUGS/LIMITATIONS 298BUGS/LIMITATIONS
208 - you must make very sure that no coro is still active on global 299 - you must make very sure that no coro is still active on global
209 destruction. very bad things might happen otherwise (usually segfaults). 300 destruction. very bad things might happen otherwise (usually segfaults).
210 301
211 - this module is not thread-safe. You should only ever use this module 302 - this module is not thread-safe. You should only ever use this module
212 from the same thread (this requirement might be losened in the future 303 from the same thread (this requirement might be loosened in the future
213 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
214 this). 305 this).
215 306
216SEE ALSO 307SEE ALSO
308 Lower level Configuration, Coroutine Environment: Coro::State.
309
310 Debugging: Coro::Debug.
311
217 Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util. 312 Support/Utility: Coro::Specific, Coro::Util.
218 313
219 Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, 314 Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,
220 Coro::SemaphoreSet, Coro::RWLock. 315 Coro::SemaphoreSet, Coro::RWLock.
221 316
222 Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket, 317 Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket.
223 Coro::Select.
224 318
319 Compatibility: Coro::LWP, Coro::Storable, Coro::Select.
320
225 Embedding: <Coro:MakeMaker> 321 Embedding: <Coro:MakeMaker>.
226 322
227AUTHOR 323AUTHOR
228 Marc Lehmann <schmorp@schmorp.de> 324 Marc Lehmann <schmorp@schmorp.de>
229 http://home.schmorp.de/ 325 http://home.schmorp.de/
230 326

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines