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.8 by root, Thu Apr 19 10:37:26 2007 UTC

… …
17 cede; 17 cede;
18 18
19DESCRIPTION 19DESCRIPTION
20 This module collection manages coroutines. Coroutines are similar to 20 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. 21 threads but don't run in parallel at the same time even on SMP machines.
22 The specific flavor of coroutine use din this module also guarentees you 22 The specific flavor of coroutine used in this module also guarantees you
23 that it will not switch between coroutines unless necessary, at 23 that it will not switch between coroutines unless necessary, at
24 easily-identified points in your program, so locking and parallel access 24 easily-identified points in your program, so locking and parallel access
25 are rarely an issue, making coroutine programming much safer than 25 are rarely an issue, making coroutine programming much safer than
26 threads programming. 26 threads programming.
27 27
… …
41 $current (or as function: current) 41 $current (or as function: current)
42 The current coroutine (the last coroutine switched to). The initial 42 The current coroutine (the last coroutine switched to). The initial
43 value is $main (of course). 43 value is $main (of course).
44 44
45 This variable is strictly *read-only*. It is provided for 45 This variable is strictly *read-only*. It is provided for
46 performance reasons. If performance is not essentiel you are 46 performance reasons. If performance is not essential you are
47 encouraged to use the "Coro::current" function instead. 47 encouraged to use the "Coro::current" function instead.
48 48
49 $idle 49 $idle
50 A callback that is called whenever the scheduler finds no ready 50 A callback that is called whenever the scheduler finds no ready
51 coroutines to run. The default implementation prints "FATAL: 51 coroutines to run. The default implementation prints "FATAL:
… …
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
… …
96 # wake up sleeping coroutine 118 # wake up sleeping coroutine
97 $current->ready; 119 $current->ready;
98 undef $current; 120 undef $current;
99 }; 121 };
100 122
101 # call schedule until event occured. 123 # call schedule until event occurred.
102 # in case we are woken up for other reasons 124 # in case we are woken up for other reasons
103 # (current still defined), loop. 125 # (current still defined), loop.
104 Coro::schedule while $current; 126 Coro::schedule while $current;
105 } 127 }
106 128
… …
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 ..
… …
177 with a coroutine. 212 with a coroutine.
178 213
179 GLOBAL FUNCTIONS 214 GLOBAL FUNCTIONS
180 Coro::nready 215 Coro::nready
181 Returns the number of coroutines that are currently in the ready 216 Returns the number of coroutines that are currently in the ready
182 state, i.e. that can be swicthed to. The value 0 means that the only 217 state, i.e. that can be switched 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.
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 }
186 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
192 own coroutine. 246 own coroutine.
193 247
194 The reason this fucntion exists is that many event libraries (such 248 The reason this function exists is that many event libraries (such
195 as the venerable Event module) are not coroutine-safe (a weaker form 249 as the venerable Event module) are not coroutine-safe (a weaker form
196 of thread-safety). This means you must not block within event 250 of thread-safety). This means you must not block within event
197 callbacks, otherwise you might suffer from crashes or worse. 251 callbacks, otherwise you might suffer from crashes or worse.
198 252
199 This function allows your callbacks to block by executing them in 253 This function allows your callbacks to block by executing them in
… …
207BUGS/LIMITATIONS 261BUGS/LIMITATIONS
208 - you must make very sure that no coro is still active on global 262 - you must make very sure that no coro is still active on global
209 destruction. very bad things might happen otherwise (usually segfaults). 263 destruction. very bad things might happen otherwise (usually segfaults).
210 264
211 - this module is not thread-safe. You should only ever use this module 265 - this module is not thread-safe. You should only ever use this module
212 from the same thread (this requirement might be losened in the future 266 from the same thread (this requirement might be loosened in the future
213 to allow per-thread schedulers, but Coro::State does not yet allow 267 to allow per-thread schedulers, but Coro::State does not yet allow
214 this). 268 this).
215 269
216SEE ALSO 270SEE ALSO
217 Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util. 271 Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util.

Diff Legend

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