--- cvsroot/Coro/README 2008/11/20 09:37:21 1.18 +++ cvsroot/Coro/README 2008/11/24 07:55:28 1.19 @@ -1,5 +1,5 @@ NAME - Coro - coroutine process abstraction + Coro - the only real threads in perl SYNOPSIS use Coro; @@ -25,33 +25,41 @@ $lock->up; DESCRIPTION - This module collection manages coroutines. Coroutines are similar to - threads but don't (in general) 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 and easier than threads programming. - - Unlike a normal perl program, however, coroutines allow you to have - multiple running interpreters that share data, which is especially - useful to code pseudo-parallel processes and for event-based - programming, such as multiple HTTP-GET requests running concurrently. - See Coro::AnyEvent to learn more. - - Coroutines are also useful because Perl has no support for threads (the - so called "threads" that perl offers are nothing more than the (bad) - process emulation coming from the Windows platform: On standard - operating systems they serve no purpose whatsoever, except by making - your programs slow and making them use a lot of memory. Best disable - them when building perl, or aks your software vendor/distributor to do - it for you). - - 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 (see Coro::State for more configuration). + For a tutorial-style introduction, please read the Coro::Intro manpage. + This manpage mainly contains reference information. + This module collection manages continuations in general, most often in + the form of cooperative threads (also called coroutines in the + documentation). They are similar to kernel threads but don't (in + general) run in parallel at the same time even on SMP machines. The + specific flavor of thread offered by this module also guarantees you + that it will not switch between threads unless necessary, at + easily-identified points in your program, so locking and parallel access + are rarely an issue, making thread programming much safer and easier + than using other thread models. + + Unlike the so-called "Perl threads" (which are not actually real threads + but only the windows process emulation ported to unix), Coro provides a + full shared address space, which makes communication between threads + very easy. And threads are fast, too: disabling the Windows process + emulation code in your perl and using Coro can easily result in a two to + four times speed increase for your programs. + + Coro achieves that by supporting multiple running interpreters that + share data, which is especially useful to code pseudo-parallel processes + and for event-based programming, such as multiple HTTP-GET requests + running concurrently. See Coro::AnyEvent to learn more on how to + integrate Coro into an event-based environment. + + In this module, a thread is defined as "callchain + lexical variables + + @_ + $_ + $@ + $/ + C stack), that is, a thread has its own callchain, + its own set of lexicals and its own set of perls most important global + variables (see Coro::State for more configuration and background info). + + See also the "SEE ALSO" section at the end of this document - the Coro + module family is quite large. + +GLOBAL VARIABLES $Coro::main This variable stores the coroutine object that represents the main program. While you cna "ready" it and do most other things you can @@ -70,22 +78,29 @@ $Coro::idle This variable is mainly useful to integrate Coro into event loops. - It is usually better to rely on Coro::AnyEvent or L"Coro::EV", as - this is pretty low-level functionality. + It is usually better to rely on Coro::AnyEvent or Coro::EV, as this + is pretty low-level functionality. + + This variable stores either a coroutine or a callback. + + If it is a callback, the it 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 variable stores 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. + If it is a coroutine object, then this object will be readied + (without invoking any ready hooks, however) when the scheduler finds + no other ready coroutines to run. - This hook is overwritten by modules such as "Coro::Timer" and + This hook is overwritten by modules such as "Coro::EV" and "Coro::AnyEvent" to wait on an external event that hopefully wake up a coroutine so the scheduler can run it. Note that the callback *must not*, under any circumstances, block the current coroutine. Normally, this is achieved by having an "idle coroutine" that calls the event loop and then blocks again, and then - readying that coroutine in the idle handler. + readying that coroutine in the idle handler, or by simply placing + the idle coroutine in this variable. See Coro::Event or Coro::AnyEvent for examples of using this technique. @@ -94,7 +109,7 @@ event handlers), then it must be prepared to be called recursively itself. - SIMPLE COROUTINE CREATION +SIMPLE COROUTINE CREATION async { ... } [@args...] Create a new coroutine and return it's coroutine object (usually unused). The coroutine will be put into the ready queue, so it will @@ -155,12 +170,12 @@ 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 via $Coro::POOL_RSS) it will also + grows larger than 32kb (adjustable via $Coro::POOL_RSS) it will also be destroyed. - STATIC METHODS - Static methods are actually functions that operate on the current - coroutine. +STATIC METHODS + Static methods are actually functions that implicitly operate on the + current coroutine. schedule Calls the scheduler. The scheduler will find the next coroutine that @@ -213,7 +228,7 @@ not the main program calls this function, there will be some one-time resource leak. - COROUTINE METHODS +COROUTINE OBJECT METHODS These are the methods you can call on coroutine objects (or to create them). @@ -330,7 +345,7 @@ This method simply sets the "$coroutine->{desc}" member to the given string. You can modify this member directly if you wish. - GLOBAL FUNCTIONS +GLOBAL FUNCTIONS Coro::nready Returns the number of coroutines that are currently in the ready state, i.e. that can be switched to by calling "schedule" directory @@ -367,7 +382,7 @@ 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 + of reentrancy). This means you must not block within event callbacks, otherwise you might suffer from crashes or worse. The only event library currently known that is safe to use without "unblock_sub" is EV. @@ -393,18 +408,18 @@ $cb = Coro::rouse_cb Create and return a "rouse callback". That's a code reference that, - when called, will save its arguments and notify the owner coroutine - of the callback. + when called, will remember a copy of its arguments and notify the + owner coroutine of the callback. See the next function. @args = Coro::rouse_wait [$cb] - Wait for the specified rouse callback (or the last one tht was + Wait for the specified rouse callback (or the last one that was created in this coroutine). - As soon as the callback is invoked (or when the calback was invoked - before "rouse_wait"), it will return a copy of the arguments - originally passed to the rouse callback. + As soon as the callback is invoked (or when the callback was invoked + before "rouse_wait"), it will return the arguments originally passed + to the rouse callback. See the section HOW TO WAIT FOR A CALLBACK for an actual usage example. @@ -482,7 +497,7 @@ perl process emulation ("threads") This module is not perl-pseudo-thread-safe. You should only ever use - this module from the same thread (this requirement might be removed + this module from the first thread (this requirement might be removed in the future to allow per-thread schedulers, but Coro::State does not yet allow this). I recommend disabling thread support and using processes, as having the windows process emulation enabled under @@ -505,16 +520,18 @@ Support/Utility: Coro::Specific, Coro::Util. - Locking/IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, + Locking and IPC: Coro::Signal, Coro::Channel, Coro::Semaphore, Coro::SemaphoreSet, Coro::RWLock. - IO/Timers: Coro::Timer, Coro::Handle, Coro::Socket, Coro::AIO. + I/O and Timers: Coro::Timer, Coro::Handle, Coro::Socket, Coro::AIO. - Compatibility: Coro::LWP, Coro::BDB, Coro::Storable, Coro::Select. + Compatibility with other modules: Coro::LWP (but see also AnyEvent::HTTP + for a better-working alternative), Coro::BDB, Coro::Storable, + Coro::Select. XS API: Coro::MakeMaker. - Low level Configuration, Coroutine Environment: Coro::State. + Low level Configuration, Thread Environment, Continuations: Coro::State. AUTHOR Marc Lehmann