--- Coro-Multicore/README	2015/06/27 17:59:10	1.1
+++ Coro-Multicore/README	2015/06/30 01:01:34	1.2
@@ -0,0 +1,114 @@
+NAME
+    Coro::Multicore - make coro threads on multiple cores with specially
+    supported modules
+
+SYNOPSIS
+     use Coro::Multicore;
+
+     # or, if you want it disabled by default (e.g. to use it from a module)
+     use Coro::Multicore ();
+
+DESCRIPTION
+    While Coro threads (unlike ithreads) provide real threads similar to
+    pthreads, python threads and so on, they do not run in parallel to each
+    other even on machines with multiple CPUs or multiple CPU cores.
+
+    This module lifts this restriction under two very specific but useful
+    conditions: firstly, the coro thread executes in XS code and does not
+    touch any perl data structures, and secondly, the XS code is specially
+    prepared to allow this.
+
+    This means that, when you call an XS function of a module prepared for
+    it, this XS function can execute in parallel to any other Coro threads.
+
+    The mechanism to support this is easily added to existing modules and is
+    independent of Coro or Coro::Multicore, and therefore could be used,
+    without changes, with other, similar, modules, or even the perl core,
+    should it gain real thread support anytime soon. See
+    <http://perlmulticore.schmorp.de/> for more info on how to prepare a
+    module to allow parallel execution. Preparing an existing module is
+    easy, doesn't add much overhead and no dependencies.
+
+    This module is an AnyEvent user (and also, if not obvious, uses Coro).
+
+HOW TO USE IT
+    It could hardly be simpler - if you use coro threads, and before you
+    call a supported lengthy operation implemented in XS, use this module
+    and other coro threads can run in parallel:
+
+       use Coro::Multicore;
+
+    This module has no important API functions to learn or remember. All you
+    need to do is *load* it before you can take advantage of it.
+
+  EXPORTS
+    This module does not (at the moment) export any symbols. It does,
+    however, export "behaviour" - if you use the default import, then
+    Coro::Multicore will be enabled for all threads and all callers in the
+    whole program:
+
+       use Coro::Multicore;
+
+    In a module where you don't control what else might be loaded and run,
+    you might want to be more conservative, and not import anything. This
+    has the effect of not enabling the functionality by default, so you have
+    to enable it per scope:
+
+       use Coro::Multicore ();
+
+       sub myfunc {
+          Coro::Multicore::scoped_enable;
+
+          # from here to the end of this function, and in any functions
+          # called from this function, tasks will be executed asynchronously.
+       }
+
+API FUNCTIONS
+    $previous = Coro::Multicore::enable [$enable]
+        This function enables (if $enable is true) or disables (if $enable
+        is false) the multicore functionality globally. By default, it is
+        enabled.
+
+        This can be used to effectively disable this module's functionality
+        by default, and enable it only for selected threads or scopes, by
+        calling "Coro::Multicore::scope_enable".
+
+        The function returns the previous value of the enable flag.
+
+    Coro::Multicore::scoped_enable
+        This function instructs Coro::Multicore to handle all requests
+        executed in the current coro thread, from the call to the end of the
+        current scope.
+
+        Calls to "scoped_enable" and "scoped_disable" don't nest very well
+        at the moment, so don't nest them.
+
+    Coro::Multicore::scoped_disable
+        The opposite of "Coro::Multicore::scope_disable": instructs
+        Coro::Multicore to *not* handle the next multicore-enabled request.
+
+INTERACTION WITH OTHER SOFTWARE
+    TODO
+
+BUGS
+    (OS-) threads are never released
+        At the moment, threads that were created once will never be freed.
+        They will be reused for asynchronous requests, though, so a slong as
+        you limit the maximum number of concurrent asynchronous tasks, this
+        will also limit the maximum number of threads created.
+
+        Future versions will likely lift this limitation.
+
+    AnyEvent is initalised on module load
+        AnyEvent is initialised on module load, as opposed to at a later
+        time.
+
+        Future versions will likely change this.
+
+AUTHOR
+     Marc Lehmann <schmorp@schmorp.de>
+     http://software.schmorp.de/pkg/AnyEvent-XSThreadPool.html
+
+    Additional thanks to Zsbán Ambrus, who gave considerable desing input
+    for this module and the perl multicore specification.
+