c61c692 · typeable/postgresql-simple

git.iko.soy/typeable/postgresql-simple

on master help sign in

Assorted Documentation fixes

c61c692Leon P Smith13 years ago

src/Database/PostgreSQL/Simple/Copy.hs+4−4

compare with master

unifiedsplit

@@ -53,7 +53,7 @@ import Database.PostgreSQL.Simple.Internal

54-- | Issue a @COPY FROM STDIN@ or @COPY TO STDOUT@ query. In the former

55-- case, the connection's state will change to @CopyIn@; in the latter,

56−-- @CopyOut@. The connection must be in the normal state in order

56+-- @CopyOut@. The connection must be in the ready state in order

57-- to call this function. Performs parameter subsitution.

59copy :: ( ToRow params ) => Connection -> Query -> params -> IO ()

@@ -64,7 +64,7 @@ copy conn template qs = do

65-- | Issue a @COPY FROM STDIN@ or @COPY TO STDOUT@ query. In the former

66-- case, the connection's state will change to @CopyIn@; in the latter,

67−-- @CopyOut@. The connection must be in the normal state in order

67+-- @CopyOut@. The connection must be in the ready state in order

68-- to call this function. Does not perform parameter subsitution.

70copy_ :: Connection -> Query -> IO ()

@@ -163,7 +163,7 @@ putCopyData conn dat = withConnection conn $ \pqconn -> do

163--

164-- A connection must be in the @CopyIn@ state in order to call this

165-- function, otherwise a 'SqlError' exception will result. The

166−-- connection's state changes back to normal after this function

166+-- connection's state changes back to ready after this function

167-- is called.

168

169putCopyEnd :: Connection -> IO Int64

@@ -180,7 +180,7 @@ putCopyEnd conn = withConnection conn $ \pqconn -> do

180--

181-- A connection must be in the @CopyIn@ state in order to call this

182-- function, otherwise a 'SqlError' exception will result. The

183−-- connection's state changes back to normal after this function

183+-- connection's state changes back to ready after this function

184-- is called.

185

186putCopyError :: Connection -> B.ByteString -> IO ()

src/Database/PostgreSQL/Simple/FromField.hs+9−7

@@ -162,14 +162,16 @@ class FromField a where

162 -- library instances, this will usually be a single 'ResultError', but

163 -- may be a 'UnicodeException'.

164 --

165− -- Implementations of 'fromField' should not retain any references to

165+ -- Note that retaining any reference to the 'Field' or 'ByteString'

166− -- the 'Field' nor the 'ByteString' arguments after the result has

166+ -- arguments causes the entire @LibPQ.'PQ.Result'@ to be retained.

167− -- been evaluated to WHNF. Such a reference causes the entire

167+ -- Thus, as a rule of thumb, implementations of 'fromField' should

168− -- @LibPQ.'PQ.Result'@ to be retained.

168+ -- not refer to these values after the result has been evaluated

169+ -- to WHNF. But it can be profitable to break this rule when you

170+ -- know it won't cause memory management problems.

169 --

171 --

172+ -- The instances included with postgresql-simple follow this rule

170− -- For example, the instance for 'ByteString' uses 'B.copy' to avoid

173+ -- of thumb (modulo bugs). For example, the instance for 'ByteString'

171− -- such a reference, and that using bytestring functions such as 'B.drop'

174+ -- uses 'B.copy' to avoid such a reference.

172− -- and 'B.takeWhile' alone will also trigger this memory leak.

173

175

174-- | Returns the data type name. This is the preferred way of identifying

176-- | Returns the data type name. This is the preferred way of identifying

175-- types that do not have a stable type oid, such as types provided by

177-- types that do not have a stable type oid, such as types provided by

src/Database/PostgreSQL/Simple/FromRow.hs+3−2

@@ -59,8 +59,9 @@ import Control.Monad.Trans.Class

59-- exception will be thrown.

60--

61-- Note that 'field' evaluates it's result to WHNF, so the caveats listed in

62−-- previous versions of postgresql-simple no longer apply. Instead, look

62+-- mysql-simple and very early versions of postgresql-simple no longer apply.

63−-- at the caveats associated with user-defined implementations of 'fromRow'.

63+-- Instead, look at the caveats associated with user-defined implementations

64+-- of 'fromField'.

65class FromRow a where

66class FromRow a where

66 fromRow :: RowParser a

67 fromRow :: RowParser a

src/Database/PostgreSQL/Simple/TypeInfo/Macro.hs+3−3

@@ -34,9 +34,9 @@ mkCompats tys = [| \(Oid x) -> $(caseE [| x |] (map alt tys ++ [catchAll])) |]

34 catchAll :: MatchQ

35 catchAll = match wildP (normalB [| False |]) []

37−-- | Literally substitute the value of a TypeInfo expression. Returns

37+-- | Literally substitute the 'typoid' of a 'TypeInfo' expression.

38−-- an expression of type 'Oid'. Useful because GHC tends not to

38+-- Returns an expression of type 'Oid'. Useful because GHC tends

39−-- fold constants.

39+-- not to fold constants.

40inlineTypoid :: TypeInfo -> ExpQ

41inlineTypoid ty = [| Oid $(litE (getTypoid ty)) |]