c61c692 · typeable/postgresql-simple

git.iko.soy/typeable/postgresql-simple

Assorted Documentation fixes

commitc61c69244299136874eb1b847bae2f84ced50526 authorLeon P Smith <leon@melding-monads.com> dateTue 20 Aug 2013, 04:00 (13 years ago) parent5f31a39

4 files changed+19−16

compare with master

unifiedsplit

src/Database/PostgreSQL/Simple/Copy.hs+4−4 src/Database/PostgreSQL/Simple/FromField.hs+9−7 src/Database/PostgreSQL/Simple/FromRow.hs+3−2 src/Database/PostgreSQL/Simple/TypeInfo/Macro.hs+3−3

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

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

5353

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

5555-- 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

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

5858

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

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

6464

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

6666-- 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

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

6969

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

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

163163--

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

165165-- 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

167167-- is called.

168168

169169putCopyEnd :: Connection -> IO Int64

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

180180--

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

182182-- 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

184184-- is called.

185185

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

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

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

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

163163 -- may be a 'UnicodeException'.

164164 --

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

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

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

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

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

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

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

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.

169171 --

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

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

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

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

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

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

173175

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

175177-- 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

5959-- exception will be thrown.

6060--

6161-- 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

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

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

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

64+-- of 'fromField'.

6465

6566class FromRow a where

6667 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])) |]

3434 catchAll :: MatchQ

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

3636

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

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

39−-- fold constants.

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

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

39+-- not to fold constants.

4040inlineTypoid :: TypeInfo -> ExpQ

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

4242