@@ -8,7 +8,23 @@
88-- Maintainer: Leon P Smith <leon@melding-monads.com>
99-- Stability: experimental
1010--
11−-- mid-level support for COPY IN and COPY OUT.
11+-- mid-level support for COPY IN and COPY OUT. See
12+-- <http://www.postgresql.org/docs/9.2/static/sql-copy.html> for
13+-- more information.
14+--
15+-- To use this binding, first call 'copy' with a @COPY FROM STDIN@
16+-- or @COPY TO STDOUT@ query as documented in the link above. Then
17+-- call @getCopyData@ repeatedly until it returns 'CopyOutDone' in
18+-- the former case, or in the latter case call @putCopyData@ repeatedly
19+-- and then finally call either @putCopyEnd@ to proceed or @putCopyError@
20+-- to abort.
21+--
22+-- You cannot issue another query on the same connection while a copy
23+-- is ongoing; this will result in an exception. It is harmless to
24+-- concurrently call @getNotification@ on a connection while it is in
25+-- a copy in or copy out state, however be aware that current versions
26+-- of the PostgreSQL backend will not deliver notifications to a client
27+-- while a transaction is ongoing.
1228--
1329------------------------------------------------------------------------------
1430
@@ -22,7 +38,7 @@ module Database.PostgreSQL.Simple.Copy
2238 ) where
2339
2440import Control.Applicative
25−import Control.Concurrent ( threadWaitRead, threadWaitWrite )
41+import Control.Concurrent
2642import Control.Exception ( throwIO )
2743import qualified Data.Attoparsec.ByteString.Char8 as P
2844import Data.Int(Int64)
@@ -57,7 +73,6 @@ doCopy funcName conn template q = do
5773 PQ.BadResponse -> throwResultError funcName result status
5874 PQ.NonfatalError -> throwResultError funcName result status
5975 PQ.FatalError -> throwResultError funcName result status
60−{-# INLINE doCopy #-}
6176
6277data CopyOutResult
6378 = CopyOutRow !B.ByteString -- ^ Data representing exactly one row
@@ -77,13 +92,12 @@ getCopyData conn = withConnection conn loop
7792#endif
7893 case row of
7994 PQ.CopyOutRow rowdata -> return $! CopyOutRow rowdata
80− PQ.CopyOutDone -> do
81− CopyOutDone <$> getCopyCommandTag funcName pqconn
95+ PQ.CopyOutDone -> CopyOutDone <$> getCopyCommandTag funcName pqconn
8296#if defined(mingw32_HOST_OS)
8397 PQ.CopyOutWouldBlock -> do
8498 fail (B.unpack funcName ++ ": the impossible happened")
8599#else
86− PQ.CopyOutWouldBlock -> do
100+ PQ.CopyOutWouldBlock -> do
87101 mfd <- PQ.socket pqconn
88102 case mfd of
89103 Nothing -> throwIO (fdError funcName)
@@ -92,7 +106,7 @@ getCopyData conn = withConnection conn loop
92106 _ <- PQ.consumeInput pqconn
93107 loop pqconn
94108#endif
95− PQ.CopyOutError -> do
109+ PQ.CopyOutError -> do
96110 mmsg <- PQ.errorMessage pqconn
97111 throwIO SqlError {
98112 sqlState = "",