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

Comparing Coro/README (file contents):
Revision 1.4 by root, Sun Dec 3 21:59:53 2006 UTC vs.
Revision 1.9 by root, Sat Sep 29 19:42:08 2007 UTC

… …
16 16
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. 21 threads but don't run in parallel at the same time even on SMP machines.
22 The specific flavor of coroutine used in this module also guarantees you
23 that it will not switch between coroutines unless necessary, at
24 easily-identified points in your program, so locking and parallel access
25 are rarely an issue, making coroutine programming much safer than
26 threads programming.
27
28 (Perl, however, does not natively support real threads but instead does
29 a very slow and memory-intensive emulation of processes using threads.
30 This is a performance win on Windows machines, and a loss everywhere
31 else).
22 32
23 In this module, coroutines are defined as "callchain + lexical variables 33 In this module, coroutines are defined as "callchain + lexical variables
24 + @_ + $_ + $@ + $^W + C stack), that is, a coroutine has it's own 34 + @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own
25 callchain, it's own set of lexicals and it's own set of perl's most 35 callchain, its own set of lexicals and its own set of perls most
26 important global variables. 36 important global variables.
27 37
28 $main 38 $main
29 This coroutine represents the main program. 39 This coroutine represents the main program.
30 40
31 $current (or as function: current) 41 $current (or as function: current)
32 The current coroutine (the last coroutine switched to). The initial 42 The current coroutine (the last coroutine switched to). The initial
33 value is $main (of course). 43 value is $main (of course).
34 44
35 This variable is strictly *read-only*. It is provided for 45 This variable is strictly *read-only*. It is provided for
36 performance reasons. If performance is not essentiel you are 46 performance reasons. If performance is not essential you are
37 encouraged to use the "Coro::current" function instead. 47 encouraged to use the "Coro::current" function instead.
38 48
39 $idle 49 $idle
40 A callback that is called whenever the scheduler finds no ready 50 A callback that is called whenever the scheduler finds no ready
41 coroutines to run. The default implementation prints "FATAL: 51 coroutines to run. The default implementation prints "FATAL:
… …
56 async { ... } [@args...] 66 async { ... } [@args...]
57 Create a new asynchronous coroutine and return it's coroutine object 67 Create a new asynchronous coroutine and return it's coroutine object
58 (usually unused). When the sub returns the new coroutine is 68 (usually unused). When the sub returns the new coroutine is
59 automatically terminated. 69 automatically terminated.
60 70
61 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
62 that. 72 outside the coroutine. Likewise, when the coroutine dies, the
63 73 program will exit, just as it would in the main program.
64 When the coroutine dies, the program will exit, just as in the main
65 program.
66 74
67 # create a new coroutine that just prints its arguments 75 # create a new coroutine that just prints its arguments
68 async { 76 async {
69 print "@_\n"; 77 print "@_\n";
70 } 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.
71 105
72 schedule 106 schedule
73 Calls the scheduler. Please note that the current coroutine will not 107 Calls the scheduler. Please note that the current coroutine will not
74 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
75 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 # wake up sleeping coroutine 120 # wake up sleeping coroutine
87 $current->ready; 121 $current->ready;
88 undef $current; 122 undef $current;
89 }; 123 };
90 124
91 # call schedule until event occured. 125 # call schedule until event occurred.
92 # in case we are woken up for other reasons 126 # in case we are woken up for other reasons
93 # (current still defined), loop. 127 # (current still defined), loop.
94 Coro::schedule while $current; 128 Coro::schedule while $current;
95 } 129 }
96 130
… …
98 "Cede" to other coroutines. This function puts the current coroutine 132 "Cede" to other coroutines. This function puts the current coroutine
99 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
100 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
101 higher priority. 135 higher priority.
102 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
103 terminate [arg...] 145 terminate [arg...]
104 Terminates the current coroutine with the given status values (see 146 Terminates the current coroutine with the given status values (see
105 cancel). 147 cancel).
106 148
107 # dynamic methods 149 # dynamic methods
… …
113 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
114 coroutine automatically terminates as if "terminate" with the 156 coroutine automatically terminates as if "terminate" with the
115 returned values were called. To make the coroutine run you must 157 returned values were called. To make the coroutine run you must
116 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.
117 159
118 Calling "exit" in a coroutine will not work correctly, so do not do 160 See "async" for additional discussion.
119 that.
120 161
121 $success = $coroutine->ready 162 $success = $coroutine->ready
122 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
123 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
124 queue, do nothing and return false. 165 queue, do nothing and return false.
… …
126 $is_ready = $coroutine->is_ready 167 $is_ready = $coroutine->is_ready
127 Return wether the coroutine is currently the ready queue or not, 168 Return wether the coroutine is currently the ready queue or not,
128 169
129 $coroutine->cancel (arg...) 170 $coroutine->cancel (arg...)
130 Terminates the given coroutine and makes it return the given 171 Terminates the given coroutine and makes it return the given
131 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.
132 174
133 $coroutine->join 175 $coroutine->join
134 Wait until the coroutine terminates and return any values given to 176 Wait until the coroutine terminates and return any values given to
135 the "terminate" or "cancel" functions. "join" can be called multiple 177 the "terminate" or "cancel" functions. "join" can be called multiple
136 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.
137 184
138 $oldprio = $coroutine->prio ($newprio) 185 $oldprio = $coroutine->prio ($newprio)
139 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
140 coroutine. Higher priority coroutines get run before lower priority 187 coroutine. Higher priority coroutines get run before lower priority
141 coroutines. Priorities are small signed integers (currently -4 .. 188 coroutines. Priorities are small signed integers (currently -4 ..
… …
164 $olddesc = $coroutine->desc ($newdesc) 211 $olddesc = $coroutine->desc ($newdesc)
165 Sets (or gets in case the argument is missing) the description for 212 Sets (or gets in case the argument is missing) the description for
166 this coroutine. This is just a free-form string you can associate 213 this coroutine. This is just a free-form string you can associate
167 with a coroutine. 214 with a coroutine.
168 215
169 UTILITY FUNCTIONS 216 GLOBAL FUNCTIONS
217 Coro::nready
218 Returns the number of coroutines that are currently in the ready
219 state, i.e. that can be switched to. The value 0 means that the only
220 runnable coroutine is the currently running one, so "cede" would
221 have no effect, and "schedule" would cause a deadlock unless there
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 }
242
170 unblock_sub { ... } 243 unblock_sub { ... }
171 This utility function takes a BLOCK or code reference and "unblocks" 244 This utility function takes a BLOCK or code reference and "unblocks"
172 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
173 return immediately without blocking, returning nothing, while the 246 return immediately without blocking, returning nothing, while the
174 original code ref will be called (with parameters) from within its 247 original code ref will be called (with parameters) from within its
175 own coroutine. 248 own coroutine.
176 249
177 The reason this fucntion exists is that many event libraries (such 250 The reason this function exists is that many event libraries (such
178 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
179 of thread-safety). This means you must not block within event 252 of thread-safety). This means you must not block within event
180 callbacks, otherwise you might suffer from crashes or worse. 253 callbacks, otherwise you might suffer from crashes or worse.
181 254
182 This function allows your callbacks to block by executing them in 255 This function allows your callbacks to block by executing them in
… …
190BUGS/LIMITATIONS 263BUGS/LIMITATIONS
191 - 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
192 destruction. very bad things might happen otherwise (usually segfaults). 265 destruction. very bad things might happen otherwise (usually segfaults).
193 266
194 - 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
195 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
196 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
197 this). 270 this).
198 271
199SEE ALSO 272SEE ALSO
200 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