--- Coro/README 2007/04/16 13:26:43 1.7 +++ Coro/README 2007/10/06 19:25:00 1.11 @@ -19,7 +19,7 @@ DESCRIPTION This module collection manages coroutines. Coroutines are similar to threads but don't run in parallel at the same time even on SMP machines. - The specific flavor of coroutine use din this module also guarentees you + The specific flavor of coroutine used in this module also guarantees you that it will not switch between coroutines unless necessary, at easily-identified points in your program, so locking and parallel access are rarely an issue, making coroutine programming much safer than @@ -43,7 +43,7 @@ value is $main (of course). This variable is strictly *read-only*. It is provided for - performance reasons. If performance is not essentiel you are + performance reasons. If performance is not essential you are encouraged to use the "Coro::current" function instead. $idle @@ -68,6 +68,9 @@ (usually unused). When the sub returns the new coroutine is automatically terminated. + See the "Coro::State::new" constructor for info about the coroutine + environment. + Calling "exit" in a coroutine will do the same as calling exit outside the coroutine. Likewise, when the coroutine dies, the program will exit, just as it would in the main program. @@ -89,8 +92,12 @@ like "on_destroy" will not work in the expected way, unless you call terminate or cancel, which somehow defeats the purpose of pooling. - The priority will be reset to 0 after each job, otherwise the - coroutine will be re-used "as-is". + The priority will be reset to 0 after each job, tracing will be + disabled, the description will be reset and the default output + filehandle gets restored, so you can change alkl these. Otherwise + the coroutine will be re-used "as-is": most notably if you change + other per-coroutine global stuff such as $/ you need to revert that + change, which is most simply done by using local as in " local $/ ". The pool size is limited to 8 idle coroutines (this can be adjusted by changing $Coro::POOL_SIZE), and there can be as many non-idle @@ -99,7 +106,9 @@ If you are concerned about pooled coroutines growing a lot because a single "async_pool" used a lot of stackspace you can e.g. "async_pool { terminate }" once per second or so to slowly replenish - the pool. + the pool. In addition to that, when the stacks used by a handler + grows larger than 16kb (adjustable with $Coro::POOL_RSS) it will + also exit. schedule Calls the scheduler. Please note that the current coroutine will not @@ -120,7 +129,7 @@ undef $current; }; - # call schedule until event occured. + # call schedule until event occurred. # in case we are woken up for other reasons # (current still defined), loop. Coro::schedule while $current; @@ -144,6 +153,11 @@ Terminates the current coroutine with the given status values (see cancel). + killall + Kills/terminates/cancels all coroutines except the currently running + one. This is useful after a fork, either in the child or the parent, + as usually only one of them should inherit the running coroutines. + # dynamic methods COROUTINE METHODS @@ -155,7 +169,8 @@ returned values were called. To make the coroutine run you must first put it into the ready queue by calling the ready method. - See "async" for additional discussion. + See "async" and "Coro::State::new" for additional info about the + coroutine environment. $success = $coroutine->ready Put the given coroutine into the ready queue (according to it's @@ -172,8 +187,8 @@ $coroutine->join Wait until the coroutine terminates and return any values given to - the "terminate" or "cancel" functions. "join" can be called multiple - times from multiple coroutine. + the "terminate" or "cancel" functions. "join" can be called + concurrently from multiple coroutines. $coroutine->on_destroy (\&cb) Registers a callback that is called when this coroutine gets @@ -211,10 +226,28 @@ this coroutine. This is just a free-form string you can associate with a coroutine. + This method simply sets the "$coroutine->{desc}" member to the given + string. You can modify this member directly if you wish. + + $coroutine->throw ([$scalar]) + If $throw is specified and defined, it will be thrown as an + exception inside the coroutine at the next convinient point in time + (usually after it gains control at the next schedule/transfer/cede). + Otherwise clears the exception object. + + The exception object will be thrown "as is" with the specified + scalar in $@, i.e. if it is a string, no line number or newline will + be appended (unlike with "die"). + + This can be used as a softer means than "cancel" to ask a coroutine + to end itself, although there is no guarentee that the exception + will lead to termination, and if the exception isn't caught it might + well end the whole program. + GLOBAL FUNCTIONS Coro::nready Returns the number of coroutines that are currently in the ready - state, i.e. that can be swicthed to. The value 0 means that the only + state, i.e. that can be switched to. The value 0 means that the only runnable coroutine is the currently running one, so "cede" would have no effect, and "schedule" would cause a deadlock unless there is an idle handler that wakes up some coroutines. @@ -245,7 +278,7 @@ original code ref will be called (with parameters) from within its own coroutine. - The reason this fucntion exists is that many event libraries (such + The reason this function exists is that many event libraries (such as the venerable Event module) are not coroutine-safe (a weaker form of thread-safety). This means you must not block within event callbacks, otherwise you might suffer from crashes or worse. @@ -263,12 +296,12 @@ destruction. very bad things might happen otherwise (usually segfaults). - this module is not thread-safe. You should only ever use this module - from the same thread (this requirement might be losened in the future + from the same thread (this requirement might be loosened in the future to allow per-thread schedulers, but Coro::State does not yet allow this). SEE ALSO - Support/Utility: Coro::Cont, Coro::Specific, Coro::State, Coro::Util. + Support/Utility: Coro::Specific, Coro::State, Coro::Util. Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, Coro::SemaphoreSet, Coro::RWLock.