--- cvsroot/Coro/README 2006/12/04 22:06:02 1.5 +++ 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,17 +76,48 @@ (usually unused). When the sub returns the new coroutine is automatically terminated. - Calling "exit" in a coroutine will not work correctly, so do not do - that. + See the "Coro::State::new" constructor for info about the coroutine + environment in which coroutines run. - When the coroutine dies, the program will exit, just as in the main - program. + 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. # create a new coroutine that just prints its arguments async { print "@_\n"; } 1,2,3,4; + async_pool { ... } [@args...] + Similar to "async", but uses a coroutine pool, so you should not + call terminate or join (although you are allowed to), and you get a + coroutine that might have executed other code already (which can be + good or bad :). + + Also, the block is executed in an "eval" context and a warning will + be issued in case of an exception instead of terminating the + program, as "async" does. As the coroutine is being reused, stuff + 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, 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 + coros as required. + + 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. 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 be put into the ready queue, so calling this function usually means @@ -98,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; @@ -110,10 +149,19 @@ giving up the current "timeslice" to other coroutines of the same or higher priority. + Coro::cede_notself + Works like cede, but is not exported by default and will cede to any + coroutine, regardless of priority, once. + 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 @@ -125,8 +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. - Calling "exit" in a coroutine will not work correctly, so do not do - that. + 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 @@ -138,12 +186,18 @@ $coroutine->cancel (arg...) Terminates the given coroutine and makes it return the given - arguments as status (default: the empty list). + arguments as status (default: the empty list). Never returns if the + coroutine is the current coroutine. $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 + destroyed, but before it is joined. The callback gets passed the + terminate arguments, if any. $oldprio = $coroutine->prio ($newprio) Sets (or gets, if the argument is missing) the priority of the @@ -176,14 +230,51 @@ 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. + my $guard = Coro::guard { ... } + This creates and returns a guard object. Nothing happens until the + object gets destroyed, in which case the codeblock given as argument + will be executed. This is useful to free locks or other resources in + case of a runtime error or when the coroutine gets canceled, as in + both cases the guard block will be executed. The guard object + supports only one method, "->cancel", which will keep the codeblock + from being executed. + + Example: set some flag and clear it again when the coroutine gets + canceled or the function returns: + + sub do_something { + my $guard = Coro::guard { $busy = 0 }; + $busy = 1; + + # do something that requires $busy to be true + } + unblock_sub { ... } This utility function takes a BLOCK or code reference and "unblocks" it, returning the new coderef. This means that the new coderef will @@ -191,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. @@ -209,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