content: {-|
  Module: Squeal.PostgreSQL.Pool
  Description: connection pools
  Copyright: (c) Eitan Chatav, 2019
  Maintainer: eitan@morphism.tech
  Stability: experimental
  
  Connection pools.
  
  Typical use case would be to create your pool using `createConnectionPool`
  and run anything that requires the pool connection with `usingConnectionPool`.
  
  Here's a simplified example:
  
  >>> import Squeal.PostgreSQL
  
  >>> :{
  do
    let
      qry :: Query_ (Public '[]) () (Only Char)
      qry = values_ (inline 'a' `as` #fromOnly)
    pool <- createConnectionPool "host=localhost port=5432 dbname=exampledb user=postgres password=postgres" 1 0.5 10
    chr <- usingConnectionPool pool $ do
      result <- runQuery qry
      Just (Only a) <- firstRow result
      return a
    destroyConnectionPool pool
    putChar chr
  :}
  a
  -}
  
  {-# LANGUAGE
      CPP
    , DeriveFunctor
    , FlexibleContexts
    , FlexibleInstances
    , InstanceSigs
    , MultiParamTypeClasses
    , PolyKinds
    , RankNTypes
    , ScopedTypeVariables
    , TypeFamilies
    , DataKinds
    , PolyKinds
    , UndecidableInstances
  #-}
  
  module Squeal.PostgreSQL.Session.Pool
    ( -- * Pool
      Pool
    , createConnectionPool
    , usingConnectionPool
    , destroyConnectionPool
    ) where
  
  import Control.Monad.Catch
  import Control.Monad.IO.Class
  import Data.ByteString
  import Data.Time
  import Data.Pool
  
  import Squeal.PostgreSQL.Type.Schema
  import Squeal.PostgreSQL.Session (PQ (..))
  import Squeal.PostgreSQL.Session.Connection
  
  -- | Create a striped pool of connections.
  -- Although the garbage collector will destroy all idle connections when the pool is garbage collected it's recommended to manually `destroyConnectionPool` when you're done with the pool so that the connections are freed up as soon as possible.
  createConnectionPool
    :: forall (db :: SchemasType) io. MonadIO io
    => ByteString
    -- ^ The passed string can be empty to use all default parameters, or it can
    -- contain one or more parameter settings separated by whitespace.
    -- Each parameter setting is in the form keyword = value. Spaces around the equal
    -- sign are optional. To write an empty value or a value containing spaces,
    -- surround it with single quotes, e.g., keyword = 'a value'. Single quotes and
    -- backslashes within the value must be escaped with a backslash, i.e., ' and \.
    -> Int
    -- ^ The number of stripes (distinct sub-pools) to maintain. The smallest acceptable value is 1.
    -> NominalDiffTime
    -- ^ Amount of time for which an unused connection is kept open. The smallest acceptable value is 0.5 seconds.
    -- The elapsed time before destroying a connection may be a little longer than requested, as the reaper thread wakes at 1-second intervals.
    -> Int
    -- ^ Maximum number of connections to keep open per stripe. The smallest acceptable value is 1.
    -- Requests for connections will block if this limit is reached on a single stripe, even if other stripes have idle connections available.
    -> io (Pool (K Connection db))
  createConnectionPool conninfo stripes idle maxResrc =
  #if MIN_VERSION_resource_pool(0,4,0)
    liftIO . newPool $ setNumStripes
      (Just stripes)
      (defaultPoolConfig (connectdb conninfo) finish (realToFrac idle) maxResrc)
  #else
    liftIO $ createPool (connectdb conninfo) finish stripes idle maxResrc
  #endif
  
  {-|
  Temporarily take a connection from a `Pool`, perform an action with it,
  and return it to the pool afterwards.
  
  If the pool has an idle connection available, it is used immediately.
  Otherwise, if the maximum number of connections has not yet been reached,
  a new connection is created and used.
  If the maximum number of connections has been reached, this function blocks
  until a connection becomes available.
  -}
  usingConnectionPool
    :: (MonadIO io, MonadMask io)
    => Pool (K Connection db) -- ^ pool
    -> PQ db db io x -- ^ session
    -> io x
  usingConnectionPool pool (PQ session) = mask $ \restore -> do
    (conn, local) <- liftIO $ takeResource pool
    ret <- restore (session conn) `onException`
              liftIO (destroyResource pool local conn)
    liftIO $ putResource local conn
    return $ unK ret
  
  {- |
  Destroy all connections in all stripes in the pool.
  Note that this will ignore any exceptions in the destroy function.
  
  This function is useful when you detect that all connections
  in the pool are broken. For example after a database has been
  restarted all connections opened before the restart will be broken.
  In that case it's better to close those connections so that
  `usingConnectionPool` won't take a broken connection from the pool
  but will open a new connection instead.
  
  Another use-case for this function is that when you know you are done
  with the pool you can destroy all idle connections immediately
  instead of waiting on the garbage collector to destroy them,
  thus freeing up those connections sooner.
  -}
  destroyConnectionPool
    :: MonadIO io
    => Pool (K Connection db) -- ^ pool
    -> io ()
  destroyConnectionPool = liftIO . destroyAllResources
  