--- cvsroot/Coro/README 2005/08/20 01:10:22 1.2 +++ cvsroot/Coro/README 2006/12/03 21:59:53 1.4 @@ -8,7 +8,7 @@ # some asynchronous thread of execution }; - # alternatively create an async process like this: + # alternatively create an async coroutine like this: sub some_func : Coro { # some more async code @@ -32,66 +32,113 @@ The current coroutine (the last coroutine switched to). The initial value is $main (of course). + This variable is strictly *read-only*. It is provided for + performance reasons. If performance is not essentiel you are + encouraged to use the "Coro::current" function instead. + $idle - The coroutine to switch to when no other coroutine is running. The - default implementation prints "FATAL: deadlock detected" and exits. + A callback that is called whenever the scheduler finds no ready + coroutines to run. The default implementation prints "FATAL: + deadlock detected" and exits, because the program has no other way + to continue. + + This hook is overwritten by modules such as "Coro::Timer" and + "Coro::Event" to wait on an external event that hopefully wake up a + 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. STATIC METHODS Static methods are actually functions that operate on the current - process only. + coroutine only. async { ... } [@args...] - Create a new asynchronous process and return it's process object - (usually unused). When the sub returns the new process is + Create a new asynchronous coroutine and return it's coroutine object + (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. + + When the coroutine dies, the program will exit, just as in the main + program. + # create a new coroutine that just prints its arguments async { print "@_\n"; } 1,2,3,4; schedule - Calls the scheduler. Please note that the current process will not + Calls the scheduler. Please note that the current coroutine will not be put into the ready queue, so calling this function usually means - you will never be called again. + you will never be called again unless something else (e.g. an event + handler) calls ready. + + The canonical way to wait on external events is this: + + { + # remember current coroutine + my $current = $Coro::current; + + # register a hypothetical event handler + on_event_invoke sub { + # wake up sleeping coroutine + $current->ready; + undef $current; + }; + + # call schedule until event occured. + # in case we are woken up for other reasons + # (current still defined), loop. + Coro::schedule while $current; + } cede - "Cede" to other processes. This function puts the current process + "Cede" to other coroutines. This function puts the current coroutine into the ready queue and calls "schedule", which has the effect of giving up the current "timeslice" to other coroutines of the same or higher priority. terminate [arg...] - Terminates the current process with the given status values (see + Terminates the current coroutine with the given status values (see cancel). # dynamic methods - PROCESS METHODS - These are the methods you can call on process objects. + COROUTINE METHODS + These are the methods you can call on coroutine objects. new Coro \&sub [, @args...] - Create a new process and return it. When the sub returns the process - automatically terminates as if "terminate" with the returned values - were called. To make the process run you must first put it into the - ready queue by calling the ready method. - - $process->ready - Put the given process into the ready queue. - - $process->cancel (arg...) - Temrinates the given process and makes it return the given arguments - as status (default: the empty list). + Create a new coroutine and return it. When the sub returns the + coroutine automatically terminates as if "terminate" with the + 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. + + $success = $coroutine->ready + Put the given coroutine into the ready queue (according to it's + priority) and return true. If the coroutine is already in the ready + queue, do nothing and return false. + + $is_ready = $coroutine->is_ready + Return wether the coroutine is currently the ready queue or not, + + $coroutine->cancel (arg...) + Terminates the given coroutine and makes it return the given + arguments as status (default: the empty list). - $process->join + $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 processes. + times from multiple coroutine. - $oldprio = $process->prio($newprio) + $oldprio = $coroutine->prio ($newprio) Sets (or gets, if the argument is missing) the priority of the - process. Higher priority processes get run before lower priority - processes. Priorities are small signed integers (currently -4 .. + coroutine. Higher priority coroutines get run before lower priority + coroutines. Priorities are small signed integers (currently -4 .. +3), that you can refer to using PRIO_xxx constants (use the import tag :prio to get then): @@ -104,20 +151,41 @@ The idle coroutine ($Coro::idle) always has a lower priority than any existing coroutine. - Changing the priority of the current process will take effect - immediately, but changing the priority of processes in the ready + Changing the priority of the current coroutine will take effect + immediately, but changing the priority of coroutines in the ready queue (but not running) will only take effect after the next - schedule (of that process). This is a bug that will be fixed in some - future version. + schedule (of that coroutine). This is a bug that will be fixed in + some future version. - $newprio = $process->nice($change) + $newprio = $coroutine->nice ($change) Similar to "prio", but subtract the given value from the priority (i.e. higher values mean lower priority, just as in unix). - $olddesc = $process->desc($newdesc) + $olddesc = $coroutine->desc ($newdesc) Sets (or gets in case the argument is missing) the description for - this process. This is just a free-form string you can associate with - a process. + this coroutine. This is just a free-form string you can associate + with a coroutine. + + UTILITY FUNCTIONS + 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 + return immediately without blocking, returning nothing, while the + original code ref will be called (with parameters) from within its + own coroutine. + + The reason this fucntion 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. + + This function allows your callbacks to block by executing them in + another coroutine where it is safe to block. One example where + blocking is handy is when you use the Coro::AIO functions to save + results to disk. + + In short: simply use "unblock_sub { ... }" instead of "sub { ... }" + when creating event callbacks that want to block. BUGS/LIMITATIONS - you must make very sure that no coro is still active on global