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

Comparing cvsroot/Coro/README (file contents):
Revision 1.5 by root, Mon Dec 4 22:06:02 2006 UTC vs.
Revision 1.7 by root, Mon Apr 16 13:26:43 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 Calling "exit" in a coroutine will not work correctly, so do not do 71 Calling "exit" in a coroutine will do the same as calling exit
72 that. 72 outside the coroutine. Likewise, when the coroutine dies, the
73 73 program will exit, just as it would in the main program.
74 When the coroutine dies, the program will exit, just as in the main
75 program.
76 74
77 # create a new coroutine that just prints its arguments 75 # create a new coroutine that just prints its arguments
78 async { 76 async {
79 print "@_\n"; 77 print "@_\n";
80 } 1,2,3,4; 78 } 1,2,3,4;
79
80 async_pool { ... } [@args...]
81 Similar to "async", but uses a coroutine pool, so you should not
82 call terminate or join (although you are allowed to), and you get a
83 coroutine that might have executed other code already (which can be
84 good or bad :).
85
86 Also, the block is executed in an "eval" context and a warning will
87 be issued in case of an exception instead of terminating the
88 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
90 terminate or cancel, which somehow defeats the purpose of pooling.
91
92 The priority will be reset to 0 after each job, otherwise the
93 coroutine will be re-used "as-is".
94
95 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
97 coros as required.
98
99 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.
101 "async_pool { terminate }" once per second or so to slowly replenish
102 the pool.
81 103
82 schedule 104 schedule
83 Calls the scheduler. Please note that the current coroutine will not 105 Calls the scheduler. Please note that the current coroutine will not
84 be put into the ready queue, so calling this function usually means 106 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 107 you will never be called again unless something else (e.g. an event
… …
108 "Cede" to other coroutines. This function puts the current coroutine 130 "Cede" to other coroutines. This function puts the current coroutine
109 into the ready queue and calls "schedule", which has the effect of 131 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 132 giving up the current "timeslice" to other coroutines of the same or
111 higher priority. 133 higher priority.
112 134
135 Returns true if at least one coroutine switch has happened.
136
137 Coro::cede_notself
138 Works like cede, but is not exported by default and will cede to any
139 coroutine, regardless of priority, once.
140
141 Returns true if at least one coroutine switch has happened.
142
113 terminate [arg...] 143 terminate [arg...]
114 Terminates the current coroutine with the given status values (see 144 Terminates the current coroutine with the given status values (see
115 cancel). 145 cancel).
116 146
117 # dynamic methods 147 # dynamic methods
… …
123 Create a new coroutine and return it. When the sub returns the 153 Create a new coroutine and return it. When the sub returns the
124 coroutine automatically terminates as if "terminate" with the 154 coroutine automatically terminates as if "terminate" with the
125 returned values were called. To make the coroutine run you must 155 returned values were called. To make the coroutine run you must
126 first put it into the ready queue by calling the ready method. 156 first put it into the ready queue by calling the ready method.
127 157
128 Calling "exit" in a coroutine will not work correctly, so do not do 158 See "async" for additional discussion.
129 that.
130 159
131 $success = $coroutine->ready 160 $success = $coroutine->ready
132 Put the given coroutine into the ready queue (according to it's 161 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 162 priority) and return true. If the coroutine is already in the ready
134 queue, do nothing and return false. 163 queue, do nothing and return false.
… …
136 $is_ready = $coroutine->is_ready 165 $is_ready = $coroutine->is_ready
137 Return wether the coroutine is currently the ready queue or not, 166 Return wether the coroutine is currently the ready queue or not,
138 167
139 $coroutine->cancel (arg...) 168 $coroutine->cancel (arg...)
140 Terminates the given coroutine and makes it return the given 169 Terminates the given coroutine and makes it return the given
141 arguments as status (default: the empty list). 170 arguments as status (default: the empty list). Never returns if the
171 coroutine is the current coroutine.
142 172
143 $coroutine->join 173 $coroutine->join
144 Wait until the coroutine terminates and return any values given to 174 Wait until the coroutine terminates and return any values given to
145 the "terminate" or "cancel" functions. "join" can be called multiple 175 the "terminate" or "cancel" functions. "join" can be called multiple
146 times from multiple coroutine. 176 times from multiple coroutine.
177
178 $coroutine->on_destroy (\&cb)
179 Registers a callback that is called when this coroutine gets
180 destroyed, but before it is joined. The callback gets passed the
181 terminate arguments, if any.
147 182
148 $oldprio = $coroutine->prio ($newprio) 183 $oldprio = $coroutine->prio ($newprio)
149 Sets (or gets, if the argument is missing) the priority of the 184 Sets (or gets, if the argument is missing) the priority of the
150 coroutine. Higher priority coroutines get run before lower priority 185 coroutine. Higher priority coroutines get run before lower priority
151 coroutines. Priorities are small signed integers (currently -4 .. 186 coroutines. Priorities are small signed integers (currently -4 ..
… …
182 state, i.e. that can be swicthed to. The value 0 means that the only 217 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 218 runnable coroutine is the currently running one, so "cede" would
184 have no effect, and "schedule" would cause a deadlock unless there 219 have no effect, and "schedule" would cause a deadlock unless there
185 is an idle handler that wakes up some coroutines. 220 is an idle handler that wakes up some coroutines.
186 221
222 my $guard = Coro::guard { ... }
223 This creates and returns a guard object. Nothing happens until the
224 object gets destroyed, in which case the codeblock given as argument
225 will be executed. This is useful to free locks or other resources in
226 case of a runtime error or when the coroutine gets canceled, as in
227 both cases the guard block will be executed. The guard object
228 supports only one method, "->cancel", which will keep the codeblock
229 from being executed.
230
231 Example: set some flag and clear it again when the coroutine gets
232 canceled or the function returns:
233
234 sub do_something {
235 my $guard = Coro::guard { $busy = 0 };
236 $busy = 1;
237
238 # do something that requires $busy to be true
239 }
240
187 unblock_sub { ... } 241 unblock_sub { ... }
188 This utility function takes a BLOCK or code reference and "unblocks" 242 This utility function takes a BLOCK or code reference and "unblocks"
189 it, returning the new coderef. This means that the new coderef will 243 it, returning the new coderef. This means that the new coderef will
190 return immediately without blocking, returning nothing, while the 244 return immediately without blocking, returning nothing, while the
191 original code ref will be called (with parameters) from within its 245 original code ref will be called (with parameters) from within its

Diff Legend

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