Safe Haskell	None
Language	GHC2024

Arbiter.Core.Backend

Contents

Database monad
Environment creation
Pool state

Description

The env, monad, pool state, and savepoint ladder shared by the pooled backends.

This is the API for backend authors.

Synopsis

newtype Db conn cfg (registry :: JobPayloadRegistry) (m :: Type -> Type) a = Db {
- unDb :: ReaderT (Env conn cfg registry) m a
}
data Env conn cfg (registry :: JobPayloadRegistry) = Env {
- schema :: SchemaName
- poolState :: PoolState conn
- listener :: Maybe Listener
- driverConfig :: cfg
}
data Driver conn cfg = Driver {
- withListenConn :: conn -> (ListenConn -> IO ()) -> IO ()
- initialConfig :: cfg
}
runDb :: forall conn cfg (registry :: JobPayloadRegistry) m a. Env conn cfg registry -> Db conn cfg registry m a -> m a
inTransaction :: forall conn cfg (registry :: JobPayloadRegistry) m a. Driver conn cfg -> conn -> SchemaName -> Db conn cfg registry m a -> m a
createEnvWithConfig :: forall m conn cfg (registry :: JobPayloadRegistry). MonadIO m => Driver conn cfg -> IO conn -> (conn -> IO ()) -> SchemaName -> PoolConfig -> m (Env conn cfg registry)
createEnvWithPool :: forall m conn cfg (registry :: JobPayloadRegistry). MonadIO m => Driver conn cfg -> Pool conn -> SchemaName -> m (Env conn cfg registry)
destroyEnv :: forall m conn cfg (registry :: JobPayloadRegistry). MonadIO m => Env conn cfg registry -> m ()
disableListener :: forall conn cfg (registry :: JobPayloadRegistry). Env conn cfg registry -> Env conn cfg registry
useDedicatedListener :: forall m conn cfg (registry :: JobPayloadRegistry). MonadIO m => ((ListenConn -> IO ()) -> IO ()) -> Env conn cfg registry -> m (Env conn cfg registry)
poolListener :: Driver conn cfg -> Pool conn -> IO Listener
data PoolState conn = PoolState {
- connectionPool :: Maybe (Pool conn)
- pinned :: Maybe (conn, Int)
}
class Monad m => HasPoolState conn (m :: Type -> Type) | m -> conn where
- getPoolState :: m (PoolState conn)
- localPoolState :: (PoolState conn -> PoolState conn) -> m a -> m a
withConn :: (HasPoolState conn m, MonadUnliftIO m) => (conn -> m a) -> m a
pinConnection :: (HasPoolState conn m, MonadUnliftIO m) => m a -> m a
withSavepointTransaction :: (HasPoolState conn m, MonadUnliftIO m) => (conn -> ByteString -> IO ()) -> (conn -> IO a -> IO a) -> m a -> m a

Database monad

newtype Db conn cfg (registry :: JobPayloadRegistry) (m :: Type -> Type) aSource #

A pooled backend's database monad.

Constructors

Db
Fields unDb :: ReaderT (Env conn cfg registry) m a The action as a reader over its env.

Instances

Instances details

Monad m => HasPoolState conn (Db conn cfg registry m) Source #
Instance details Defined in Arbiter.Core.Backend Methods getPoolState :: Db conn cfg registry m (PoolState conn)Source # localPoolState :: (PoolState conn -> PoolState conn) -> Db conn cfg registry m a -> Db conn cfg registry m aSource #
Monad m => MonadReader (Env conn cfg registry) (Db conn cfg registry m) Source #
Instance details Defined in Arbiter.Core.Backend Methods ask :: Db conn cfg registry m (Env conn cfg registry)# local :: (Env conn cfg registry -> Env conn cfg registry) -> Db conn cfg registry m a -> Db conn cfg registry m a# reader :: (Env conn cfg registry -> a) -> Db conn cfg registry m a#
MonadCatch m => MonadCatch (Db conn cfg registry m) Source #
Instance details Defined in Arbiter.Core.Backend Methods catch :: (HasCallStack, Exception e) => Db conn cfg registry m a -> (e -> Db conn cfg registry m a) -> Db conn cfg registry m a# catchNoPropagate :: Exception e => Db conn cfg registry m a -> (ExceptionWithContext e -> Db conn cfg registry m a) -> Db conn cfg registry m a#
MonadMask m => MonadMask (Db conn cfg registry m) Source #
Instance details Defined in Arbiter.Core.Backend Methods mask :: HasCallStack => ((forall a. Db conn cfg registry m a -> Db conn cfg registry m a) -> Db conn cfg registry m b) -> Db conn cfg registry m b# uninterruptibleMask :: HasCallStack => ((forall a. Db conn cfg registry m a -> Db conn cfg registry m a) -> Db conn cfg registry m b) -> Db conn cfg registry m b# generalBracket :: HasCallStack => Db conn cfg registry m a -> (a -> ExitCase b -> Db conn cfg registry m c) -> (a -> Db conn cfg registry m b) -> Db conn cfg registry m (b, c)#
MonadThrow m => MonadThrow (Db conn cfg registry m) Source #
Instance details Defined in Arbiter.Core.Backend Methods throwM :: (HasCallStack, Exception e) => e -> Db conn cfg registry m a# rethrowM :: Exception e => ExceptionWithContext e -> Db conn cfg registry m a#
Applicative m => Applicative (Db conn cfg registry m) Source #
Instance details Defined in Arbiter.Core.Backend Methods pure :: a -> Db conn cfg registry m a# (<>) :: Db conn cfg registry m (a -> b) -> Db conn cfg registry m a -> Db conn cfg registry m b# liftA2 :: (a -> b -> c) -> Db conn cfg registry m a -> Db conn cfg registry m b -> Db conn cfg registry m c# (>) :: Db conn cfg registry m a -> Db conn cfg registry m b -> Db conn cfg registry m b# (<*) :: Db conn cfg registry m a -> Db conn cfg registry m b -> Db conn cfg registry m a#
Functor m => Functor (Db conn cfg registry m) Source #
Instance details Defined in Arbiter.Core.Backend Methods fmap :: (a -> b) -> Db conn cfg registry m a -> Db conn cfg registry m b# (<$) :: a -> Db conn cfg registry m b -> Db conn cfg registry m a#
Monad m => Monad (Db conn cfg registry m) Source #
Instance details Defined in Arbiter.Core.Backend Methods (>>=) :: Db conn cfg registry m a -> (a -> Db conn cfg registry m b) -> Db conn cfg registry m b# (>>) :: Db conn cfg registry m a -> Db conn cfg registry m b -> Db conn cfg registry m b# return :: a -> Db conn cfg registry m a#
MonadFail m => MonadFail (Db conn cfg registry m) Source #
Instance details Defined in Arbiter.Core.Backend Methods fail :: HasCallStack => String -> Db conn cfg registry m a#
MonadIO m => MonadIO (Db conn cfg registry m) Source #
Instance details Defined in Arbiter.Core.Backend Methods liftIO :: IO a -> Db conn cfg registry m a#
MonadUnliftIO m => MonadUnliftIO (Db conn cfg registry m) Source #
Instance details Defined in Arbiter.Core.Backend Methods withRunInIO :: ((forall a. Db conn cfg registry m a -> IO a) -> IO b) -> Db conn cfg registry m b#

data Env conn cfg (registry :: JobPayloadRegistry)Source #

Schema name, pool state, listener, and the driver's own state.

Constructors

Env
Fields schema :: SchemaName The schema the arbiter tables live in. poolState :: PoolState conn The pool and the pinned connection. listener :: Maybe Listener Resolved LISTEN source. `Nothing` runs poll-only. driverConfig :: cfg The driver's own state.

Instances

Instances details

Monad m => MonadReader (Env conn cfg registry) (Db conn cfg registry m) Source #
Instance details Defined in Arbiter.Core.Backend Methods ask :: Db conn cfg registry m (Env conn cfg registry)# local :: (Env conn cfg registry -> Env conn cfg registry) -> Db conn cfg registry m a -> Db conn cfg registry m a# reader :: (Env conn cfg registry -> a) -> Db conn cfg registry m a#

data Driver conn cfgSource #

What a connection type contributes to its env.

Constructors

Driver
Fields withListenConn :: conn -> (ListenConn -> IO ()) -> IO () Run the listener loop on a connection's driver handle. initialConfig :: cfg The driver state a new env starts with.

runDb :: forall conn cfg (registry :: JobPayloadRegistry) m a. Env conn cfg registry -> Db conn cfg registry m a -> m aSource #

Run a Db action in its env.

inTransaction :: forall conn cfg (registry :: JobPayloadRegistry) m a. Driver conn cfg -> conn -> SchemaName -> Db conn cfg registry m a -> m aSource #

Run a Db action on one connection pinned as the caller's open transaction.

Environment creation

createEnvWithConfig :: forall m conn cfg (registry :: JobPayloadRegistry). MonadIO m => Driver conn cfg -> IO conn -> (conn -> IO ()) -> SchemaName -> PoolConfig -> m (Env conn cfg registry)Source #

Create an env over a new pool opened with the connect and release actions. While anything listens, the listener holds one pool slot.

createEnvWithPool :: forall m conn cfg (registry :: JobPayloadRegistry). MonadIO m => Driver conn cfg -> Pool conn -> SchemaName -> m (Env conn cfg registry)Source #

Create an env over a caller's own connection pool. While anything listens, the listener holds one pool slot.

destroyEnv :: forall m conn cfg (registry :: JobPayloadRegistry). MonadIO m => Env conn cfg registry -> m ()Source #

Close the idle connections in the env's pool. Connections in use stay open and go back to the pool. The pool stays usable.

disableListener :: forall conn cfg (registry :: JobPayloadRegistry). Env conn cfg registry -> Env conn cfg registrySource #

Turn off the shared LISTEN listener for an env, running poll-only.

useDedicatedListener :: forall m conn cfg (registry :: JobPayloadRegistry). MonadIO m => ((ListenConn -> IO ()) -> IO ()) -> Env conn cfg registry -> m (Env conn cfg registry)Source #

Give the env a LISTEN connection of its own from a connection runner.

poolListener :: Driver conn cfg -> Pool conn -> IO ListenerSource #

A listener that borrows one pool connection for the hub's lifetime.

Pool state

data PoolState connSource #

Pool and the pinned connection with its transaction depth.

Constructors

PoolState
Fields connectionPool :: Maybe (Pool conn) The pool to check connections out of. `Nothing` for a pinned-only env. pinned :: Maybe (conn, Int) The pinned connection and its transaction depth. Depth 0 means no open transaction.

class Monad m => HasPoolState conn (m :: Type -> Type) | m -> conn whereSource #

Ambient access to the pool state.

Methods

getPoolState :: m (PoolState conn)Source #

The current pool state.

localPoolState :: (PoolState conn -> PoolState conn) -> m a -> m aSource #

Run an action under an adjusted pool state.

Instances

Instances details

Monad m => HasPoolState conn (Db conn cfg registry m) Source #
Instance details Defined in Arbiter.Core.Backend Methods getPoolState :: Db conn cfg registry m (PoolState conn)Source # localPoolState :: (PoolState conn -> PoolState conn) -> Db conn cfg registry m a -> Db conn cfg registry m aSource #

withConn :: (HasPoolState conn m, MonadUnliftIO m) => (conn -> m a) -> m aSource #

The pinned connection, or one checked out of the pool.

pinConnection :: (HasPoolState conn m, MonadUnliftIO m) => m a -> m aSource #

Pin one pooled connection for the action.

withSavepointTransaction :: (HasPoolState conn m, MonadUnliftIO m) => (conn -> ByteString -> IO ()) -> (conn -> IO a -> IO a) -> m a -> m aSource #

Transaction bracket over the backend's own statement runner and bracket. Nests via savepoints.