Add an advice for library authors

README.md

@@ -7,3 +7,38 @@
 
 A high-performance striped resource pooling implementation for Haskell based on
 [QSem](https://hackage.haskell.org/package/base/docs/Control-Concurrent-QSem.html).
+
+## Advice for library authors
+
+If your library creates a pool on behalf of its users, don't expose your own,
+restricted set of pool parameters (size, TTL, ...) and construct the
+`PoolConfig` internally. Such a config inevitably lags behind features of this
+library (stripe count, labels, whatever comes next) and users can't take
+advantage of them without waiting for you to mirror each one.
+
+Instead, take a function of type `IO a -> (a -> IO ()) -> PoolConfig a` as a
+parameter. Your library supplies the resource creation and destruction actions:
+
+```haskell
+createConnectionPool
+  :: ConnectionSettings
+  -> (IO Connection -> (Connection -> IO ()) -> PoolConfig Connection)
+  -> IO (Pool Connection)
+createConnectionPool settings mkPoolConfig =
+  newPool $ mkPoolConfig connect disconnect
+  where
+    connect :: IO Connection
+    connect = ...
+
+    disconnect :: Connection -> IO ()
+    disconnect = ...
+```
+
+while users retain full control over the rest of the pool configuration:
+
+```haskell
+pool <- createConnectionPool settings $ \create free ->
+  setPoolLabel "db"
+    . setNumStripes (Just 1)
+    $ defaultPoolConfig create free 60 10
+```