-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | LISTEN/NOTIFY support for Hasql
--   
--   Use PostgreSQL Asynchronous notification support with your Hasql
--   Types.
@package hasql-notifications
@version 0.2.0.6


-- | This module has functions to send commands LISTEN and NOTIFY to the
--   database server. It also has a function to wait for and handle
--   notifications on a database connection.
--   
--   For more information check the <a>PostgreSQL documentation</a>.
module Hasql.Notifications

-- | Given a Hasql Pool, a channel and a message sends a notify command to
--   the database
notifyPool :: Pool -> Text -> Text -> IO (Either UsageError ())

-- | Given a Hasql Connection, a channel and a message sends a notify
--   command to the database
notify :: Connection -> PgIdentifier -> Text -> IO (Either QueryError ())

-- | Given a Hasql Connection and a channel sends a listen command to the
--   database. Once the connection sends the LISTEN command the server
--   register its interest in the channel. Hence it's important to keep
--   track of which connection was used to open the listen command.
--   
--   Example of listening and waiting for a notification:
--   
--   <pre>
--   import System.Exit (die)
--   
--   import Hasql.Connection
--   import Hasql.Notifications
--   
--   main :: IO ()
--   main = do
--     dbOrError &lt;- acquire "postgres:/<i>localhost</i>db_name"
--     case dbOrError of
--         Right db -&gt; do
--             let channelToListen = toPgIdentifier "sample-channel"
--             listen db channelToListen
--             waitForNotifications (channel _ -&gt; print $ "Just got notification on channel " &lt;&gt; channel) db
--         _ -&gt; die "Could not open database connection"
--   
--   </pre>
listen :: Connection -> PgIdentifier -> IO ()

-- | Given a Hasql Connection and a channel sends a unlisten command to the
--   database
unlisten :: Connection -> PgIdentifier -> IO ()

-- | Given a function that handles notifications and a Hasql connection it
--   will listen on the database connection and call the handler everytime
--   a message arrives.
--   
--   The message handler passed as first argument needs two parameters
--   channel and payload. See an example of handling notification on a
--   separate thread:
--   
--   <pre>
--   import Control.Concurrent.Async (async)
--   import Control.Monad (void)
--   import System.Exit (die)
--   
--   import Hasql.Connection
--   import Hasql.Notifications
--   
--   notificationHandler :: ByteString -&gt; ByteString -&gt; IO()
--   notificationHandler channel payload = 
--     void $ async do
--       print $ "Handle payload " &lt;&gt; payload &lt;&gt; " in its own thread"
--   
--   main :: IO ()
--   main = do
--     dbOrError &lt;- acquire "postgres:/<i>localhost</i>db_name"
--     case dbOrError of
--         Right db -&gt; do
--             let channelToListen = toPgIdentifier "sample-channel"
--             listen db channelToListen
--             waitForNotifications notificationHandler db
--         _ -&gt; die "Could not open database connection"
--   
--   </pre>
waitForNotifications :: (ByteString -> ByteString -> IO ()) -> Connection -> IO ()

-- | A wrapped text that represents a properly escaped and quoted
--   PostgreSQL identifier
data PgIdentifier

-- | Given a text returns a properly quoted and escaped PgIdentifier
toPgIdentifier :: Text -> PgIdentifier

-- | Given a PgIdentifier returns the wrapped text
fromPgIdentifier :: PgIdentifier -> Text
instance GHC.Show.Show Hasql.Notifications.PgIdentifier
instance GHC.Show.Show Hasql.Notifications.FatalError
instance GHC.Exception.Type.Exception Hasql.Notifications.FatalError
