4b11d1c · typeable/postgresql-simple

git.iko.soy/typeable/postgresql-simple

on master help sign in

Rough documentation pass for Ok, Notification, and LargeObjects

4b11d1cLeon P Smith14 years ago

src/Database/PostgreSQL/Simple/LargeObjects.hs+10−1

compare with master

unifiedsplit

@@ -1,11 +1,20 @@

1-----------------------------------------------------------------------------

2-- |

3-- Module : Database.PostgreSQL.Simple.LargeObjects

5-- License : BSD3

6--

7-- Maintainer : leon@melding-monads.com

8--

9+-- Support for PostgreSQL's Large Objects; see

10+-- <http://www.postgresql.org/docs/9.1/static/largeobjects.html> for more

11+-- information.

12+--

13+-- Note that Large Object File Descriptors are only valid within a single

14+-- database transaction, so if you are interested in using anything beyond

15+-- 'loCreat', 'loImport', 'loExport', and 'loUnlink', you will need to run

16+-- the entire sequence of functions in a transaction.

17+--

9-----------------------------------------------------------------------------

18-----------------------------------------------------------------------------

11module Database.PostgreSQL.Simple.LargeObjects

20module Database.PostgreSQL.Simple.LargeObjects

src/Database/PostgreSQL/Simple/Notification.hs+15−6

@@ -3,12 +3,17 @@

3-----------------------------------------------------------------------------

4-- |

5-- Module : Database.PostgreSQL.Simple.Notification

7-- License : BSD3

8--

9-- Maintainer : leon@melding-monads.com

10-- Stability : experimental

11--

12+-- Support for receiving asynchronous notifications via PostgreSQL's

13+-- Listen/Notify mechanism. See

14+-- <http://www.postgresql.org/docs/9.1/static/sql-notify.html> for more

15+-- information.

16+--

12-----------------------------------------------------------------------------

17-----------------------------------------------------------------------------

14module Database.PostgreSQL.Simple.Notification

19module Database.PostgreSQL.Simple.Notification

@@ -23,16 +28,20 @@ import Database.PostgreSQL.Simple.Internal

23import qualified Database.PostgreSQL.LibPQ as PQ

28import qualified Database.PostgreSQL.LibPQ as PQ

24import System.Posix.Types ( CPid )

29import System.Posix.Types ( CPid )

26−data Notification = Notification

31+data Notification = Notification

27− { notificationPid :: CPid

32+ { notificationPid :: !CPid

28− , notificationChannel :: B.ByteString

33+ , notificationChannel :: !B.ByteString

29− , notificationData :: B.ByteString

34+ , notificationData :: !B.ByteString

30− }

35+ }

32errfd :: String

37errfd :: String

33errfd = "Database.PostgreSQL.Simple.Notification.getNotification: \

38errfd = "Database.PostgreSQL.Simple.Notification.getNotification: \

34 \failed to fetch file descriptor"

39 \failed to fetch file descriptor"

41+

42+-- | Returns a single notification. If no notifications are available,

43+-- 'getNotification' blocks until one arrives.

44+

36getNotification :: Connection -> IO Notification

45getNotification :: Connection -> IO Notification

37getNotification = loop False

46getNotification = loop False

38 where

47 where

src/Database/PostgreSQL/Simple/Ok.hs+40−7

@@ -1,6 +1,34 @@

1{-# LANGUAGE DeriveDataTypeable #-}

2{-# LANGUAGE DeriveFunctor #-}

4+------------------------------------------------------------------------------

5+-- |

6+-- Module : Database.PostgreSQL.Simple.Ok

8+-- License : BSD3

9+--

10+-- Maintainer : leon@melding-monads.com

11+-- Stability : experimental

12+--

13+-- The 'Ok' type is a simple error handler, basically equivalent to

14+-- @Either [SomeException]@. This type (without the list) was used to

15+-- handle conversion errors in early versions of postgresql-simple.

16+--

17+-- One of the primary reasons why this type was introduced is that

18+-- @Either SomeException@ had not been provided an instance for 'Alternative',

19+-- and it would have been a bad idea to provide an orphaned instance for a

20+-- commonly-used type and typeclass included in @base@.

21+--

22+-- Extending the failure case to a list of 'SomeException's enables a

23+-- more sensible 'Alternative' instance definitions: '<|>' concatinates

24+-- the list of exceptions when both cases fail, and 'empty' is defined as

25+-- 'Errors []'. Though '<|>' one could pick one of two exceptions, and

26+-- throw away the other, and have 'empty' provide a generic exception,

27+-- this avoids cases where 'empty' overrides a more informative exception

28+-- and allows you to see all the different ways your computation has failed.

29+--

30+------------------------------------------------------------------------------

31+

4module Database.PostgreSQL.Simple.Ok where

32module Database.PostgreSQL.Simple.Ok where

6import Control.Applicative

34import Control.Applicative

@@ -8,16 +36,15 @@ import Control.Exception

8import Control.Monad(MonadPlus(..))

36import Control.Monad(MonadPlus(..))

9import Data.Typeable

37import Data.Typeable

11−newtype ManyErrors = ManyErrors [SomeException]

12− deriving (Show, Typeable)

13−

14−instance Exception ManyErrors

15−

16−-- FIXME: [SomeException] should probably be a difference list

39+-- FIXME: [SomeException] should probably be something else, maybe

40+-- a difference list (or a tree?)

18data Ok a = Errors [SomeException] | Ok !a

42data Ok a = Errors [SomeException] | Ok !a

19 deriving(Show, Typeable, Functor)

43 deriving(Show, Typeable, Functor)

45+-- | Two 'Errors' cases are considered equal, regardless of what the

46+-- list of exceptions looks like.

47+

21instance Eq a => Eq (Ok a) where

48instance Eq a => Eq (Ok a) where

22 Errors _ == Errors _ = True

49 Errors _ == Errors _ = True

23 Ok a == Ok b = a == b

50 Ok a == Ok b = a == b

@@ -37,7 +64,6 @@ instance Alternative Ok where

37 Errors _ <|> b@(Ok _) = b

64 Errors _ <|> b@(Ok _) = b

38 Errors as <|> Errors bs = Errors (as ++ bs)

65 Errors as <|> Errors bs = Errors (as ++ bs)

40−

41instance MonadPlus Ok where

67instance MonadPlus Ok where

42 mzero = empty

68 mzero = empty

43 mplus = (<|>)

69 mplus = (<|>)

@@ -53,3 +79,10 @@ instance Monad Ok where

54 -- but *correct*, as this will throw an exception if you try to

80 -- but *correct*, as this will throw an exception if you try to

55 -- examine the exception.

81 -- examine the exception.

82+

83+-- | a way to reify a list of exceptions into a single exception

84+

85+newtype ManyErrors = ManyErrors [SomeException]

86+ deriving (Show, Typeable)

87+

88+instance Exception ManyErrors