NAME
    Coro - coroutine process abstraction

SYNOPSIS
     use Coro;

     async {
        # some asynchronous thread of execution
     };

     # alternatively create an async process like this:

     sub some_func : Coro {
        # some more async code
     }

     cede;

DESCRIPTION
    This module collection manages coroutines. Coroutines are similar to
    Threads but don't run in parallel.

    This module is still experimental, see the BUGS section below.

    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
    important global variables.

    $main
    This coroutine represents the main program.

    $current (or as function: current)
    The current coroutine (the last coroutine switched to). The initial
    value is $main (of course).

    $idle
    The coroutine to switch to when no other coroutine is running. The
    default implementation prints "FATAL: deadlock detected" and exits.

  STATIC METHODS

    Static methods are actually functions that operate on the current
    process only.

    async { ... } [@args...]
        Create a new asynchronous process and return it's process object
        (usually unused). When the sub returns the new process is
        automatically terminated.

           # create a new coroutine that just prints its arguments
           async {
              print "@_\n";
           } 1,2,3,4;

        The coderef you submit MUST NOT be a closure that refers to
        variables in an outer scope. This does NOT work. Pass arguments into
        it instead.

    schedule
        Calls the scheduler. Please note that the current process will not
        be put into the ready queue, so calling this function usually means
        you will never be called again.

    cede
        "Cede" to other processes. This function puts the current process
        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.

        Future versions of this function will allow result arguments.

    # dynamic methods

  PROCESS METHODS

    These are the methods you can call on process 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 start the process you must first put it into the
        ready queue by calling the ready method.

        The coderef you submit MUST NOT be a closure that refers to
        variables in an outer scope. This does NOT work. Pass arguments into
        it instead.

    $process->ready
        Put the given process into the ready queue.

    $process->cancel
        Like "terminate", but terminates the specified process instead.

    $process->join
        Wait until the coroutine terminates and return any values given to
        the "terminate" function. "join" can be called multiple times from
        multiple processes.

    $oldprio = $process->prio($newprio)
        Sets the priority of the process. Higher priority processes get run
        before lower priority processes. Priorities are smalled signed
        integer (currently -4 .. +3), that you can refer to using PRIO_xxx
        constants (use the import tag :prio to get then):

           PRIO_MAX > PRIO_HIGH > PRIO_NORMAL > PRIO_LOW > PRIO_IDLE > PRIO_MIN
               3    >     1     >      0      >    -1    >    -3     >    -4

           # set priority to HIGH
           current->prio(PRIO_HIGH);

        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
        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.

    $newprio = $process->nice($change)
        Similar to "prio", but subtract the given value from the priority
        (i.e. higher values mean lower priority, just as in unix).

BUGS/LIMITATIONS
     - you must make very sure that no coro is still active on global destruction.
       very bad things might happen otherwise (usually segfaults).
     - this module is not thread-safe. You must only ever use this module 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
    the Coro::Channel manpage, the Coro::Cont manpage, the Coro::Specific
    manpage, the Coro::Semaphore manpage, the Coro::Signal manpage, the
    Coro::State manpage, the Coro::Event manpage, the Coro::RWLock manpage,
    the Coro::Handle manpage, the Coro::Socket manpage.

AUTHOR
     Marc Lehmann <pcg@goof.com>
     http://www.goof.com/pcg/marc/

