Merge branch 'release/v0.8.0' into main

.github/workflows/ci-tests.yml

@@ -41,7 +41,7 @@ jobs:
           otp-version: ${{matrix.otp}}
           elixir-version: ${{matrix.elixir}}
       - name: Fetch dependencies
-        run: mix do deps.get, compile
+        run: mix deps.get --only test
       - name: Launch tests
         run: mix test
   static-analysis:

CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2023-08-30
+
+### Changed
+
+#### Breaking changes
+
+- Option `:timeout` renamed to `:checkout_timeout`.
+  - Reason: This option configures only the waiting time for `worker` from the pool, not the task's work time. This naming should be more understandable on the call site.
+
+    ```elixir
+    # Before
+    Poolex.run(:my_awesome_pool, fn worker -> some_work(worker) end, timeout: 10_000)
+
+    # After
+    Poolex.run(:my_awesome_pool, fn worker -> some_work(worker) end, checkout_timeout: 10_000)
+    ```
+
+- `Poolex.run/3` returns tuple `{:error, :checkout_timeout}` instead of `:all_workers_are_busy`.
+  - Reason: It is easier to understand the uniform format of the response from the function: `{:ok, result}` or `{:error, reason}`.
+- `Poolex.caller()` type replaced with struct defined in `Poolex.Caller.t()`.
+  - Reason: We need to save unique caller references.
+- `Poolex.run!/3` was removed in favor of `Poolex.run/3`. The new unified function returns `{:ok, result}` or `{:error, :checkout_timeout}` and not handles runtime errors anymore.
+  - Reason: We should not catch errors in the caller process. The caller process itself must choose how to handle exceptions and exit signals.
+
+### Fixed
+
+- Fixed a bug when workers get stuck in `busy` status after checkout timeout.
+
 ## [0.7.6] - 2023-08-03
 
 ### Fixed
@@ -205,7 +233,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Supported main interface `Poolex.run/3` with `:timeout` option.
 
-[unreleased]: https://github.com/general-CbIC/poolex/compare/v0.7.5...HEAD
+[unreleased]: https://github.com/general-CbIC/poolex/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/general-CbIC/poolex/compare/v0.7.6...v0.8.0
+[0.7.6]: https://github.com/general-CbIC/poolex/compare/v0.7.5...v0.7.6
 [0.7.5]: https://github.com/general-CbIC/poolex/compare/v0.7.4...v0.7.5
 [0.7.4]: https://github.com/general-CbIC/poolex/compare/v0.7.3...v0.7.4
 [0.7.3]: https://github.com/general-CbIC/poolex/compare/v0.7.2...v0.7.3

README.md

@@ -4,7 +4,7 @@
 [![hex.pm version](https://img.shields.io/hexpm/v/poolex.svg?style=flat)](https://hex.pm/packages/poolex)
 [![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg?style=flat)](https://hexdocs.pm/poolex/)
 [![License](https://img.shields.io/hexpm/l/poolex.svg?style=flat)](https://github.com/general-CbIC/poolex/blob/main/LICENSE)
-<!-- [![Total Download](https://img.shields.io/hexpm/dt/poolex.svg?style=flat)](https://hex.pm/packages/poolex) -->
+[![Total Download](https://img.shields.io/hexpm/dt/poolex.svg?style=flat)](https://hex.pm/packages/poolex)
 
 Poolex is a library for managing pools of workers. Inspired by [poolboy](https://github.com/devinus/poolboy).
 
@@ -79,7 +79,7 @@ Supervisor.start_link(children, strategy: :one_for_one)
 Then you can execute any code on the workers with `run/3`:
 
 ```elixir
-iex> Poolex.run(:worker_pool, &(is_pid?(&1)), timeout: 1_000)
+iex> Poolex.run(:worker_pool, &(is_pid?(&1)), checkout_timeout: 1_000)
 {:ok, true}
 ```
 

docs/guides/example-of-use.cheatmd

@@ -65,7 +65,7 @@ defmodule PoolexExample.Test do
 
   defp async_call_square_root(i) do
     Task.async(fn ->
-      Poolex.run!(
+      Poolex.run(
         :worker_pool,
         fn pid ->
           # Let's wrap the genserver call in a try-catch block. This allows us to trap any exceptions
@@ -79,7 +79,7 @@ defmodule PoolexExample.Test do
               :ok
           end
         end,
-        timeout: @timeout
+        checkout_timeout: @timeout
       )
     end)
   end

docs/guides/getting-started.cheatmd

@@ -40,20 +40,18 @@ The second argument should contain a set of options for starting the pool.
 
 ## Working with the pool
 
-After the pool is initialized, you can get a free worker and perform any operations on it. This is done through the main interfaces `run/3` and `run!/3`. The functions work the same and the only difference between them is that `run/3` takes care of the runtime error handling.
+After the pool is initialized, you can get a free worker and perform any operations on it. This is done through the main interface `run/3`.
 
 The first argument is the name of the pool mentioned above.
 
 The second argument is the function that takes the pid of the worker as the only parameter and performs the necessary actions.
 
-The third argument contains run options. Currently, there is only one `timeout` option that tells Poolex how long we can wait for a worker on the call site.
+The third argument contains run options. Currently, there is only one `checkout_timeout` option that tells Poolex how long we can wait for a worker on the call site.
 
 ```elixir
 iex> Poolex.start_link(pool_id: :agent_pool, worker_module: Agent, worker_args: [fn -> 5 end], workers_count: 1)
 iex> Poolex.run(:agent_pool, fn pid -> Agent.get(pid, &(&1)) end)
 {:ok, 5}
-iex> Poolex.run!(:agent_pool, fn pid -> Agent.get(pid, &(&1)) end)
-5
 ```
 
 If you would like to see examples of using Poolex, then check out [Example of Use](https://hexdocs.pm/poolex/example-of-use.html).

docs/guides/migration-from-poolboy.cheatmd

@@ -55,18 +55,18 @@ end
 
 ### III. Update call site
 
-Use `run!/3` to leave the same behavior. 
-If you want a safe interface with error handling, then use `run/3`.
+Use `run/3`.
+Be careful, unlike `:poolboy.transaction`, `Poolex.run` returns `{:ok, result}`.
 
 ```diff
 -  :poolboy.transaction(
 -    :some_pool,
 -    fn pid -> some_function(pid) end,
 -    :timer.seconds(10)
 -  )
-+  Poolex.run!(
++  Poolex.run(
 +    :some_pool,
 +    fn pid -> some_function(pid) end,
-+    timeout: :timer.seconds(10)
++    checkout_timeout: :timer.seconds(10)
 +  )
 ```

docs/guides/workers-and-callers-implementations.md

@@ -4,7 +4,7 @@
 
 ## Callers
 
-`Callers` are processes that have requested to get a worker (used `run/3` or `run!/3`). Each pool keeps the information about `callers` to distribute workers to them when they are free.
+`Callers` are processes that have requested to get a worker (used `run/3`). Each pool keeps the information about `callers` to distribute workers to them when they are free.
 
 > ### Caller's typespec {: .warning}
 >

examples/poolex_example/lib/poolex_example/test.ex

@@ -20,7 +20,7 @@ defmodule PoolexExample.Test do
               :ok
           end
         end,
-        timeout: @timeout
+        checkout_timeout: @timeout
       )
     end)
   end