--- Coro-Mysql/README	2009/05/18 15:19:38	1.1
+++ Coro-Mysql/README	2009/05/30 06:58:22	1.2
@@ -0,0 +1,63 @@
+NAME
+    Coro::Mysql - let other threads run while doing mysql requests
+
+SYNOPSIS
+     use Coro::Mysql;
+
+     my $DBH = Coro::Mysql::unblock DBI->connect (...);
+
+DESCRIPTION
+    (Note that in this manual, "thread" refers to real threads as
+    implemented by the Coro module, not to the built-in windows process
+    emulation which unfortunately is also called "threads")
+
+    This module "patches" DBD::mysql database handles so that they do not
+    block the whole process, but only the thread that they are used in.
+
+    This can be used to make parallel sql requests using Coro, or to do
+    other stuff while mysql is rumbling in the background.
+
+  CAVEAT
+    Note that this module must be linked against exactly the same
+    libmysqlclient library as DBD::mysql, otherwise it will not work.
+
+    Also, while this module makes database handles non-blocking, you still
+    cannot run multiple requests in parallel on the same database handle. If
+    you want to run multiple queries in parallel, you have to create
+    multiple database connections, one for each thread that runs queries.
+
+    If you make sure that you never run two or more requests in parallel,
+    you cna freely share the database handles between threads, of course.
+
+    Also, this module uses a number of "unclean" techniques (patching an
+    internal libmysql structure for one thing) and was hacked within a few
+    hours on a long flight to Malaysia.
+
+    It does, however, check whether it indeed got the structure layout
+    correct, so you should expect perl exceptions or early crashes as
+    opposed to data corruption when something goes wrong.
+
+  SPEED
+    This module is implemented in XS, and as long as mysqld replies quickly
+    enough, it adds no overhead to the standard libmysql communication
+    routines (which are very badly written).
+
+    For very fast queries ("select 0"), this module can add noticable
+    overhead (around 15%) as it tries to switch to other coroutines when
+    mysqld doesn't deliver the data instantly.
+
+    For most types of queries, there will be no overhead, especially on
+    multicore systems where your perl process can do other things while
+    mysqld does its stuff.
+
+    $DBH = Coro::Mysql::unblock $DBH
+        This function takes a DBI database handles and "patches" it so it
+        becomes compatible to Coro threads.
+
+        After that, it returns the patched handle - you should always use
+        the newly returned database handle.
+
+AUTHOR
+     Marc Lehmann <schmorp@schmorp.de>
+     http://home.schmorp.de/
+