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.7 by root, Mon Apr 16 13:26:43 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
… …
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.
71 103
72 schedule 104 schedule
73 Calls the scheduler. Please note that the current coroutine will not 105 Calls the scheduler. Please note that the current coroutine will not
74 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
75 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
… …
98 "Cede" to other coroutines. This function puts the current coroutine 130 "Cede" to other coroutines. This function puts the current coroutine
99 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
100 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
101 higher priority. 133 higher priority.
102 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
103 terminate [arg...] 143 terminate [arg...]
104 Terminates the current coroutine with the given status values (see 144 Terminates the current coroutine with the given status values (see
105 cancel). 145 cancel).
106 146
107 # dynamic methods 147 # dynamic methods
… …
113 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
114 coroutine automatically terminates as if "terminate" with the 154 coroutine automatically terminates as if "terminate" with the
115 returned values were called. To make the coroutine run you must 155 returned values were called. To make the coroutine run you must
116 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.
117 157
118 Calling "exit" in a coroutine will not work correctly, so do not do 158 See "async" for additional discussion.
119 that.
120 159
121 $success = $coroutine->ready 160 $success = $coroutine->ready
122 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
123 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
124 queue, do nothing and return false. 163 queue, do nothing and return false.
… …
126 $is_ready = $coroutine->is_ready 165 $is_ready = $coroutine->is_ready
127 Return wether the coroutine is currently the ready queue or not, 166 Return wether the coroutine is currently the ready queue or not,
128 167
129 $coroutine->cancel (arg...) 168 $coroutine->cancel (arg...)
130 Terminates the given coroutine and makes it return the given 169 Terminates the given coroutine and makes it return the given
131 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.
132 172
133 $coroutine->join 173 $coroutine->join
134 Wait until the coroutine terminates and return any values given to 174 Wait until the coroutine terminates and return any values given to
135 the "terminate" or "cancel" functions. "join" can be called multiple 175 the "terminate" or "cancel" functions. "join" can be called multiple
136 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.
137 182
138 $oldprio = $coroutine->prio ($newprio) 183 $oldprio = $coroutine->prio ($newprio)
139 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
140 coroutine. Higher priority coroutines get run before lower priority 185 coroutine. Higher priority coroutines get run before lower priority
141 coroutines. Priorities are small signed integers (currently -4 .. 186 coroutines. Priorities are small signed integers (currently -4 ..
… …
164 $olddesc = $coroutine->desc ($newdesc) 209 $olddesc = $coroutine->desc ($newdesc)
165 Sets (or gets in case the argument is missing) the description for 210 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 211 this coroutine. This is just a free-form string you can associate
167 with a coroutine. 212 with a coroutine.
168 213
169 UTILITY FUNCTIONS 214 GLOBAL FUNCTIONS
215 Coro::nready
216 Returns the number of coroutines that are currently in the ready
217 state, i.e. that can be swicthed to. The value 0 means that the only
218 runnable coroutine is the currently running one, so "cede" would
219 have no effect, and "schedule" would cause a deadlock unless there
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 }
240
170 unblock_sub { ... } 241 unblock_sub { ... }
171 This utility function takes a BLOCK or code reference and "unblocks" 242 This utility function takes a BLOCK or code reference and "unblocks"
172 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
173 return immediately without blocking, returning nothing, while the 244 return immediately without blocking, returning nothing, while the
174 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