--- Coro-Mysql/README	2009/07/18 05:58:27	1.3
+++ Coro-Mysql/README	2011/02/20 10:35:10	1.4
@@ -18,8 +18,9 @@
     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.
+    Note that this module must be linked against exactly the same (shared,
+    possibly not working with all OSes) 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
@@ -32,8 +33,8 @@
     you can 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.
+    internal libmysql structure for one thing) and was initially 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
@@ -42,13 +43,17 @@
   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, btw.).
+    routines (which are very badly written, btw.). In fact, since it has a
+    more efficient buffering and allows requests to run in parallel, it
+    often decreases the actual time to run many queries considerably.
 
     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.
+    overhead (around 15%, 7% when EV can be used) as it tries to switch to
+    other coroutines when mysqld doesn't deliver the data immediately,
+    although, again, when running queries in parallel, they will usually
+    execute faster.
 
-    For most types of queries, there will be no overhead, especially on
+    For most types of queries, there will be no extra latency, especially on
     multicore systems where your perl process can do other things while
     mysqld does its stuff.
 
@@ -58,6 +63,12 @@
     named pipes (windows) and shared memory (also windows). No support for
     these connection types is planned, either.
 
+CANCELLATION
+    Cancelling a thread that is within a mysql query will likely make the
+    handle unusable. As far as Coro::Mysql is concerned, the handle can be
+    safely destroyed, but it's not clear how mysql itself will react to a
+    cancellation.
+
 FUNCTIONS
     Coro::Mysql offers a single user-accessible function:
 
@@ -73,6 +84,12 @@
         handles, others are returned unchanged. That means it is harmless
         when applied to database handles of other databases.
 
+        It is also safe to pass "undef", so code like this is works as
+        expected:
+
+           my $dbh = DBI->connect ($database, $user, $pass)->Coro::Mysql::unblock
+              or die $DBI::errstr;
+
 USAGE EXAMPLE
     This example uses PApp::SQL and Coro::on_enter to implement a function
     "with_db", that connects to a database, uses "unblock" on the resulting
@@ -87,7 +104,7 @@
        sub with_db($$$&) {
           my ($database, $user, $pass, $cb) = @_;
 
-          my $dbh = Coro::Mysql::unblock DBI->connect ($database, $user, $pass)
+          my $dbh = DBI->connect ($database, $user, $pass)->Coro::Mysql::unblock
              or die $DBI::errstr;
 
           Coro::on_enter { $PApp::SQL::DBH = $dbh };