Connection Pool

[Hackage ][Hackage: connection-pool] Hackage Dependencies [Haskell Programming Language][Haskell.org] [BSD3 License][tl;dr Legal: BSD3]

Build

Description

Connection pool is a family specialised resource pools. Currently package provides two

  1. pool for TCP client connections,
  2. and pool for UNIX Sockets client connections.

In addition it can be used to build your own connection pool using provided primitives.

This package is built on top of [resource-pool][Hackage: resource-pool] and [streaming-commons][Hackage: streaming-commons]. The later allows us to use conduit-extra package for implementation of TCP or UNIX Sockets clients.

Documentation

Stable releases with API documentation are available on [Hackage][Hackage: connection-pool]

Examples

Simple code examples, including example from the following section, are available in example/ directory.

TCP Client Example

Here is a simple example that demonstrates how TCP client can be created and how connection pool behaves.

{-# LANGUAGE OverloadedStrings #-}
module Main (main)
  where

import Control.Concurrent
    ( forkIO
    , newEmptyMVar
    , putMVar
    , readMVar
    , threadDelay
    )
import Control.Monad (void, mapM_)
import System.Environment (getArgs)

import Control.Lens ((.~), (&))
import Data.ConnectionPool
    ( createTcpClientPool
    , numberOfResourcesPerStripe
    , numberOfStripes
    , withTcpClientConnection
    )
import Data.Default.Class (Default(def))
import Data.Streaming.Network (appWrite, clientSettingsTCP)


main :: IO ()
main = do
    [port, numStripes, numPerStripe] <- getArgs
    pool <- createTcpClientPool
        (poolParams numStripes numPerStripe)
        (clientSettingsTCP (read port) "127.0.0.1")
    thread1 <- newEmptyMVar
    thread2 <- newEmptyMVar
    void . forkIO . withTcpClientConnection pool $ \appData -> do
        threadDelay 1000
        appWrite appData "1: I'm alive!\n"
        putMVar thread1 ()
    void . forkIO . withTcpClientConnection pool $ \appData -> do
        appWrite appData "2: I'm alive!\n"
        putMVar thread2 ()
    mapM_ readMVar [thread1, thread2]
  where
    poolParams m n =
        def & numberOfStripes .~ read m
            & numberOfResourcesPerStripe .~ read n

To test it we can use socat or some netcat like application. Our test will require two terminals, in one we will execute socat as a server listenting on UNIX socket and in the other one we execute above example.

Simple TCP server listening on port 8001 that prints what it receives to stdout:

$ socat TCP4-LISTEN:8001,bind=127.0.0.1,fork -

The fork parameter in the above example is important, otherwise socat would terminate when client closes its connection.

If we run above example as:

$ runghc tcp-example.hs 8001 1 1

We can see that socat received following text:

1: I'm alive!
2: I'm alive!

But if we increment number of stripes or number of connections (resources) per stripe, then we will get:

2: I'm alive!
1: I'm alive!

The reason for this is that we use threadDelay 1000 in the first executed thread. So when we have only one stripe and one connection per stripe, then we have only one connection in the pool. Therefore when the first thread executes and acquires a connection, then all the other threads (the other one in above example) will block. If we have more then one connection available in our pool, then the first thread acquires connection, blocks on threadDelay call, but the other thread also acquires connection and prints its output while the first thread is still blocked on threadDelay. This example demonstrates how connection pool behaves if it reached its capacity and when it has enough free resources.

License

The BSD 3-Clause License, see LICENSE file for details.

Contributions

Contributions, pull requests and bug reports are welcome! Please don't be afraid to contact author using GitHub or by e-mail (see .cabal file for that).

http://hackage.haskell.org/package/conduit-extra [Hackage: connection-pool]: http://hackage.haskell.org/package/connection-pool [Hackage: resource-pool]: http://hackage.haskell.org/package/resource-pool [Hackage: streaming-commons]: http://hackage.haskell.org/package/streaming-commons [Haskell.org]: http://www.haskell.org "The Haskell Programming Language" [tl;dr Legal: BSD3]: https://tldrlegal.com/license/bsd-3-clause-license-%28revised%29 "BSD 3-Clause License (Revised)"

Changes

ChangeLog / ReleaseNotes

Version 0.2.1

Version 0.2

  • Release has backward compatible API with 0.1 branch.
  • Introducing ConnectionPoolFor type class which has instances for both ConnectionPool TcpClient and ConnectionPool UnixClient. Class is located in its own module Data.ConnectionPool.Class, therefore it is part of stable API. It provides withConnection and destroyAllConnections methods which can be used instead of their more specific equivalents. (new)
  • ConnectionPool data family moved in to its own module Data.ConnectionPool.Family, as a consequence it became part of stable API. (change)
  • Introducing tryWithUnixClientConnection and tryWithTcpClientConnection functions. (new)
  • Providing instances of Generic and Show where ever possible and reasonable. This is a backwards compatible change. (new)
  • Internal ConnectionPool data type is now more generic because Socket handle isn't hard-coded in it any more. This change breaks packages depending on internal API. (change)
  • Internal type class HasConnectionPool was introduced to simplify access to ConnectionPool data type wrapped in other types. (new)
  • Internal modules were heavily reorganized and TCP and UNIX Sockets related implementations were moved in to their own modules. This change breaks packages depending on internal API. (change)
  • Heavy inlining of everything. Purpose is to be safe that this library gets abstracted away as much as possible. Best result is if only direct references to [resource-pool][] and [streaming-commons][] remain. (change)
  • Uploaded to [Hackage][]: http://hackage.haskell.org/package/connection-pool-0.2

Version 0.1.3

  • All lenses are now defined as strict, as a consequence lower bound of between is now 0.10.0.0 instead of 0.9.0.0. (change)
  • Support for user defined read buffer size, this was introduced in [streaming-commons][] == 0.1.13. Non-internal library API is backwards compatible. (new)
  • Default buffer size changed in [streaming-commons][] == 0.1.13 to 32kiB, this library uses this value as a default even if it's built with [streaming-commons][] < 0.1.13. For more details see https://github.com/fpco/streaming-commons/issues/22. (change)
  • Uploaded to [Hackage][]: http://hackage.haskell.org/package/connection-pool-0.1.3

Version 0.1.2.1

Version 0.1.2.0

Version 0.1.1.0

  • Package is now buildable on Windows. (new)
  • Introducing function validateResourcePoolParams. (new)
  • Introducing internal function destroyAllConnections. (new)
  • Introducing functions destroyAllTcpClientConnections and destroyAllTcpClientConnections both build on top of destroyAllConnections. (new)
  • Corrected some typos in documentation and Haddock markup.
  • Small documentation enhancements.
  • Uploaded to [Hackage][]: http://hackage.haskell.org/package/connection-pool-0.1.1.0

Version 0.1.0.0

http://hackage.haskell.org/package/between "Function combinator 'between' and derived combinators." [data-default-class]: http://hackage.haskell.org/package/data-default-class "Default type class provides a default value (def) of a type." [Hackage]: http://hackage.haskell.org/ "HackageDB (or just Hackage) is a collection of releases of Haskell packages." [resource-pool]: http://hackage.haskell.org/package/resource-pool "A high-performance striped pooling abstraction for managing resources." [streaming-commons]: http://hackage.haskell.org/package/streaming-commons "Low-dependency functionality commonly needed by various streaming data libraries"

comments powered byDisqus