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.6 by root, Sat Jan 6 02:45:56 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 use din this module also guarentees 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
… …
66 76
67 # create a new coroutine that just prints its arguments 77 # create a new coroutine that just prints its arguments
68 async { 78 async {
69 print "@_\n"; 79 print "@_\n";
70 } 1,2,3,4; 80 } 1,2,3,4;
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.
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
… …
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
… …
126 $is_ready = $coroutine->is_ready 168 $is_ready = $coroutine->is_ready
127 Return wether the coroutine is currently the ready queue or not, 169 Return wether the coroutine is currently the ready queue or not,
128 170
129 $coroutine->cancel (arg...) 171 $coroutine->cancel (arg...)
130 Terminates the given coroutine and makes it return the given 172 Terminates the given coroutine and makes it return the given
131 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.
132 175
133 $coroutine->join 176 $coroutine->join
134 Wait until the coroutine terminates and return any values given to 177 Wait until the coroutine terminates and return any values given to
135 the "terminate" or "cancel" functions. "join" can be called multiple 178 the "terminate" or "cancel" functions. "join" can be called multiple
136 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.
137 185
138 $oldprio = $coroutine->prio ($newprio) 186 $oldprio = $coroutine->prio ($newprio)
139 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
140 coroutine. Higher priority coroutines get run before lower priority 188 coroutine. Higher priority coroutines get run before lower priority
141 coroutines. Priorities are small signed integers (currently -4 .. 189 coroutines. Priorities are small signed integers (currently -4 ..
… …
164 $olddesc = $coroutine->desc ($newdesc) 212 $olddesc = $coroutine->desc ($newdesc)
165 Sets (or gets in case the argument is missing) the description for 213 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 214 this coroutine. This is just a free-form string you can associate
167 with a coroutine. 215 with a coroutine.
168 216
169 UTILITY FUNCTIONS 217 GLOBAL FUNCTIONS
218 Coro::nready
219 Returns the number of coroutines that are currently in the ready
220 state, i.e. that can be swicthed to. The value 0 means that the only
221 runnable coroutine is the currently running one, so "cede" would
222 have no effect, and "schedule" would cause a deadlock unless there
223 is an idle handler that wakes up some coroutines.
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
170 unblock_sub { ... } 244 unblock_sub { ... }
171 This utility function takes a BLOCK or code reference and "unblocks" 245 This utility function takes a BLOCK or code reference and "unblocks"
172 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
173 return immediately without blocking, returning nothing, while the 247 return immediately without blocking, returning nothing, while the
174 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