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

Comparing Coro/README (file contents):
Revision 1.9 by root, Sat Sep 29 19:42:08 2007 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 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
… …
132 "Cede" to other coroutines. This function puts the current coroutine 147 "Cede" to other coroutines. This function puts the current coroutine
133 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
134 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
135 higher priority. 150 higher priority.
136 151
137 Returns true if at least one coroutine switch has happened.
138
139 Coro::cede_notself 152 Coro::cede_notself
140 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
141 coroutine, regardless of priority, once. 154 coroutine, regardless of priority, once.
142 155
143 Returns true if at least one coroutine switch has happened.
144
145 terminate [arg...] 156 terminate [arg...]
146 Terminates the current coroutine with the given status values (see 157 Terminates the current coroutine with the given status values (see
147 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.
148 164
149 # dynamic methods 165 # dynamic methods
150 166
151 COROUTINE METHODS 167 COROUTINE METHODS
152 These are the methods you can call on coroutine objects. 168 These are the methods you can call on coroutine objects.
… …
155 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
156 coroutine automatically terminates as if "terminate" with the 172 coroutine automatically terminates as if "terminate" with the
157 returned values were called. To make the coroutine run you must 173 returned values were called. To make the coroutine run you must
158 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.
159 175
160 See "async" for additional discussion. 176 See "async" and "Coro::State::new" for additional info about the
177 coroutine environment.
161 178
162 $success = $coroutine->ready 179 $success = $coroutine->ready
163 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
164 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
165 queue, do nothing and return false. 182 queue, do nothing and return false.
… …
172 arguments as status (default: the empty list). Never returns if the 189 arguments as status (default: the empty list). Never returns if the
173 coroutine is the current coroutine. 190 coroutine is the current coroutine.
174 191
175 $coroutine->join 192 $coroutine->join
176 Wait until the coroutine terminates and return any values given to 193 Wait until the coroutine terminates and return any values given to
177 the "terminate" or "cancel" functions. "join" can be called multiple 194 the "terminate" or "cancel" functions. "join" can be called
178 times from multiple coroutine. 195 concurrently from multiple coroutines.
179 196
180 $coroutine->on_destroy (\&cb) 197 $coroutine->on_destroy (\&cb)
181 Registers a callback that is called when this coroutine gets 198 Registers a callback that is called when this coroutine gets
182 destroyed, but before it is joined. The callback gets passed the 199 destroyed, but before it is joined. The callback gets passed the
183 terminate arguments, if any. 200 terminate arguments, if any.
… …
210 227
211 $olddesc = $coroutine->desc ($newdesc) 228 $olddesc = $coroutine->desc ($newdesc)
212 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
213 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
214 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.
215 250
216 GLOBAL FUNCTIONS 251 GLOBAL FUNCTIONS
217 Coro::nready 252 Coro::nready
218 Returns the number of coroutines that are currently in the ready 253 Returns the number of coroutines that are currently in the ready
219 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
… …
268 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
269 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
270 this). 305 this).
271 306
272SEE ALSO 307SEE ALSO
308 Lower level Configuration, Coroutine Environment: Coro::State.
309
310 Debugging: Coro::Debug.
311
273 Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util. 312 Support/Utility: Coro::Specific, Coro::Util.
274 313
275 Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, 314 Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,
276 Coro::SemaphoreSet, Coro::RWLock. 315 Coro::SemaphoreSet, Coro::RWLock.
277 316
278 Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket, 317 Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket.
279 Coro::Select.
280 318
319 Compatibility: Coro::LWP, Coro::Storable, Coro::Select.
320
281 Embedding: <Coro:MakeMaker> 321 Embedding: <Coro:MakeMaker>.
282 322
283AUTHOR 323AUTHOR
284 Marc Lehmann <schmorp@schmorp.de> 324 Marc Lehmann <schmorp@schmorp.de>
285 http://home.schmorp.de/ 325 http://home.schmorp.de/
286 326

Diff Legend

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