From a84dc2168f07be47384d6fad7eaf94022b4dbbbb Mon Sep 17 00:00:00 2001
From: Bryan O'Sullivan <bos@serpentine.com>
Date: Mon, 25 Apr 2011 20:24:17 -0700
Subject: [PATCH] Document withRTSSignalsBlocked more clearly.

---
 Database/HDBC/MySQL.hs      | 59 +++++++++++++++++++++----------------
 Database/HDBC/MySQL/RTS.hsc |  5 +++-
 2 files changed, 38 insertions(+), 26 deletions(-)

diff --git a/Database/HDBC/MySQL.hs b/Database/HDBC/MySQL.hs
index f580844..a1b82ca 100644
--- a/Database/HDBC/MySQL.hs
+++ b/Database/HDBC/MySQL.hs
@@ -13,34 +13,43 @@ To use it, invoke the 'connectMySQL' method to create an
 database.  Use the 'defaultMySQLConnectInfo', overriding the default
 values as necessary.
 
-> import Control.Monad
-> import Database.HDBC
-> import Database.HDBC.MySQL
-> main = do conn <- connectMySQL defaultMySQLConnectInfo {
->                        mysqlHost     = "db1.example.com",
->                        mysqlUser     = "scott",
->                        mysqlPassword = "tiger"
->                     }
->
->           rows <- quickQuery' conn "SELECT 1 + 1" []
->           forM_ rows $ \row -> putStrLn $ show row
+@
+import Control.Monad
+import Database.HDBC
+import Database.HDBC.MySQL
+
+main = do
+  rows <- 'withRTSSignalsBlocked' $ do
+    conn <- 'connectMySQL' 'defaultMySQLConnectInfo' {
+              'mysqlHost'     = \"db1.example.com\",
+              'mysqlUser'     = \"scott\",
+              'mysqlPassword' = \"tiger\"
+            }
+    'quickQuery'' conn \"SELECT 1 + 1\" []
+  forM_ rows $ \row -> putStrLn $ show row
+@
 
 There are some important caveats to note about this driver.
 
-The first relates to transaction support.  The MySQL server supports a
-variety of backend \"engines\", only some of which support
-transactional access (e.g., InnoDB).  This driver will report that the
-database supports transactions.  Should you decide to make use of the
-transactional support in the HDBC API,
-/it is up to you to make sure that you use a MySQL engine that supports transactions/.
-
-The next relates to dates and times.  MySQL does not store time zone
-information in @DATETIME@ or @TIMESTAMP@ columns: instead, it assumes
-that all dates are stored in the \"server's time zone\".  At some
-point in the future, this driver may query for the server's time zone
-and apply appropriate time zone conversion to these datatypes. For
-now, it simply treats all times as UTC; i.e., it assumes the server's
-time zone is UTC.
+* RTS signals.  If you are writing an application that links against GHC's
+  threaded runtime (as most server-side applications do), you must use
+  'withRTSSignalsBlocked' to defend the @mysqlclient@ library against the
+  signals the RTS uses, or you may experience crashes.
+
+* Transaction support.  The MySQL server supports a
+  variety of backend \"engines\", only some of which support
+  transactional access (e.g., InnoDB).  This driver will report that the
+  database supports transactions.  Should you decide to make use of the
+  transactional support in the HDBC API,
+  /it is up to you to make sure that you use a MySQL engine that supports transactions/.
+
+* Dates and times.  MySQL does not store time zone
+  information in @DATETIME@ or @TIMESTAMP@ columns: instead, it assumes
+  that all dates are stored in the \"server's time zone\".  At some
+  point in the future, this driver may query for the server's time zone
+  and apply appropriate time zone conversion to these datatypes. For
+  now, it simply treats all times as UTC; i.e., it assumes the server's
+  time zone is UTC.
 
 -}
 module Database.HDBC.MySQL
diff --git a/Database/HDBC/MySQL/RTS.hsc b/Database/HDBC/MySQL/RTS.hsc
index 635e5c5..c78dd6b 100644
--- a/Database/HDBC/MySQL/RTS.hsc
+++ b/Database/HDBC/MySQL/RTS.hsc
@@ -15,11 +15,14 @@ import Foreign.Storable (Storable(..))
 -- blocked.  The @mysqlclient@ C library does not correctly restart
 -- system calls if they are interrupted by signals, so many MySQL API
 -- calls can unexpectedly fail when called from a Haskell application.
+-- This is most likely to occur if you are linking against GHC's
+-- threaded runtime (using the @-threaded@ option).
 --
 -- This function blocks @SIGALRM@ and @SIGVTALRM@, runs your action,
 -- then unblocks those signals.  If you have a series of HDBC calls
 -- that may block for a period of time, it may be wise to wrap them in
--- this action.
+-- this action.  Blocking and unblocking signals is cheap, but not
+-- free.
 --
 -- Here is an example of an exception that could be avoided by
 -- temporarily blocking GHC's runtime signals: