Improved logic for checking overflow workers

.github/workflows/erlang.yml

@@ -0,0 +1,25 @@
+name: Erlang CI
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+permissions:
+  contents: read
+
+jobs:
+
+  build:
+
+    runs-on: ubuntu-latest
+
+    container:
+      image: erlang:22.0.7
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Compile
+      run: rebar3 compile
+

.gitignore

@@ -1,3 +1,6 @@
+/rebar.lock
+/poolboy.iml
+/.idea
 .eunit
 .rebar
 _build

README.md

@@ -1,14 +1,13 @@
 # Poolboy - A hunky Erlang worker pool factory
 
-[![Build Status](https://api.travis-ci.org/devinus/poolboy.svg?branch=master)](https://travis-ci.org/devinus/poolboy)
-
-[![Support via Gratipay](https://cdn.rawgit.com/gratipay/gratipay-badge/2.3.0/dist/gratipay.png)](https://gratipay.com/devinus/)
+[![Erlang CI](https://github.com/comtihon/poolboy/actions/workflows/erlang.yml/badge.svg)](https://github.com/comtihon/poolboy/actions/workflows/erlang.yml)
 
 Poolboy is a **lightweight**, **generic** pooling library for Erlang with a
 focus on **simplicity**, **performance**, and **rock-solid** disaster recovery.
 
 ## Usage
-
+The most basic use case is to check out a worker, make a call and manually 
+return it to the pool when done
 ```erl-sh
 1> Worker = poolboy:checkout(PoolName).
 <0.9001.0>
@@ -17,7 +16,15 @@ ok
 3> poolboy:checkin(PoolName, Worker).
 ok
 ```
-
+Alternatively you can use a transaction which will return the worker to the 
+pool when the call is finished.
+```erl-sh
+poolboy:transaction(
+    PoolName,
+    fun(Worker) -> gen_server:call(Worker, Request) end, 
+    TransactionTimeout
+)
+```
 ## Example
 
 This is an example application showcasing database connection pools using
@@ -149,23 +156,35 @@ code_change(_OldVsn, State, _Extra) ->
     {ok, State}.
 ```
 
-## Options
+## Pool Options
 
-- `name`: the pool name
-- `worker_module`: the module that represents the workers
-- `size`: maximum pool size
-- `max_overflow`: maximum number of workers created if pool is empty
+- `name`: the pool name - optional
+- `worker_module`: worker module. Can be either a `module` or `{module, function}`.
+Example:
+```
+start_pool(SizeArgs, WorkerArgs) ->
+  PoolArgs = [{worker_module, {mc_worker_api, connect}}] ++ SizeArgs,
+  supervisor:start_child(?MODULE, [PoolArgs, WorkerArgs]).
+```
+In case of just atom `start_link` will be called.
+- `size`: maximum pool size - optional
+- `max_overflow`: maximum number of workers created if pool is empty - optional
 - `strategy`: `lifo` or `fifo`, determines whether checked in workers should be
   placed first or last in the line of available workers. Default is `lifo`.
-
-## Authors
-
-- Devin Torres (devinus) <[email protected]>
-- Andrew Thompson (Vagabond) <[email protected]>
-- Kurt Williams (onkel-dirtus) <[email protected]>
-
-## License
-
-Poolboy is available in the public domain (see `UNLICENSE`).
-Poolboy is also optionally available under the ISC license (see `LICENSE`),
-meant especially for jurisdictions that do not recognize public domain works.
+- `overflow_ttl`: time in milliseconds you want to wait before removing overflow
+  workers. Useful when it's expensive to start workers. Default is 0.
+- `overflow_check_period`: time in milliseconds for checking overflow workers to rip. 
+  Default is min(1 sec, overflow_ttl). Cheking job will not be started, if overflow_ttl is 0.
+
+## Pool Status
+Returns : {Status, Workers, Overflow, InUse}
+- `Status`: ready | full | overflow
+            The ready atom indicates there are workers that are not checked out 
+            ready. The full atom indicates all workers including overflow are 
+            checked out. The overflow atom is used to describe the condition 
+            when all permanent workers are in use but there is overflow capacity 
+            available.
+- `Workers`: Number of workers ready for use.
+- `Overflow`: Number of overflow workers started, should never exceed number 
+              specified by MaxOverflow when starting pool
+- `InUse`: Number of workers currently busy/checked out

src/poolboy.app.src

@@ -1,6 +1,6 @@
 {application, poolboy, [
     {description, "A hunky Erlang worker pool factory"},
-    {vsn, "1.5.1"},
+    {vsn, "1.6.1"},
     {applications, [kernel, stdlib]},
     {registered, [poolboy]},