Merge branch 'release/v0.10.0' into main

.check.exs

@@ -15,7 +15,8 @@
   tools: [
     ## curated tools may be disabled (e.g. the check for compilation warnings)
     {:sobelow, false},
-    {:mix_audit, false}
+    {:mix_audit, false},
+    {:gettext, false}
 
     ## ...or have command & args adjusted (e.g. enable skip comments for sobelow)
     # {:sobelow, "mix sobelow --exit --skip"},

.github/workflows/ci-tests.yml

@@ -36,6 +36,8 @@ jobs:
             otp: '26'
           - elixir: '1.16'
             otp: '26'
+          - elixir: '1.17'
+            otp: '27'
     steps:
       - uses: actions/checkout@v4
       - uses: erlef/setup-beam@v1
@@ -67,7 +69,7 @@ jobs:
       - name: Run dialyzer
         uses: erlef/setup-beam@v1
         with:
-          otp-version: '26'
-          elixir-version: '1.16'
+          otp-version: '27'
+          elixir-version: '1.17'
       - run: mix do deps.get, compile
       - run: mix check

.tool-versions

@@ -1,2 +1,2 @@
-erlang 26.2.1
-elixir 1.16.0-otp-26
+erlang 27.0.1
+elixir 1.17.2-otp-27

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2024-08-26
+
+### Added
+
+- Added functions `add_idle_workers!/2` and `remove_idle_workers!/2` for changing count of idle workers in runtime.
+
+### Changed
+
+- Refactored private `start_workers` function. It no longer accepts monitor_id as it already is in the state.
+- Updated `telemetry` dependency.
+
 ## [0.9.0] - 2024-04-24
 
 ### Added
@@ -239,7 +250,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/v0.9.0...HEAD
+[unreleased]: https://github.com/general-CbIC/poolex/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/general-CbIC/poolex/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/general-CbIC/poolex/compare/v0.8.0...v0.9.0
 [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

README.md

@@ -25,15 +25,13 @@ With `poolex` you can:
 
 - Launch multiple pools of workers and then access the free ones from anywhere in the application.
 - Configure the pool to run additional temporary workers if the load increases.
+- Analyze and optimize your pool's production settings using metrics.
 - Use your implementations to define worker and caller processes access logic.
 
-<details>
-  <summary>Why `poolex` instead of `poolboy`?</summary>
+**Why `poolex` instead of `poolboy`?**
 
 - `poolex` is written in Elixir. This library is much more convenient to use in Elixir projects.
 - `poolboy` is a great library, but not actively maintained :crying_cat_face:![Last poolboy commit](https://img.shields.io/github/last-commit/devinus/poolboy?style=flat)
-
-</details>
 
 ## Requirements
 
@@ -49,7 +47,7 @@ Add `:poolex` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:poolex, "~> 0.9.0"}
+    {:poolex, "~> 0.10.0"}
   ]
 end
 ```

docs/guides/migration-from-poolboy.cheatmd

@@ -12,7 +12,7 @@ If you are using `:poolboy` and want to use `Poolex` instead, then you need to f
 defp deps do
   [
 -    {:poolboy, "~> 1.5.0"}
-+    {:poolex, "~> 0.9.0"}
++    {:poolex, "~> 0.10.0"}
   ]
 end
 ```

docs/guides/pool-metrics.cheatmd

@@ -8,6 +8,18 @@ The Poolex library presents **an idle/busy worker count metric**. These metrics
 
 Also, there is **an overflow metric**. It shows how long pools are forced to use additional workers.
 
+To enable pool size metrics, you need to set the pool_size_metrics parameter to true on the pool initialization:
+
+```elixir
+children = [
+  {Poolex, 
+    pool_id: :worker_pool,
+    worker_module: SomeWorker,
+    workers_count: 5,
+    pool_size_metrics: true}
+]
+```
+
 You can handle them by using `:telemetry.attach/4`:
 
 ```elixir

lib/poolex.ex

@@ -253,6 +253,37 @@ defmodule Poolex do
     GenServer.call(pool_id, :get_debug_info)
   end
 
+  @doc """
+  Adds some idle workers to existing pool.
+  """
+  @spec add_idle_workers!(pool_id(), pos_integer()) :: :ok | no_return()
+  def add_idle_workers!(_pool_id, workers_count) when workers_count < 1 do
+    message = "workers_count must be positive number, received: #{inspect(workers_count)}"
+
+    raise ArgumentError, message
+  end
+
+  def add_idle_workers!(pool_id, workers_count)
+      when is_atom(pool_id) and is_integer(workers_count) do
+    GenServer.call(pool_id, {:add_idle_workers, workers_count})
+  end
+
+  @doc """
+  Removes some idle workers from existing pool.
+  If the number of workers to remove is greater than the number of idle workers, all idle workers will be removed.
+  """
+  @spec remove_idle_workers!(pool_id(), pos_integer()) :: :ok | no_return()
+  def remove_idle_workers!(_pool_id, workers_count) when workers_count < 1 do
+    message = "workers_count must be positive number, received: #{inspect(workers_count)}"
+
+    raise ArgumentError, message
+  end
+
+  def remove_idle_workers!(pool_id, workers_count)
+      when is_atom(pool_id) and 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)
@@ -285,7 +316,7 @@ defmodule Poolex do
         worker_start_fun: worker_start_fun
       }
 
-    initial_workers_pids = start_workers(workers_count, state, monitor_id)
+    initial_workers_pids = start_workers(workers_count, state)
 
     state =
       state
@@ -303,20 +334,20 @@ defmodule Poolex do
     {:noreply, state}
   end
 
-  @spec start_workers(non_neg_integer(), State.t(), Monitoring.monitor_id()) :: [pid]
-  defp start_workers(0, _state, _monitor_id) do
+  @spec start_workers(non_neg_integer(), State.t()) :: [pid]
+  defp start_workers(0, _state) do
     []
   end
 
-  defp start_workers(workers_count, _state, _monitor_id) when workers_count < 0 do
+  defp start_workers(workers_count, _state) when workers_count < 0 do
     msg = "workers_count must be non negative number, received: #{inspect(workers_count)}"
     raise ArgumentError, msg
   end
 
-  defp start_workers(workers_count, state, monitor_id) do
+  defp start_workers(workers_count, state) do
     Enum.map(1..workers_count, fn _ ->
       {:ok, worker_pid} = start_worker(state)
-      Monitoring.add(monitor_id, worker_pid, :worker)
+      Monitoring.add(state.monitor_id, worker_pid, :worker)
 
       worker_pid
     end)
@@ -367,7 +398,7 @@ defmodule Poolex do
     {:reply, state, state}
   end
 
-  def handle_call(:get_debug_info, _form, %State{} = state) do
+  def handle_call(:get_debug_info, _from, %State{} = state) do
     debug_info = %DebugInfo{
       busy_workers_count: BusyWorkers.count(state),
       busy_workers_impl: state.busy_workers_impl,
@@ -387,6 +418,31 @@ defmodule Poolex do
     {:reply, debug_info, state}
   end
 
+  @impl GenServer
+  def handle_call({:add_idle_workers, workers_count}, _from, %State{} = state) do
+    new_state =
+      workers_count
+      |> start_workers(state)
+      |> Enum.reduce(state, fn worker, acc_state ->
+        IdleWorkers.add(acc_state, worker)
+      end)
+
+    {:reply, :ok, new_state}
+  end
+
+  @impl GenServer
+  def handle_call({:remove_idle_workers, workers_count}, _from, %State{} = state) do
+    new_state =
+      state
+      |> IdleWorkers.to_list()
+      |> Enum.take(workers_count)
+      |> Enum.reduce(state, fn worker, acc_state ->
+        IdleWorkers.remove(acc_state, worker)
+      end)
+
+    {:reply, :ok, new_state}
+  end
+
   @impl GenServer
   def handle_cast({:release_busy_worker, worker}, %State{} = state) do
     if WaitingCallers.empty?(state) do

mix.exs

@@ -15,7 +15,7 @@ defmodule Poolex.MixProject do
       package: package(),
       source_url: "https://github.com/general-CbIC/poolex",
       start_permanent: Mix.env() == :prod,
-      version: "0.9.0"
+      version: "0.10.0"
     ]
   end
 
@@ -33,7 +33,7 @@ defmodule Poolex.MixProject do
       {:telemetry, "~> 1.0"},
       {:telemetry_poller, "~> 1.0"},
       # Development dependencies
-      {:credo, ">= 0.0.0", only: [:dev], runtime: false},
+      {:credo, "1.7.7", 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},

mix.lock

@@ -1,20 +1,20 @@
 %{
   "bunt": {:hex, :bunt, "1.0.0", "081c2c665f086849e6d57900292b3a161727ab40431219529f13c4ddcf3e7a44", [:mix], [], "hexpm", "dc5f86aa08a5f6fa6b8096f0735c4e76d54ae5c9fa2c143e5a1fc7c1cd9bb6b5"},
-  "credo": {:hex, :credo, "1.7.5", "643213503b1c766ec0496d828c90c424471ea54da77c8a168c725686377b9545", [:mix], [{:bunt, "~> 0.2.1 or ~> 1.0", [hex: :bunt, repo: "hexpm", optional: false]}, {:file_system, "~> 0.2 or ~> 1.0", [hex: :file_system, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "f799e9b5cd1891577d8c773d245668aa74a2fcd15eb277f51a0131690ebfb3fd"},
+  "credo": {:hex, :credo, "1.7.7", "771445037228f763f9b2afd612b6aa2fd8e28432a95dbbc60d8e03ce71ba4446", [:mix], [{:bunt, "~> 0.2.1 or ~> 1.0", [hex: :bunt, repo: "hexpm", optional: false]}, {:file_system, "~> 0.2 or ~> 1.0", [hex: :file_system, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "8bc87496c9aaacdc3f90f01b7b0582467b69b4bd2441fe8aae3109d843cc2f2e"},
   "decimal": {:hex, :decimal, "2.1.1", "5611dca5d4b2c3dd497dec8f68751f1f1a54755e8ed2a966c2633cf885973ad6", [:mix], [], "hexpm", "53cfe5f497ed0e7771ae1a475575603d77425099ba5faef9394932b35020ffcc"},
   "dialyxir": {:hex, :dialyxir, "1.4.3", "edd0124f358f0b9e95bfe53a9fcf806d615d8f838e2202a9f430d59566b6b53b", [:mix], [{:erlex, ">= 0.2.6", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "bf2cfb75cd5c5006bec30141b131663299c661a864ec7fbbc72dfa557487a986"},
   "doctor": {:hex, :doctor, "0.21.0", "20ef89355c67778e206225fe74913e96141c4d001cb04efdeba1a2a9704f1ab5", [:mix], [{:decimal, "~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}], "hexpm", "a227831daa79784eb24cdeedfa403c46a4cb7d0eab0e31232ec654314447e4e0"},
-  "earmark_parser": {:hex, :earmark_parser, "1.4.39", "424642f8335b05bb9eb611aa1564c148a8ee35c9c8a8bba6e129d51a3e3c6769", [:mix], [], "hexpm", "06553a88d1f1846da9ef066b87b57c6f605552cfbe40d20bd8d59cc6bde41944"},
-  "erlex": {:hex, :erlex, "0.2.6", "c7987d15e899c7a2f34f5420d2a2ea0d659682c06ac607572df55a43753aa12e", [:mix], [], "hexpm", "2ed2e25711feb44d52b17d2780eabf998452f6efda104877a3881c2f8c0c0c75"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.41", "ab34711c9dc6212dda44fcd20ecb87ac3f3fce6f0ca2f28d4a00e4154f8cd599", [:mix], [], "hexpm", "a81a04c7e34b6617c2792e291b5a2e57ab316365c2644ddc553bb9ed863ebefa"},
+  "erlex": {:hex, :erlex, "0.2.7", "810e8725f96ab74d17aac676e748627a07bc87eb950d2b83acd29dc047a30595", [:mix], [], "hexpm", "3ed95f79d1a844c3f6bf0cea61e0d5612a42ce56da9c03f01df538685365efb0"},
   "ex_check": {:hex, :ex_check, "0.16.0", "07615bef493c5b8d12d5119de3914274277299c6483989e52b0f6b8358a26b5f", [:mix], [], "hexpm", "4d809b72a18d405514dda4809257d8e665ae7cf37a7aee3be6b74a34dec310f5"},
-  "ex_doc": {:hex, :ex_doc, "0.32.1", "21e40f939515373bcdc9cffe65f3b3543f05015ac6c3d01d991874129d173420", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.1", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "5142c9db521f106d61ff33250f779807ed2a88620e472ac95dc7d59c380113da"},
+  "ex_doc": {:hex, :ex_doc, "0.34.2", "13eedf3844ccdce25cfd837b99bea9ad92c4e511233199440488d217c92571e8", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "5ce5f16b41208a50106afed3de6a2ed34f4acfd65715b82a0b84b49d995f95c1"},
   "file_system": {:hex, :file_system, "1.0.0", "b689cc7dcee665f774de94b5a832e578bd7963c8e637ef940cd44327db7de2cd", [:mix], [], "hexpm", "6752092d66aec5a10e662aefeed8ddb9531d79db0bc145bb8c40325ca1d8536d"},
   "jason": {:hex, :jason, "1.4.1", "af1504e35f629ddcdd6addb3513c3853991f694921b1b9368b0bd32beb9f1b63", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "fbb01ecdfd565b56261302f7e1fcc27c4fb8f32d56eab74db621fc154604a7a1"},
-  "makeup": {:hex, :makeup, "1.1.1", "fa0bc768698053b2b3869fa8a62616501ff9d11a562f3ce39580d60860c3a55e", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "5dc62fbdd0de44de194898b6710692490be74baa02d9d108bc29f007783b0b48"},
+  "makeup": {:hex, :makeup, "1.1.2", "9ba8837913bdf757787e71c1581c21f9d2455f4dd04cfca785c70bbfff1a76a3", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cce1566b81fbcbd21eca8ffe808f33b221f9eee2cbc7a1706fc3da9ff18e6cac"},
   "makeup_diff": {:hex, :makeup_diff, "0.1.0", "5be352b6aa6f07fa6a236e3efd7ba689a03f28fb5d35b7a0fa0a1e4a64f6d8bb", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "186bad5bb433a8afeb16b01423950e440072284a4103034ca899180343b9b4ac"},
   "makeup_elixir": {:hex, :makeup_elixir, "0.16.2", "627e84b8e8bf22e60a2579dad15067c755531fea049ae26ef1020cad58fe9578", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "41193978704763f6bbe6cc2758b84909e62984c7752b3784bd3c218bb341706b"},
-  "makeup_erlang": {:hex, :makeup_erlang, "0.1.5", "e0ff5a7c708dda34311f7522a8758e23bfcd7d8d8068dc312b5eb41c6fd76eba", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "94d2e986428585a21516d7d7149781480013c56e30c6a233534bedf38867a59a"},
+  "makeup_erlang": {:hex, :makeup_erlang, "1.0.0", "6f0eff9c9c489f26b69b61440bf1b238d95badae49adac77973cbacae87e3c2e", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "ea7a9307de9d1548d2a72d299058d1fd2339e3d398560a0e46c27dab4891e4d2"},
   "nimble_parsec": {:hex, :nimble_parsec, "1.4.0", "51f9b613ea62cfa97b25ccc2c1b4216e81df970acd8e16e8d1bdc58fef21370d", [:mix], [], "hexpm", "9c565862810fb383e9838c1dd2d7d2c437b3d13b267414ba6af33e50d2d1cf28"},
-  "telemetry": {:hex, :telemetry, "1.2.1", "68fdfe8d8f05a8428483a97d7aab2f268aaff24b49e0f599faa091f1d4e7f61c", [:rebar3], [], "hexpm", "dad9ce9d8effc621708f99eac538ef1cbe05d6a874dd741de2e689c47feafed5"},
+  "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"},
 }

test/poolex_test.exs

@@ -4,6 +4,8 @@ defmodule PoolexTest do
 
   doctest Poolex
 
+  alias Poolex.Private.DebugInfo
+
   describe "debug info" do
     test "valid after initialization" do
       initial_fun = fn -> 0 end
@@ -12,7 +14,7 @@ defmodule PoolexTest do
 
       debug_info = Poolex.get_debug_info(pool_name)
 
-      assert debug_info.__struct__ == Poolex.Private.DebugInfo
+      assert debug_info.__struct__ == DebugInfo
       assert debug_info.busy_workers_count == 0
       assert debug_info.busy_workers_impl == Poolex.Workers.Impl.List
       assert debug_info.busy_workers_pids == []
@@ -51,7 +53,7 @@ defmodule PoolexTest do
 
       debug_info = Poolex.get_debug_info(pool_name)
 
-      assert debug_info.__struct__ == Poolex.Private.DebugInfo
+      assert debug_info.__struct__ == DebugInfo
       assert debug_info.busy_workers_count == 0
       assert Enum.empty?(debug_info.busy_workers_pids)
       assert debug_info.idle_workers_count == 5
@@ -80,7 +82,7 @@ defmodule PoolexTest do
 
       debug_info = Poolex.get_debug_info(pool_name)
 
-      assert debug_info.__struct__ == Poolex.Private.DebugInfo
+      assert debug_info.__struct__ == DebugInfo
       assert debug_info.busy_workers_count == 1
       assert Enum.count(debug_info.busy_workers_pids) == 1
       assert debug_info.idle_workers_count == 4
@@ -582,4 +584,66 @@ defmodule PoolexTest do
       assert elem(message_3, 3) == pool_pid
     end
   end
+
+  describe "add_idle_workers!/2" do
+    test "adds idle workers to pool" do
+      initial_fun = fn -> 0 end
+
+      pool_name = start_pool(worker_module: Agent, worker_args: [initial_fun], workers_count: 5)
+
+      assert %DebugInfo{idle_workers_count: 5} = Poolex.get_debug_info(pool_name)
+      assert :ok = Poolex.add_idle_workers!(pool_name, 5)
+      assert %DebugInfo{idle_workers_count: 10} = Poolex.get_debug_info(pool_name)
+    end
+
+    test "raises error on non positive workers_count" do
+      initial_fun = fn -> 0 end
+
+      pool_name = start_pool(worker_module: Agent, worker_args: [initial_fun], workers_count: 5)
+
+      assert_raise(ArgumentError, fn ->
+        Poolex.add_idle_workers!(pool_name, -1)
+      end)
+
+      assert_raise(ArgumentError, fn ->
+        Poolex.add_idle_workers!(pool_name, 0)
+      end)
+    end
+  end
+
+  describe "remove_idle_workers!/2" do
+    test "removes idle workers from pool" do
+      initial_fun = fn -> 0 end
+
+      pool_name = start_pool(worker_module: Agent, worker_args: [initial_fun], workers_count: 5)
+
+      assert %DebugInfo{idle_workers_count: 5} = Poolex.get_debug_info(pool_name)
+      assert :ok = Poolex.remove_idle_workers!(pool_name, 2)
+      assert %DebugInfo{idle_workers_count: 3} = Poolex.get_debug_info(pool_name)
+    end
+
+    test "removes all idle workers when argument is bigger than idle_workers count" do
+      initial_fun = fn -> 0 end
+
+      pool_name = start_pool(worker_module: Agent, worker_args: [initial_fun], workers_count: 3)
+
+      assert %DebugInfo{idle_workers_count: 3} = Poolex.get_debug_info(pool_name)
+      assert :ok = Poolex.remove_idle_workers!(pool_name, 5)
+      assert %DebugInfo{idle_workers_count: 0} = Poolex.get_debug_info(pool_name)
+    end
+
+    test "raises error on non positive workers_count" do
+      initial_fun = fn -> 0 end
+
+      pool_name = start_pool(worker_module: Agent, worker_args: [initial_fun], workers_count: 5)
+
+      assert_raise(ArgumentError, fn ->
+        Poolex.remove_idle_workers!(pool_name, -1)
+      end)
+
+      assert_raise(ArgumentError, fn ->
+        Poolex.remove_idle_workers!(pool_name, 0)
+      end)
+    end
+  end
 end