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.6 by root, Sat Jan 6 02:45:56 2007 UTC

… …
77 # create a new coroutine that just prints its arguments 77 # create a new coroutine that just prints its arguments
78 async { 78 async {
79 print "@_\n"; 79 print "@_\n";
80 } 1,2,3,4; 80 } 1,2,3,4;
81 81
82 async_pool { ... } [@args...]
83 Similar to "async", but uses a coroutine pool, so you should not
84 call terminate or join (although you are allowed to), and you get a
85 coroutine that might have executed other code already (which can be
86 good or bad :).
87
88 Also, the block is executed in an "eval" context and a warning will
89 be issued in case of an exception instead of terminating the
90 program, as "async" does. As the coroutine is being reused, stuff
91 like "on_destroy" will not work in the expected way, unless you call
92 terminate or cancel, which somehow defeats the purpose of pooling.
93
94 The priority will be reset to 0 after each job, otherwise the
95 coroutine will be re-used "as-is".
96
97 The pool size is limited to 8 idle coroutines (this can be adjusted
98 by changing $Coro::POOL_SIZE), and there can be as many non-idle
99 coros as required.
100
101 If you are concerned about pooled coroutines growing a lot because a
102 single "async_pool" used a lot of stackspace you can e.g.
103 "async_pool { terminate }" once per second or so to slowly replenish
104 the pool.
105
82 schedule 106 schedule
83 Calls the scheduler. Please note that the current coroutine will not 107 Calls the scheduler. Please note that the current coroutine will not
84 be put into the ready queue, so calling this function usually means 108 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 109 you will never be called again unless something else (e.g. an event
86 handler) calls ready. 110 handler) calls ready.
… …
108 "Cede" to other coroutines. This function puts the current coroutine 132 "Cede" to other coroutines. This function puts the current coroutine
109 into the ready queue and calls "schedule", which has the effect of 133 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 134 giving up the current "timeslice" to other coroutines of the same or
111 higher priority. 135 higher priority.
112 136
137 Returns true if at least one coroutine switch has happened.
138
139 Coro::cede_notself
140 Works like cede, but is not exported by default and will cede to any
141 coroutine, regardless of priority, once.
142
143 Returns true if at least one coroutine switch has happened.
144
113 terminate [arg...] 145 terminate [arg...]
114 Terminates the current coroutine with the given status values (see 146 Terminates the current coroutine with the given status values (see
115 cancel). 147 cancel).
116 148
117 # dynamic methods 149 # dynamic methods
… …
136 $is_ready = $coroutine->is_ready 168 $is_ready = $coroutine->is_ready
137 Return wether the coroutine is currently the ready queue or not, 169 Return wether the coroutine is currently the ready queue or not,
138 170
139 $coroutine->cancel (arg...) 171 $coroutine->cancel (arg...)
140 Terminates the given coroutine and makes it return the given 172 Terminates the given coroutine and makes it return the given
141 arguments as status (default: the empty list). 173 arguments as status (default: the empty list). Never returns if the
174 coroutine is the current coroutine.
142 175
143 $coroutine->join 176 $coroutine->join
144 Wait until the coroutine terminates and return any values given to 177 Wait until the coroutine terminates and return any values given to
145 the "terminate" or "cancel" functions. "join" can be called multiple 178 the "terminate" or "cancel" functions. "join" can be called multiple
146 times from multiple coroutine. 179 times from multiple coroutine.
180
181 $coroutine->on_destroy (\&cb)
182 Registers a callback that is called when this coroutine gets
183 destroyed, but before it is joined. The callback gets passed the
184 terminate arguments, if any.
147 185
148 $oldprio = $coroutine->prio ($newprio) 186 $oldprio = $coroutine->prio ($newprio)
149 Sets (or gets, if the argument is missing) the priority of the 187 Sets (or gets, if the argument is missing) the priority of the
150 coroutine. Higher priority coroutines get run before lower priority 188 coroutine. Higher priority coroutines get run before lower priority
151 coroutines. Priorities are small signed integers (currently -4 .. 189 coroutines. Priorities are small signed integers (currently -4 ..
… …
182 state, i.e. that can be swicthed to. The value 0 means that the only 220 state, i.e. that can be swicthed to. The value 0 means that the only
183 runnable coroutine is the currently running one, so "cede" would 221 runnable coroutine is the currently running one, so "cede" would
184 have no effect, and "schedule" would cause a deadlock unless there 222 have no effect, and "schedule" would cause a deadlock unless there
185 is an idle handler that wakes up some coroutines. 223 is an idle handler that wakes up some coroutines.
186 224
225 my $guard = Coro::guard { ... }
226 This creates and returns a guard object. Nothing happens until the
227 objetc gets destroyed, in which case the codeblock given as argument
228 will be executed. This is useful to free locks or other resources in
229 case of a runtime error or when the coroutine gets canceled, as in
230 both cases the guard block will be executed. The guard object
231 supports only one method, "->cancel", which will keep the codeblock
232 from being executed.
233
234 Example: set some flag and clear it again when the coroutine gets
235 canceled or the function returns:
236
237 sub do_something {
238 my $guard = Coro::guard { $busy = 0 };
239 $busy = 1;
240
241 # do something that requires $busy to be true
242 }
243
187 unblock_sub { ... } 244 unblock_sub { ... }
188 This utility function takes a BLOCK or code reference and "unblocks" 245 This utility function takes a BLOCK or code reference and "unblocks"
189 it, returning the new coderef. This means that the new coderef will 246 it, returning the new coderef. This means that the new coderef will
190 return immediately without blocking, returning nothing, while the 247 return immediately without blocking, returning nothing, while the
191 original code ref will be called (with parameters) from within its 248 original code ref will be called (with parameters) from within its

Diff Legend

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