Merge branch 'release/v1.2.0' into main

Author: general-CbIC

.github/workflows/ci-tests.yml

@@ -38,6 +38,8 @@ jobs:
             otp: '26'
           - elixir: '1.17'
             otp: '27'
+          - elixir: '1.18'
+            otp: '27'
     steps:
       - uses: actions/checkout@v4
       - uses: erlef/setup-beam@v1

.tool-versions

@@ -1,2 +1,2 @@
-erlang 27.1
-elixir 1.17.3-otp-27
+erlang 27.2
+elixir 1.18.1-otp-27

CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2025-01-07
+
+### Added
+
+- Added Elixir 1.18.* support to CI.
+
+### Changed
+
+- Refactored tests with new [ExUnit parameterize feature](https://hexdocs.pm/ex_unit/1.18.0/ExUnit.Case.html#module-parameterized-tests).
+- `:pool_id` is not required init option anymore. For now it is equal to `worker_module` option value.
+
+### Fixed
+
+- Functions `Poolex.add_idle_workers!/2` and `Poolex.remove_idle_workers!/2` now accept any value of type `GenServer.name()` as their first argument, instead of only `atom()`.
+- Supressed Supervisor's error logs in tests.
+  
+
 ## [1.1.0] - 2024-12-08
 
 ### Added
@@ -15,13 +32,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- Monitoring implemetation has been optimized by using plain map instead of `Agent` process.
-- Refactored `State` struct by adding list of `@enforced_keys`. ([Details](https://hexdocs.pm/elixir/structs.html#default-values-and-required-keys))
+- Monitoring implementation has been optimized by using a plain map instead of the `Agent` process.
+- Refactored `State` struct by adding a list of `@enforced_keys`. ([Details](https://hexdocs.pm/elixir/structs.html#default-values-and-required-keys))
 - Poolex processes now have higher priority. ([Details](https://www.erlang.org/doc/apps/erts/erlang.html#process_flag_priority))
 
 ### Deprecated
 
-- `Poolex.get_state/1` deprecated in favor `:sys.get_state/1`.
+- `Poolex.get_state/1` deprecated in favor of `:sys.get_state/1`.
 
 ## [1.0.0] - 2024-09-23
 
@@ -273,7 +290,8 @@ 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/v1.1.0...HEAD
+[unreleased]: https://github.com/general-CbIC/poolex/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/general-CbIC/poolex/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/general-CbIC/poolex/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/general-CbIC/poolex/compare/v0.10.0...v1.0.0
 [0.10.0]: https://github.com/general-CbIC/poolex/compare/v0.9.0...v0.10.0

README.md

@@ -5,12 +5,16 @@
 [![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)
-[![Chat on Matrix](https://matrix.to/img/matrix-badge.svg?style=flat)](https://matrix.to/#/#poolex:gitter.im)
 
 Poolex is a library for managing pools of workers. Inspired by [poolboy](https://github.com/devinus/poolboy).
 
+> [!IMPORTANT]  
+> Documentation on GitHub corresponds to the current branch. For stable versions' docs see [Hexdocs](https://hexdocs.pm/poolex/).
+
 ## Table of Contents
 
+<img alt="Poolex logo" src="https://raw.githubusercontent.com/general-CbIC/poolex/develop/assets/poolex.png" width="250" height="250" align="right"/>
+
 - [Poolex](#poolex)
   - [Table of Contents](#table-of-contents)
   - [Features](#features)
@@ -59,8 +63,7 @@ In the most typical use of Poolex, you only need to start a pool of workers as a
 
 ```elixir
 children = [
-  {Poolex, 
-    pool_id: :worker_pool,
+  {Poolex,
     worker_module: SomeWorker,
     workers_count: 5}
 ]
@@ -71,7 +74,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)), checkout_timeout: 1_000)
+iex> Poolex.run(SomeWorker, &(is_pid?(&1)), checkout_timeout: 1_000)
 {:ok, true}
 ```
 

assets/poolex.png

@@ -38,7 +38,6 @@ defmodule PoolexExample.Application do
   def start(_type, _args) do
     children = [
       {Poolex,
-       pool_id: :worker_pool,
        worker_module: PoolexExample.Worker,
        workers_count: 5,
        max_overflow: 2}
@@ -66,7 +65,7 @@ defmodule PoolexExample.Test do
   defp async_call_square_root(i) do
     Task.async(fn ->
       Poolex.run(
-        :worker_pool,
+        PoolexExample.Worker,
         fn pid ->
           # Let's wrap the genserver call in a try-catch block. This allows us to trap any exceptions
           # that might be thrown and return the worker to Poolex in a clean manner. It also allows

docs/guides/example-of-use.cheatmd

@@ -5,15 +5,14 @@
 To start a pool you can use either `start/1` or `start_link/1`.
 
 ```elixir
-Poolex.start_link(pool_id: :my_pool, worker_module: SomeWorker, workers_count: 10)
+Poolex.start_link(worker_module: SomeWorker, workers_count: 10)
 ```
 
 In general, you should place it into your Supervision tree for fault tolerance.
 
 ```elixir
 children = [
   {Poolex,
-  pool_id: :my_pool,
   worker_module: SomeWorker,
   workers_count: 10,
   max_overflow: 10}
@@ -22,13 +21,11 @@ children = [
 Supervisor.start_link(children, strategy: :one_for_one)
 ```
 
-The second argument should contain a set of options for starting the pool.
-
 ## Poolex configuration options
 
 | Option                 | Description                                          | Example               | Default value                     |
 |------------------------|------------------------------------------------------|-----------------------|-------------------------|
-| `pool_id`              | Identifier by which you will access the pool         | `:my_pool`            | **option is required**               |
+| `pool_id`              | Identifier by which you will access the pool         | `:my_pool`            | `worker_module` value                    |
 | `worker_module`        | Name of module that implements our worker            | `MyApp.Worker`        | **option is required**               |
 | `workers_count`        | How many workers should be running in the pool       | `5`                   | **option is required**               |
 | `max_overflow`         | How many workers can be created over the limit       | `2`                   | `0`                      |
@@ -51,7 +48,7 @@ The third argument contains run options. Currently, there is only one `checkout_
 
 ```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)
+iex> Poolex.run(:agent_pool, fn pid -> Agent.get(pid, &(&1)) end, checkout_timeout: 5_000)
 {:ok, 5}
 ```
 

docs/guides/getting-started.cheatmd

@@ -43,7 +43,7 @@ def init(_args) do
 -      max_overflow: 50
 -    )
 +    {Poolex,
-+      pool_id: :some_pool,
++      pool_id: {:local, :some_pool},
 +      worker_module: MyApp.SomeWorker,
 +      workers_count: 100,
 +      max_overflow: 50}
@@ -59,12 +59,12 @@ Use `run/3`.
 Be careful, unlike `:poolboy.transaction`, `Poolex.run` returns `{:ok, result}`.
 
 ```diff
--  :poolboy.transaction(
+-  result = :poolboy.transaction(
 -    :some_pool,
 -    fn pid -> some_function(pid) end,
 -    :timer.seconds(10)
 -  )
-+  Poolex.run(
++  {:ok, result} = Poolex.run(
 +    :some_pool,
 +    fn pid -> some_function(pid) end,
 +    checkout_timeout: :timer.seconds(10)

docs/guides/migration-from-poolboy.cheatmd

@@ -13,7 +13,6 @@ To enable pool size metrics, you need to set the pool_size_metrics parameter to
 ```elixir
 children = [
   {Poolex, 
-    pool_id: :worker_pool,
     worker_module: SomeWorker,
     workers_count: 5,
     pool_size_metrics: true}

docs/guides/pool-metrics.cheatmd

@@ -6,7 +6,6 @@ defmodule PoolexExample.Application do
   def start(_type, _args) do
     children = [
       {Poolex,
-       pool_id: :worker_pool,
        worker_module: PoolexExample.Worker,
        workers_count: 5,
        max_overflow: 2,

examples/poolex_example/lib/poolex_example/application.ex

@@ -1,7 +1,7 @@
 %{
-  "dialyxir": {:hex, :dialyxir, "1.4.3", "edd0124f358f0b9e95bfe53a9fcf806d615d8f838e2202a9f430d59566b6b53b", [:mix], [{:erlex, ">= 0.2.6", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "bf2cfb75cd5c5006bec30141b131663299c661a864ec7fbbc72dfa557487a986"},
-  "erlex": {:hex, :erlex, "0.2.6", "c7987d15e899c7a2f34f5420d2a2ea0d659682c06ac607572df55a43753aa12e", [:mix], [], "hexpm", "2ed2e25711feb44d52b17d2780eabf998452f6efda104877a3881c2f8c0c0c75"},
+  "dialyxir": {:hex, :dialyxir, "1.4.5", "ca1571ac18e0f88d4ab245f0b60fa31ff1b12cbae2b11bd25d207f865e8ae78a", [:mix], [{:erlex, ">= 0.2.7", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "b0fb08bb8107c750db5c0b324fa2df5ceaa0f9307690ee3c1f6ba5b9eb5d35c3"},
+  "erlex": {:hex, :erlex, "0.2.7", "810e8725f96ab74d17aac676e748627a07bc87eb950d2b83acd29dc047a30595", [:mix], [], "hexpm", "3ed95f79d1a844c3f6bf0cea61e0d5612a42ce56da9c03f01df538685365efb0"},
   "poolex": {:hex, :poolex, "0.4.0", "cc3c5eb921a2ea5886953a2ea3beb0e36148d7d91dd9b628df74c3abb5ea7981", [:mix], [], "hexpm", "0441bf433f8fca4127b68c5985354cb772bba049057bca842f6e73df4f631c17"},
-  "telemetry": {:hex, :telemetry, "1.2.1", "68fdfe8d8f05a8428483a97d7aab2f268aaff24b49e0f599faa091f1d4e7f61c", [:rebar3], [], "hexpm", "dad9ce9d8effc621708f99eac538ef1cbe05d6a874dd741de2e689c47feafed5"},
-  "telemetry_poller": {:hex, :telemetry_poller, "1.0.0", "db91bb424e07f2bb6e73926fcafbfcbcb295f0193e0a00e825e589a0a47e8453", [:rebar3], [{:telemetry, "~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "b3a24eafd66c3f42da30fc3ca7dda1e9d546c12250a2d60d7b81d264fbec4f6e"},
+  "telemetry": {:hex, :telemetry, "1.3.0", "fedebbae410d715cf8e7062c96a1ef32ec22e764197f70cda73d82778d61e7a2", [:rebar3], [], "hexpm", "7015fc8919dbe63764f4b4b87a95b7c0996bd539e0d499be6ec9d7f3875b79e6"},
+  "telemetry_poller": {:hex, :telemetry_poller, "1.1.0", "58fa7c216257291caaf8d05678c8d01bd45f4bdbc1286838a28c4bb62ef32999", [:rebar3], [{:telemetry, "~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "9eb9d9cbfd81cbd7cdd24682f8711b6e2b691289a0de6826e58452f28c103c8f"},
 }

examples/poolex_example/mix.lock

@@ -39,7 +39,7 @@ defmodule Poolex do
   @poolex_options_table """
   | Option                 | Description                                          | Example               | Default value                     |
   |------------------------|------------------------------------------------------|-----------------------|-----------------------------------|
-  | `pool_id`              | Identifier by which you will access the pool         | `:my_pool`            | **option is required**            |
+  | `pool_id`              | Identifier by which you will access the pool         | `:my_pool`            | `worker_module` value             |
   | `worker_module`        | Name of module that implements our worker            | `MyApp.Worker`        | **option is required**            |
   | `workers_count`        | How many workers should be running in the pool       | `5`                   | **option is required**            |
   | `max_overflow`         | How many workers can be created over the limit       | `2`                   | `0`                               |
@@ -55,7 +55,7 @@ defmodule Poolex do
   Any valid GenServer's name. It may be an atom like `:some_pool` or a tuple {:via, Registry, {MyApp.Registry, "pool"}
   if you want to use Registry.
   """
-  @type pool_id() :: GenServer.name()
+  @type pool_id() :: GenServer.name() | pid()
   @typedoc """
   #{@poolex_options_table}
   """
@@ -101,8 +101,7 @@ defmodule Poolex do
   """
   @spec start(list(poolex_option())) :: GenServer.on_start()
   def start(opts) do
-    pool_id = Keyword.fetch!(opts, :pool_id)
-    GenServer.start(__MODULE__, opts, name: pool_id, spawn_opt: @spawn_opts)
+    GenServer.start(__MODULE__, opts, name: get_pool_id(opts), spawn_opt: @spawn_opts)
   end
 
   @doc """
@@ -125,8 +124,7 @@ defmodule Poolex do
   """
   @spec start_link(list(poolex_option())) :: GenServer.on_start()
   def start_link(opts) do
-    pool_id = Keyword.fetch!(opts, :pool_id)
-    GenServer.start_link(__MODULE__, opts, name: pool_id, spawn_opt: @spawn_opts)
+    GenServer.start_link(__MODULE__, opts, name: get_pool_id(opts), spawn_opt: @spawn_opts)
   end
 
   @doc """
@@ -139,17 +137,16 @@ defmodule Poolex do
   ## Examples
 
       children = [
-        Poolex.child_spec(pool_id: :worker_pool_1, worker_module: SomeWorker, workers_count: 5),
+        Poolex.child_spec(worker_module: SomeWorker, workers_count: 5),
         # or in another way
-        {Poolex, pool_id: :worker_pool_2, worker_module: SomeOtherWorker, workers_count: 5}
+        {Poolex, worker_module: SomeOtherWorker, workers_count: 5}
       ]
 
       Supervisor.start_link(children, strategy: :one_for_one)
   """
   @spec child_spec(list(poolex_option())) :: Supervisor.child_spec()
   def child_spec(opts) do
-    pool_id = Keyword.fetch!(opts, :pool_id)
-    %{id: pool_id, start: {Poolex, :start_link, [opts]}}
+    %{id: get_pool_id(opts), start: {Poolex, :start_link, [opts]}}
   end
 
   @doc """
@@ -252,7 +249,7 @@ defmodule Poolex do
     raise ArgumentError, message
   end
 
-  def add_idle_workers!(pool_id, workers_count) when is_atom(pool_id) and is_integer(workers_count) do
+  def add_idle_workers!(pool_id, workers_count) when is_integer(workers_count) do
     GenServer.call(pool_id, {:add_idle_workers, workers_count})
   end
 
@@ -267,15 +264,15 @@ defmodule Poolex do
     raise ArgumentError, message
   end
 
-  def remove_idle_workers!(pool_id, workers_count) when is_atom(pool_id) and is_integer(workers_count) do
+  def remove_idle_workers!(pool_id, workers_count) when is_integer(workers_count) do
     GenServer.call(pool_id, {:remove_idle_workers, workers_count})
   end
 
   @impl GenServer
   def init(opts) do
     Process.flag(:trap_exit, true)
 
-    pool_id = Keyword.fetch!(opts, :pool_id)
+    pool_id = get_pool_id(opts)
     worker_module = Keyword.fetch!(opts, :worker_module)
     workers_count = Keyword.fetch!(opts, :workers_count)
 
@@ -312,6 +309,17 @@ defmodule Poolex do
     {:ok, state, {:continue, opts}}
   end
 
+  @doc """
+  Returns pool identifier from initialization options.
+  """
+  @spec get_pool_id(list(poolex_option())) :: pool_id()
+  def get_pool_id(options) do
+    case Keyword.get(options, :pool_id) do
+      nil -> Keyword.fetch!(options, :worker_module)
+      pool_id -> pool_id
+    end
+  end
+
   @impl GenServer
   def handle_continue(opts, state) do
     Metrics.start_poller(opts)

lib/poolex.ex

@@ -30,7 +30,7 @@ defmodule Poolex.Private.Metrics do
   """
   @spec start_poller(list(Poolex.poolex_option())) :: GenServer.on_start()
   def start_poller(opts) do
-    pool_id = Keyword.fetch!(opts, :pool_id)
+    pool_id = Poolex.get_pool_id(opts)
     measurements = collect_measurements(opts)
 
     if measurements == [] do
@@ -46,7 +46,7 @@ defmodule Poolex.Private.Metrics do
 
   @spec collect_measurements(list(Poolex.poolex_option())) :: list()
   defp collect_measurements(opts) do
-    pool_id = Keyword.fetch!(opts, :pool_id)
+    pool_id = Poolex.get_pool_id(opts)
 
     if Keyword.get(opts, :pool_size_metrics, false) do
       [

lib/poolex/private/metrics.ex

@@ -15,7 +15,7 @@ defmodule Poolex.MixProject do
       package: package(),
       source_url: "https://github.com/general-CbIC/poolex",
       start_permanent: Mix.env() == :prod,
-      version: "1.1.0"
+      version: "1.2.0"
     ]
   end
 
@@ -33,7 +33,7 @@ defmodule Poolex.MixProject do
       {:telemetry, "~> 1.0"},
       {:telemetry_poller, "~> 1.0"},
       # Development dependencies
-      {:credo, "1.7.10", only: [:dev], runtime: false},
+      {:credo, "1.7.11", only: [:dev], runtime: false},
       {:dialyxir, ">= 0.0.0", only: [:dev], runtime: false},
       {:doctor, ">= 0.0.0", only: [:dev], runtime: false},
       {:ex_check, "~> 0.16.0", only: [:dev], runtime: false},
@@ -45,18 +45,21 @@ defmodule Poolex.MixProject do
 
   defp package do
     [
+      files: ~w(lib mix.exs LICENSE),
       licenses: ["MIT"],
       links: %{
         "Changelog" => "https://github.com/general-CbIC/poolex/blob/develop/CHANGELOG.md",
         "GitHub" => "https://github.com/general-CbIC/poolex",
         "Sponsor" => "https://github.com/sponsors/general-CbIC"
-      }
+      },
+      maintainers: ["Aleksandr Sysoev"]
     ]
   end
 
   defp docs do
     [
       main: "readme",
+      logo: "assets/poolex.png",
       extras: [
         "README.md",
         "docs/guides/getting-started.cheatmd",