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

Comparing cvsroot/Coro/README (file contents):
Revision 1.7 by root, Mon Apr 16 13:26:43 2007 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:
… …
97 coros as required. 97 coros as required.
98 98
99 If you are concerned about pooled coroutines growing a lot because a 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. 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 101 "async_pool { terminate }" once per second or so to slowly replenish
102 the pool. 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.
103 105
104 schedule 106 schedule
105 Calls the scheduler. Please note that the current coroutine will not 107 Calls the scheduler. Please note that the current coroutine will not
106 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
107 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
… …
118 # wake up sleeping coroutine 120 # wake up sleeping coroutine
119 $current->ready; 121 $current->ready;
120 undef $current; 122 undef $current;
121 }; 123 };
122 124
123 # call schedule until event occured. 125 # call schedule until event occurred.
124 # in case we are woken up for other reasons 126 # in case we are woken up for other reasons
125 # (current still defined), loop. 127 # (current still defined), loop.
126 Coro::schedule while $current; 128 Coro::schedule while $current;
127 } 129 }
128 130
… …
212 with a coroutine. 214 with a coroutine.
213 215
214 GLOBAL FUNCTIONS 216 GLOBAL FUNCTIONS
215 Coro::nready 217 Coro::nready
216 Returns the number of coroutines that are currently in the ready 218 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 219 state, i.e. that can be switched to. The value 0 means that the only
218 runnable coroutine is the currently running one, so "cede" would 220 runnable coroutine is the currently running one, so "cede" would
219 have no effect, and "schedule" would cause a deadlock unless there 221 have no effect, and "schedule" would cause a deadlock unless there
220 is an idle handler that wakes up some coroutines. 222 is an idle handler that wakes up some coroutines.
221 223
222 my $guard = Coro::guard { ... } 224 my $guard = Coro::guard { ... }
… …
243 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
244 return immediately without blocking, returning nothing, while the 246 return immediately without blocking, returning nothing, while the
245 original code ref will be called (with parameters) from within its 247 original code ref will be called (with parameters) from within its
246 own coroutine. 248 own coroutine.
247 249
248 The reason this fucntion exists is that many event libraries (such 250 The reason this function exists is that many event libraries (such
249 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
250 of thread-safety). This means you must not block within event 252 of thread-safety). This means you must not block within event
251 callbacks, otherwise you might suffer from crashes or worse. 253 callbacks, otherwise you might suffer from crashes or worse.
252 254
253 This function allows your callbacks to block by executing them in 255 This function allows your callbacks to block by executing them in
… …
261BUGS/LIMITATIONS 263BUGS/LIMITATIONS
262 - 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
263 destruction. very bad things might happen otherwise (usually segfaults). 265 destruction. very bad things might happen otherwise (usually segfaults).
264 266
265 - 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
266 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
267 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
268 this). 270 this).
269 271
270SEE ALSO 272SEE ALSO
271 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