--- cvsroot/Coro/README 2007/04/16 13:26:43 1.7 +++ cvsroot/Coro/README 2007/10/11 00:38:37 1.12 @@ -6,20 +6,27 @@ async { # some asynchronous thread of execution + print "2\n"; + cede; # yield back to main + print "4\n"; }; - - # alternatively create an async coroutine like this: - - sub some_func : Coro { - # some more async code - } - - cede; + print "1\n"; + cede; # yield to coroutine + print "3\n"; + cede; # and again + + # use locking + my $lock = new Coro::Semaphore; + my $locked; + + $lock->down; + $locked = 1; + $lock->up; 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 @@ -33,7 +40,7 @@ In this module, coroutines are defined as "callchain + lexical variables + @_ + $_ + $@ + $/ + C stack), that is, a coroutine has its own callchain, its own set of lexicals and its own set of perls most - important global variables. + important global variables (see Coro::State for more configuration). $main This coroutine represents the main program. @@ -43,7 +50,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 @@ -57,7 +64,8 @@ coroutine so the scheduler can run it. Please note that if your callback recursively invokes perl (e.g. for - event handlers), then it must be prepared to be called recursively. + event handlers), then it must be prepared to be called recursively + itself. STATIC METHODS Static methods are actually functions that operate on the current @@ -68,6 +76,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 in which coroutines run. + 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 +100,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 +114,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 +137,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; @@ -132,18 +149,19 @@ giving up the current "timeslice" to other coroutines of the same or higher priority. - Returns true if at least one coroutine switch has happened. - Coro::cede_notself Works like cede, but is not exported by default and will cede to any coroutine, regardless of priority, once. - Returns true if at least one coroutine switch has happened. - terminate [arg...] 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 +173,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 +191,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 +230,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 +282,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,20 +300,25 @@ 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. + Lower level Configuration, Coroutine Environment: Coro::State. + + Debugging: Coro::Debug. + + Support/Utility: Coro::Specific, Coro::Util. Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, Coro::SemaphoreSet, Coro::RWLock. - Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket, - Coro::Select. + Event/IO: Coro::Timer, Coro::Event, Coro::Handle, Coro::Socket. + + Compatibility: Coro::LWP, Coro::Storable, Coro::Select. - Embedding: + Embedding: . AUTHOR Marc Lehmann