--- cvsroot/Coro/README 2006/12/03 21:59:53 1.4 +++ cvsroot/Coro/README 2007/10/06 19:25:00 1.11 @@ -18,11 +18,21 @@ DESCRIPTION This module collection manages coroutines. Coroutines are similar to - threads but don't run in parallel. + threads but don't run in parallel at the same time even on SMP machines. + 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 + threads programming. + + (Perl, however, does not natively support real threads but instead does + a very slow and memory-intensive emulation of processes using threads. + This is a performance win on Windows machines, and a loss everywhere + else). In this module, coroutines are defined as "callchain + lexical variables - + @_ + $_ + $@ + $^W + C stack), that is, a coroutine has it's own - callchain, it's own set of lexicals and it's own set of perl's most + + @_ + $_ + $@ + $/ + 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. $main @@ -33,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 @@ -58,17 +68,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. - 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 @@ -88,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; @@ -100,10 +141,23 @@ 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 @@ -115,8 +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. - 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 @@ -128,12 +182,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 @@ -166,7 +226,51 @@ this coroutine. This is just a free-form string you can associate with a coroutine. - UTILITY FUNCTIONS + 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 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 @@ -174,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. @@ -192,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.