Database.PostgreSQL.LibPQ.Notify

Support for receiving asynchronous notifications via PostgreSQL's Listen/Notify mechanism. See http://www.postgresql.org/docs/9.4/static/sql-notify.html for more information.

Note that on Windows, getNotification currently uses a polling loop of 1 second to check for more notifications, due to some inadequacies in GHC's IO implementation and interface on that platform. See GHC issue #7353 for more information. While this workaround is less than ideal, notifications are still better than polling the database directly. Notifications do not create any extra work for the backend, and are likely cheaper on the client side as well.

http://hackage.haskell.org/trac/ghc/ticket/7353

PostgreSQL notifications support using the same connection for sending and receiving notifications.

However this implementation cannot support this usage pattern.

This implementation favors low latency by utilizing socket read notifications. However a consequence of this implementation choice is the connection used to wait for the notification cannot be used for anything else.

Documentation

getNotification

Arguments

:: Connection

The connection. The connection cannot be used for anything else while waiting on the notification or this call might never return.

-> IO (Either IOError Notify)

Returns a single notification. If no notifications are available, getNotification blocks until one arrives.

The connection passed in cannot be used for anything else while waiting on the notification or this call might never return.

Note that PostgreSQL does not deliver notifications while a connection is inside a transaction.

Advanced API

getNotificationWithConfig

Arguments

:: Config

Config to instrument and configure the retry period on Windows.

-> Connection

The connection. The connection cannot be used for anything else while waiting on the notification or this call might never return.

-> IO (Either IOError Notify)

Returns a single notification. If no notifications are available, getNotificationWithConfig blocks until one arrives. Unlike getNotification, getNotificationWithConfig takes in an additional Config parameter provides event hooks for operational insight.

The connection passed in cannot be used for anything else while waiting on the notification or this call might never return.

Note that PostgreSQL does not deliver notifications while a connection is inside a transaction.

defaultConfig :: Config

Default configuration

data Config

Options for controlling and instrumenting the behavior of getNotificationWithConfig

Constructors

Config

Fields

• startLoop :: IO ()

  Called each time getNotificationWithConfig loops to look for another notification

• beforeWait :: IO ()

  Event called before the thread will wait on threadWaitReadSTM action.