--- cvsroot/Coro/README 2007/09/29 19:42:08 1.9 +++ cvsroot/Coro/README 2007/10/11 00:38:37 1.12 @@ -6,15 +6,22 @@ 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 @@ -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. @@ -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 @@ -134,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 @@ -157,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 @@ -174,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 @@ -213,6 +230,24 @@ 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 @@ -270,15 +305,20 @@ 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