Release v3.0.0-rc.1 🔖

Author: cabol

README.md

@@ -15,14 +15,18 @@ cache topologies, but this feature will depend on the adapters. Here is where
 **"Nebulex Distributed"** comes in. It provides the following adapters to set up
 distributed topologies:
 
-  * `Nebulex.Adapters.Partitioned` - Partitioned cache topology.
-  * `Nebulex.Adapters.Multilevel` - Multi-level distributed cache topology.
+  * [`Nebulex.Adapters.Partitioned`][partitioned] - Partitioned cache topology.
+  * [`Nebulex.Adapters.Multilevel`][multilevel] - Multi-level or near cache
+    topology.
   * `Nebulex.Adapters.Replicated` - Replicated cache topology (**WIP!**).
 
 These adapters work more as wrappers for an existing local adapter and provide
 the distributed topology on top of it. You can optionally set the adapter for
 the primary cache storage with the option `:primary_storage_adapter`.
 
+[partitioned]: http://hexdocs.pm/nebulex_distributed/Nebulex.Adapters.Partitioned.html
+[multilevel]: http://hexdocs.pm/nebulex_distributed/Nebulex.Adapters.Multilevel.html
+
 ## Installation
 
 `:nebulex_distributed` requires Erlang/OTP 25 or later. Then add

lib/nebulex/adapters/partitioned.ex

@@ -5,9 +5,9 @@ defmodule Nebulex.Adapters.Partitioned do
   ## Features
 
     * Partitioned cache topology (Sharding Distribution Model).
-    * Configurable primary storage adapter.
     * `ExHashRing` for distributing the keys across the cluster members.
     * Support for transactions via Erlang global name registration facility.
+    * Configurable primary storage adapter.
 
   ## Partitioned Cache Topology
 
@@ -59,15 +59,34 @@ defmodule Nebulex.Adapters.Partitioned do
   `:pg` is used under-the-hood by the adapter to manage the cluster nodes.
   When the partitioned cache is started in a node, it creates a group and joins
   it (the cache supervisor PID is joined to the group). Then, when a function
-  is invoked, the adapter picks a node from the group members, and then the
-  function is executed on that specific node. In the same way, when a
-  partitioned cache supervisor dies (the cache is stopped or killed for some
-  reason), the PID of that process is automatically removed from the PG group;
-  this is why it's recommended to use consistent hashing for distributing the
-  keys across the cluster nodes.
+  is invoked, the adapter uses `ExHashRing` to determine which node should
+  handle the request based on the key's hash value. This ensures consistent
+  key distribution across the cluster nodes, even when nodes join or leave
+  the cluster.
+
+  The key distribution process works as follows:
+
+    1. Each node in the cluster is assigned a set of virtual nodes (vnodes) in
+      the hash ring.
+    2. When a key is accessed, `ExHashRing.Ring` is used to find the node
+      responsible for that key (the hash value is used to find the corresponding
+      vnode in the hash ring).
+    3. The request is routed to the physical node that owns that vnode.
+
+  This consistent hashing approach provides several benefits:
+
+    * Minimal key redistribution when nodes join or leave the cluster.
+    * Even distribution of keys across the cluster.
+    * Predictable key-to-node mapping.
+    * Efficient node lookup for key operations.
+
+  When a partitioned cache supervisor dies (the cache is stopped or killed for some
+  reason), the PID of that process is automatically removed from the PG group.
+  The hash ring is then automatically rebalanced to ensure keys are properly
+  distributed among the remaining nodes.
 
   This adapter depends on a local cache adapter (primary storage), it adds
-  a thin layer on top of it in order to distribute requests across a group
+  an extra layer on top of it in order to distribute requests across a group
   of nodes, where is supposed the local cache is running already. However,
   you don't need to define any additional cache module for the primary
   storage, instead, the adapter initializes it automatically (it adds the
@@ -502,7 +521,7 @@ defmodule Nebulex.Adapters.Partitioned do
     end
   end
 
-  def do_put_all(action, adapter_meta, entries, ttl, opts) do
+  defp do_put_all(action, adapter_meta, entries, ttl, opts) do
     timeout = Keyword.fetch!(opts, :timeout)
     opts = [ttl: ttl] ++ opts
 

mix.exs

@@ -31,33 +31,14 @@ defmodule NebulexDistributed.MixProject do
 
       # Hex
       package: package(),
-      description: "A generational local cache adapter for Nebulex",
+      description: "Distributed cache topologies adapters for Nebulex",
 
       # Docs
       name: "Nebulex.Distributed",
       docs: docs()
     ]
   end
 
-  defp docs do
-    [
-      main: "Nebulex.Distributed",
-      source_ref: "v#{@version}",
-      source_url: @source_url,
-      canonical: "http://hexdocs.pm/nebulex_distributed",
-      groups_for_modules: [
-        Adapters: [
-          Nebulex.Adapters.Multilevel,
-          Nebulex.Adapters.Partitioned
-        ],
-        Utilities: [
-          Nebulex.Distributed.Cluster,
-          Nebulex.Distributed.RPC
-        ]
-      ]
-    ]
-  end
-
   defp elixirc_paths(:test), do: ["lib", "test/support"]
   defp elixirc_paths(_), do: ["lib"]
 
@@ -72,7 +53,7 @@ defmodule NebulexDistributed.MixProject do
     [
       nebulex_dep(),
       {:nebulex_local, "~> 3.0.0-rc.1"},
-      {:ex_hash_ring, "~> 7.0", override: true},
+      {:ex_hash_ring, "~> 6.0 or ~> 7.0"},
       {:telemetry, "~> 0.4 or ~> 1.0", optional: true},
 
       # Test & Code Analysis
@@ -98,7 +79,7 @@ defmodule NebulexDistributed.MixProject do
     if path = System.get_env("NEBULEX_PATH") do
       {:nebulex, path: path, override: true}
     else
-      {:nebulex, "~> #{@nbx_vsn}", override: true}
+      {:nebulex, "~> #{@nbx_vsn}"}
     end
   end
 
@@ -122,17 +103,35 @@ defmodule NebulexDistributed.MixProject do
 
   defp package do
     [
-      name: :nebulex_local,
+      name: :nebulex_distributed,
       maintainers: [
-        "Carlos Bolanos",
-        "Felipe Ripoll"
+        "Carlos Bolanos"
       ],
       licenses: ["MIT"],
       links: %{"GitHub" => @source_url},
       files: ~w(lib .formatter.exs mix.exs README* CHANGELOG* LICENSE*)
     ]
   end
 
+  defp docs do
+    [
+      main: "Nebulex.Distributed",
+      source_ref: "v#{@version}",
+      source_url: @source_url,
+      canonical: "http://hexdocs.pm/nebulex_distributed",
+      groups_for_modules: [
+        Adapters: [
+          Nebulex.Adapters.Multilevel,
+          Nebulex.Adapters.Partitioned
+        ],
+        Utilities: [
+          Nebulex.Distributed.Cluster,
+          Nebulex.Distributed.RPC
+        ]
+      ]
+    ]
+  end
+
   defp dialyzer do
     [
       plt_add_apps: [:nebulex, :mix],

mix.lock

@@ -12,7 +12,7 @@
   "eternal": {:hex, :eternal, "1.2.2", "d1641c86368de99375b98d183042dd6c2b234262b8d08dfd72b9eeaafc2a1abd", [:mix], [], "hexpm", "2c9fe32b9c3726703ba5e1d43a1d255a4f3f2d8f8f9bc19f094c7cb1a7a9e782"},
   "ex2ms": {:hex, :ex2ms, "1.7.0", "45b9f523d0b777667ded60070d82d871a37e294f0b6c5b8eca86771f00f82ee1", [:mix], [], "hexpm", "2589eee51f81f1b1caa6d08c990b1ad409215fe6f64c73f73c67d36ed10be827"},
   "ex_doc": {:hex, :ex_doc, "0.38.2", "504d25eef296b4dec3b8e33e810bc8b5344d565998cd83914ffe1b8503737c02", [:mix], [{:earmark_parser, "~> 1.4.44", [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", "732f2d972e42c116a70802f9898c51b54916e542cc50968ac6980512ec90f42b"},
-  "ex_hash_ring": {:hex, :ex_hash_ring, "7.0.0", "2d92d90669019536abaab7db6ccf00cb33c323e43a1fb44f1f16177a3d777a99", [:mix], [], "hexpm", "9f61f33f043a69e9df9febe6df05ddb0ec78227a43aad8407503e2cd81715c5b"},
+  "ex_hash_ring": {:hex, :ex_hash_ring, "6.0.4", "bef9d2d796afbbe25ab5b5a7ed746e06b99c76604f558113c273466d52fa6d6b", [:mix], [], "hexpm", "89adabf31f7d3dfaa36802ce598ce918e9b5b33bae8909ac1a4d052e1e567d18"},
   "excoveralls": {:hex, :excoveralls, "0.18.5", "e229d0a65982613332ec30f07940038fe451a2e5b29bce2a5022165f0c9b157e", [:mix], [{:castore, "~> 1.0", [hex: :castore, repo: "hexpm", optional: true]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "523fe8a15603f86d64852aab2abe8ddbd78e68579c8525ae765facc5eae01562"},
   "file_system": {:hex, :file_system, "1.1.0", "08d232062284546c6c34426997dd7ef6ec9f8bbd090eb91780283c9016840e8f", [:mix], [], "hexpm", "bfcf81244f416871f2a2e15c1b515287faa5db9c6bcf290222206d120b3d43f6"},
   "ham": {:hex, :ham, "0.3.0", "7cd031b4a55fba219c11553e7b13ba73bd86eab4034518445eff1e038cb9a44d", [:mix], [], "hexpm", "7d6c6b73d7a6a83233876cc1b06a4d9b5de05562b228effda4532f9a49852bf6"},