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.10 by root, Fri Oct 5 10:57:40 2007 UTC

… …
66 async { ... } [@args...] 66 async { ... } [@args...]
67 Create a new asynchronous coroutine and return it's coroutine object 67 Create a new asynchronous coroutine and return it's coroutine object
68 (usually unused). When the sub returns the new coroutine is 68 (usually unused). When the sub returns the new coroutine is
69 automatically terminated. 69 automatically terminated.
70 70
71 See the "Coro::State::new" constructor for info about the coroutine
72 environment.
73
71 Calling "exit" in a coroutine will do the same as calling exit 74 Calling "exit" in a coroutine will do the same as calling exit
72 outside the coroutine. Likewise, when the coroutine dies, the 75 outside the coroutine. Likewise, when the coroutine dies, the
73 program will exit, just as it would in the main program. 76 program will exit, just as it would in the main program.
74 77
75 # create a new coroutine that just prints its arguments 78 # create a new coroutine that just prints its arguments
… …
87 be issued in case of an exception instead of terminating the 90 be issued in case of an exception instead of terminating the
88 program, as "async" does. As the coroutine is being reused, stuff 91 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 92 like "on_destroy" will not work in the expected way, unless you call
90 terminate or cancel, which somehow defeats the purpose of pooling. 93 terminate or cancel, which somehow defeats the purpose of pooling.
91 94
92 The priority will be reset to 0 after each job, otherwise the 95 The priority will be reset to 0 after each job, tracing will be
93 coroutine will be re-used "as-is". 96 disabled, the description will be reset and the default output
97 filehandle gets restored, so you can change alkl these. Otherwise
98 the coroutine will be re-used "as-is": most notably if you change
99 other per-coroutine global stuff such as $/ you need to revert that
100 change, which is most simply done by using local as in " local $/ ".
94 101
95 The pool size is limited to 8 idle coroutines (this can be adjusted 102 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 103 by changing $Coro::POOL_SIZE), and there can be as many non-idle
97 coros as required. 104 coros as required.
98 105
… …
144 151
145 terminate [arg...] 152 terminate [arg...]
146 Terminates the current coroutine with the given status values (see 153 Terminates the current coroutine with the given status values (see
147 cancel). 154 cancel).
148 155
156 killall
157 Kills/terminates/cancels all coroutines except the currently running
158 one. This is useful after a fork, either in the child or the parent,
159 as usually only one of them should inherit the running coroutines.
160
149 # dynamic methods 161 # dynamic methods
150 162
151 COROUTINE METHODS 163 COROUTINE METHODS
152 These are the methods you can call on coroutine objects. 164 These are the methods you can call on coroutine objects.
153 165
… …
155 Create a new coroutine and return it. When the sub returns the 167 Create a new coroutine and return it. When the sub returns the
156 coroutine automatically terminates as if "terminate" with the 168 coroutine automatically terminates as if "terminate" with the
157 returned values were called. To make the coroutine run you must 169 returned values were called. To make the coroutine run you must
158 first put it into the ready queue by calling the ready method. 170 first put it into the ready queue by calling the ready method.
159 171
160 See "async" for additional discussion. 172 See "async" and "Coro::State::new" for additional info about the
173 coroutine environment.
161 174
162 $success = $coroutine->ready 175 $success = $coroutine->ready
163 Put the given coroutine into the ready queue (according to it's 176 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 177 priority) and return true. If the coroutine is already in the ready
165 queue, do nothing and return false. 178 queue, do nothing and return false.
… …
172 arguments as status (default: the empty list). Never returns if the 185 arguments as status (default: the empty list). Never returns if the
173 coroutine is the current coroutine. 186 coroutine is the current coroutine.
174 187
175 $coroutine->join 188 $coroutine->join
176 Wait until the coroutine terminates and return any values given to 189 Wait until the coroutine terminates and return any values given to
177 the "terminate" or "cancel" functions. "join" can be called multiple 190 the "terminate" or "cancel" functions. "join" can be called
178 times from multiple coroutine. 191 concurrently from multiple coroutines.
179 192
180 $coroutine->on_destroy (\&cb) 193 $coroutine->on_destroy (\&cb)
181 Registers a callback that is called when this coroutine gets 194 Registers a callback that is called when this coroutine gets
182 destroyed, but before it is joined. The callback gets passed the 195 destroyed, but before it is joined. The callback gets passed the
183 terminate arguments, if any. 196 terminate arguments, if any.
… …
210 223
211 $olddesc = $coroutine->desc ($newdesc) 224 $olddesc = $coroutine->desc ($newdesc)
212 Sets (or gets in case the argument is missing) the description for 225 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 226 this coroutine. This is just a free-form string you can associate
214 with a coroutine. 227 with a coroutine.
228
229 This method simply sets the "$coroutine->{desc}" member to the given
230 string. You can modify this member directly if you wish.
215 231
216 GLOBAL FUNCTIONS 232 GLOBAL FUNCTIONS
217 Coro::nready 233 Coro::nready
218 Returns the number of coroutines that are currently in the ready 234 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 235 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 284 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 285 to allow per-thread schedulers, but Coro::State does not yet allow
270 this). 286 this).
271 287
272SEE ALSO 288SEE ALSO
273 Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util. 289 Support/Utility: Coro::Specific, Coro::State, Coro::Util.
274 290
275 Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, 291 Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,
276 Coro::SemaphoreSet, Coro::RWLock. 292 Coro::SemaphoreSet, Coro::RWLock.
277 293
278 Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket, 294 Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket,

Diff Legend

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