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

Comparing Coro/README (file contents):
Revision 1.8 by root, Thu Apr 19 10:37:26 2007 UTC vs.
Revision 1.11 by root, Sat Oct 6 19:25:00 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
99 If you are concerned about pooled coroutines growing a lot because a 106 If you are concerned about pooled coroutines growing a lot because a
100 single "async_pool" used a lot of stackspace you can e.g. 107 single "async_pool" used a lot of stackspace you can e.g.
101 "async_pool { terminate }" once per second or so to slowly replenish 108 "async_pool { terminate }" once per second or so to slowly replenish
102 the pool. 109 the pool. In addition to that, when the stacks used by a handler
110 grows larger than 16kb (adjustable with $Coro::POOL_RSS) it will
111 also exit.
103 112
104 schedule 113 schedule
105 Calls the scheduler. Please note that the current coroutine will not 114 Calls the scheduler. Please note that the current coroutine will not
106 be put into the ready queue, so calling this function usually means 115 be put into the ready queue, so calling this function usually means
107 you will never be called again unless something else (e.g. an event 116 you will never be called again unless something else (e.g. an event
… …
142 151
143 terminate [arg...] 152 terminate [arg...]
144 Terminates the current coroutine with the given status values (see 153 Terminates the current coroutine with the given status values (see
145 cancel). 154 cancel).
146 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
147 # dynamic methods 161 # dynamic methods
148 162
149 COROUTINE METHODS 163 COROUTINE METHODS
150 These are the methods you can call on coroutine objects. 164 These are the methods you can call on coroutine objects.
151 165
… …
153 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
154 coroutine automatically terminates as if "terminate" with the 168 coroutine automatically terminates as if "terminate" with the
155 returned values were called. To make the coroutine run you must 169 returned values were called. To make the coroutine run you must
156 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.
157 171
158 See "async" for additional discussion. 172 See "async" and "Coro::State::new" for additional info about the
173 coroutine environment.
159 174
160 $success = $coroutine->ready 175 $success = $coroutine->ready
161 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
162 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
163 queue, do nothing and return false. 178 queue, do nothing and return false.
… …
170 arguments as status (default: the empty list). Never returns if the 185 arguments as status (default: the empty list). Never returns if the
171 coroutine is the current coroutine. 186 coroutine is the current coroutine.
172 187
173 $coroutine->join 188 $coroutine->join
174 Wait until the coroutine terminates and return any values given to 189 Wait until the coroutine terminates and return any values given to
175 the "terminate" or "cancel" functions. "join" can be called multiple 190 the "terminate" or "cancel" functions. "join" can be called
176 times from multiple coroutine. 191 concurrently from multiple coroutines.
177 192
178 $coroutine->on_destroy (\&cb) 193 $coroutine->on_destroy (\&cb)
179 Registers a callback that is called when this coroutine gets 194 Registers a callback that is called when this coroutine gets
180 destroyed, but before it is joined. The callback gets passed the 195 destroyed, but before it is joined. The callback gets passed the
181 terminate arguments, if any. 196 terminate arguments, if any.
… …
208 223
209 $olddesc = $coroutine->desc ($newdesc) 224 $olddesc = $coroutine->desc ($newdesc)
210 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
211 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
212 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.
231
232 $coroutine->throw ([$scalar])
233 If $throw is specified and defined, it will be thrown as an
234 exception inside the coroutine at the next convinient point in time
235 (usually after it gains control at the next schedule/transfer/cede).
236 Otherwise clears the exception object.
237
238 The exception object will be thrown "as is" with the specified
239 scalar in $@, i.e. if it is a string, no line number or newline will
240 be appended (unlike with "die").
241
242 This can be used as a softer means than "cancel" to ask a coroutine
243 to end itself, although there is no guarentee that the exception
244 will lead to termination, and if the exception isn't caught it might
245 well end the whole program.
213 246
214 GLOBAL FUNCTIONS 247 GLOBAL FUNCTIONS
215 Coro::nready 248 Coro::nready
216 Returns the number of coroutines that are currently in the ready 249 Returns the number of coroutines that are currently in the ready
217 state, i.e. that can be switched to. The value 0 means that the only 250 state, i.e. that can be switched to. The value 0 means that the only
… …
266 from the same thread (this requirement might be loosened in the future 299 from the same thread (this requirement might be loosened in the future
267 to allow per-thread schedulers, but Coro::State does not yet allow 300 to allow per-thread schedulers, but Coro::State does not yet allow
268 this). 301 this).
269 302
270SEE ALSO 303SEE ALSO
271 Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util. 304 Support/Utility: Coro::Specific, Coro::State, Coro::Util.
272 305
273 Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, 306 Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore,
274 Coro::SemaphoreSet, Coro::RWLock. 307 Coro::SemaphoreSet, Coro::RWLock.
275 308
276 Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket, 309 Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket,

Diff Legend

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