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.9 by root, Sat Sep 29 19:42:08 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. In addition to that, when the stacks used by a handler
103 grows larger than 16kb (adjustable with $Coro::POOL_RSS) it will
104 also exit.
81 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
… …
96 # wake up sleeping coroutine 120 # wake up sleeping coroutine
97 $current->ready; 121 $current->ready;
98 undef $current; 122 undef $current;
99 }; 123 };
100 124
101 # call schedule until event occured. 125 # call schedule until event occurred.
102 # in case we are woken up for other reasons 126 # in case we are woken up for other reasons
103 # (current still defined), loop. 127 # (current still defined), loop.
104 Coro::schedule while $current; 128 Coro::schedule while $current;
105 } 129 }
106 130
… …
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
… …
123 Create a new coroutine and return it. When the sub returns the 155 Create a new coroutine and return it. When the sub returns the
124 coroutine automatically terminates as if "terminate" with the 156 coroutine automatically terminates as if "terminate" with the
125 returned values were called. To make the coroutine run you must 157 returned values were called. To make the coroutine run you must
126 first put it into the ready queue by calling the ready method. 158 first put it into the ready queue by calling the ready method.
127 159
128 Calling "exit" in a coroutine will not work correctly, so do not do 160 See "async" for additional discussion.
129 that.
130 161
131 $success = $coroutine->ready 162 $success = $coroutine->ready
132 Put the given coroutine into the ready queue (according to it's 163 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 164 priority) and return true. If the coroutine is already in the ready
134 queue, do nothing and return false. 165 queue, do nothing and return false.
… …
136 $is_ready = $coroutine->is_ready 167 $is_ready = $coroutine->is_ready
137 Return wether the coroutine is currently the ready queue or not, 168 Return wether the coroutine is currently the ready queue or not,
138 169
139 $coroutine->cancel (arg...) 170 $coroutine->cancel (arg...)
140 Terminates the given coroutine and makes it return the given 171 Terminates the given coroutine and makes it return the given
141 arguments as status (default: the empty list). 172 arguments as status (default: the empty list). Never returns if the
173 coroutine is the current coroutine.
142 174
143 $coroutine->join 175 $coroutine->join
144 Wait until the coroutine terminates and return any values given to 176 Wait until the coroutine terminates and return any values given to
145 the "terminate" or "cancel" functions. "join" can be called multiple 177 the "terminate" or "cancel" functions. "join" can be called multiple
146 times from multiple coroutine. 178 times from multiple coroutine.
179
180 $coroutine->on_destroy (\&cb)
181 Registers a callback that is called when this coroutine gets
182 destroyed, but before it is joined. The callback gets passed the
183 terminate arguments, if any.
147 184
148 $oldprio = $coroutine->prio ($newprio) 185 $oldprio = $coroutine->prio ($newprio)
149 Sets (or gets, if the argument is missing) the priority of the 186 Sets (or gets, if the argument is missing) the priority of the
150 coroutine. Higher priority coroutines get run before lower priority 187 coroutine. Higher priority coroutines get run before lower priority
151 coroutines. Priorities are small signed integers (currently -4 .. 188 coroutines. Priorities are small signed integers (currently -4 ..
… …
177 with a coroutine. 214 with a coroutine.
178 215
179 GLOBAL FUNCTIONS 216 GLOBAL FUNCTIONS
180 Coro::nready 217 Coro::nready
181 Returns the number of coroutines that are currently in the ready 218 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 219 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 220 runnable coroutine is the currently running one, so "cede" would
184 have no effect, and "schedule" would cause a deadlock unless there 221 have no effect, and "schedule" would cause a deadlock unless there
185 is an idle handler that wakes up some coroutines. 222 is an idle handler that wakes up some coroutines.
223
224 my $guard = Coro::guard { ... }
225 This creates and returns a guard object. Nothing happens until the
226 object gets destroyed, in which case the codeblock given as argument
227 will be executed. This is useful to free locks or other resources in
228 case of a runtime error or when the coroutine gets canceled, as in
229 both cases the guard block will be executed. The guard object
230 supports only one method, "->cancel", which will keep the codeblock
231 from being executed.
232
233 Example: set some flag and clear it again when the coroutine gets
234 canceled or the function returns:
235
236 sub do_something {
237 my $guard = Coro::guard { $busy = 0 };
238 $busy = 1;
239
240 # do something that requires $busy to be true
241 }
186 242
187 unblock_sub { ... } 243 unblock_sub { ... }
188 This utility function takes a BLOCK or code reference and "unblocks" 244 This utility function takes a BLOCK or code reference and "unblocks"
189 it, returning the new coderef. This means that the new coderef will 245 it, returning the new coderef. This means that the new coderef will
190 return immediately without blocking, returning nothing, while the 246 return immediately without blocking, returning nothing, while the
191 original code ref will be called (with parameters) from within its 247 original code ref will be called (with parameters) from within its
192 own coroutine. 248 own coroutine.
193 249
194 The reason this fucntion exists is that many event libraries (such 250 The reason this function exists is that many event libraries (such
195 as the venerable Event module) are not coroutine-safe (a weaker form 251 as the venerable Event module) are not coroutine-safe (a weaker form
196 of thread-safety). This means you must not block within event 252 of thread-safety). This means you must not block within event
197 callbacks, otherwise you might suffer from crashes or worse. 253 callbacks, otherwise you might suffer from crashes or worse.
198 254
199 This function allows your callbacks to block by executing them in 255 This function allows your callbacks to block by executing them in
… …
207BUGS/LIMITATIONS 263BUGS/LIMITATIONS
208 - you must make very sure that no coro is still active on global 264 - you must make very sure that no coro is still active on global
209 destruction. very bad things might happen otherwise (usually segfaults). 265 destruction. very bad things might happen otherwise (usually segfaults).
210 266
211 - this module is not thread-safe. You should only ever use this module 267 - 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 268 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 269 to allow per-thread schedulers, but Coro::State does not yet allow
214 this). 270 this).
215 271
216SEE ALSO 272SEE ALSO
217 Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util. 273 Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util.

Diff Legend

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