Overall updates

Author: cabol

.github/workflows/ci.yml

@@ -22,23 +22,19 @@ jobs:
           - elixir: 1.18.x
             otp: 27.x
             os: 'ubuntu-latest'
-            style: true
+            lint: true
             coverage: true
             sobelow: true
             dialyzer: true
-            doctor: true
           - elixir: 1.17.x
-            otp: 26.x
-            os: 'ubuntu-latest'
-          - elixir: 1.16.x
-            otp: 26.x
+            otp: 27.x
             os: 'ubuntu-latest'
-          - elixir: 1.15.x
+          - elixir: 1.17.x
             otp: 25.x
             os: 'ubuntu-latest'
           - elixir: 1.14.x
-            otp: 23.x
-            os: 'ubuntu-20.04'
+            otp: 24.x
+            os: 'ubuntu-latest'
 
     env:
       GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
@@ -86,14 +82,22 @@ jobs:
           mix deps.get
         if: ${{ steps.mix-cache.outputs.cache-hit != 'true' }}
 
-      - name: Compile code
+      - name: Compile deps
+        run: mix deps.compile
+
+      - name: Check unused dependencies
+        run: mix deps.unlock --check-unused
+        if: ${{ matrix.lint }}
+
+      - name: Compile lint
         run: mix compile --warnings-as-errors
+        if: ${{ matrix.lint }}
 
       - name: Run style and code consistency checks
         run: |
           mix format --check-formatted
           mix credo --strict
-        if: ${{ matrix.style }}
+        if: ${{ matrix.lint }}
 
       - name: Run tests
         run: |
@@ -114,6 +118,10 @@ jobs:
           flags: unittests-elixir-${{ matrix.elixir }}-otp-${{ matrix.otp }}
         if: ${{ matrix.coverage }}
 
+      - name: Run sobelow
+        run: mix sobelow --skip --exit Low
+        if: ${{ matrix.sobelow }}
+
       - name: Restore PLT Cache
         uses: actions/cache@v3
         id: plt-cache

.tool-versions

@@ -1,2 +1,2 @@
-elixir 1.18.2-otp-27
-erlang 27.2.1
+elixir 1.18.3-otp-27
+erlang 27.3.3

LICENSE renamed to LICENSE.md

@@ -1,4 +1,4 @@
-MIT License
+# MIT License
 
 Copyright (c) 2024 Carlos Andres Bolaños R.A.
 

README.md

@@ -1,16 +1,27 @@
-# Nebulex Distributed
+# Nebulex Distributed :spider_web:
 > Distributed cache topologies adapters for [Nebulex][Nebulex].
 
-[Nebulex]: https://github.com/cabol/nebulex
+[Nebulex]: http://github.com/elixir-nebulex/nebulex
 
-![CI](https://github.com/elixir-nebulex/nebulex_distributed/workflows/CI/badge.svg)
-[![Documentation](https://img.shields.io/badge/Documentation-ff69b4)](https://hexdocs.pm/nebulex_distributed)
-[![Hex Version](https://img.shields.io/hexpm/v/nebulex_distributed.svg)](https://hex.pm/packages/nebulex_distributed)
-[![Codecov](https://codecov.io/gh/elixir-nebulex/nebulex_distributed/graph/badge.svg)](https://codecov.io/gh/elixir-nebulex/nebulex_distributed/graph/badge.svg)
+![CI](http://github.com/elixir-nebulex/nebulex_distributed/workflows/CI/badge.svg)
+[![Codecov](http://codecov.io/gh/elixir-nebulex/nebulex_distributed/graph/badge.svg)](http://codecov.io/gh/elixir-nebulex/nebulex_distributed/graph/badge.svg)
+[![Hex.pm](http://img.shields.io/hexpm/v/nebulex_distributed.svg)](http://hex.pm/packages/nebulex_distributed)
+[![Documentation](http://img.shields.io/badge/Documentation-ff69b4)](http://hexdocs.pm/nebulex_distributed)
 
-See the [online documentation][online_docs] for more information.
+## About
+
+One of the goals of Nebulex is also to provide the ability to set up distributed
+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:
 
-[online_docs]: https://hexdocs.pm/nebulex_distributed/
+  * `Nebulex.Adapters.Multilevel` - Multi-level distributed cache topology.
+  * `Nebulex.Adapters.Partitioned` - Partitioned 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`.
 
 ## Installation
 
@@ -19,14 +30,14 @@ Add `:nebulex_distributed` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:nebulex_distributed, "~> 3.0"}
+    {:nebulex_distributed, "~> 3.0.0-rc.1"}
   ]
 end
 ```
 
-## Usage
+## Partitioned cache topology example
 
-You can define a cache as follows:
+You can define a partitioned cache as follows:
 
 ```elixir
 defmodule MyApp.PartitionedCache do
@@ -65,8 +76,69 @@ def start(_type, _args) do
 end
 ```
 
+## Near cache topology example
+
+To set up a near cache, you use the multilevel adapter, like so:
+
+```elixir
+defmodule MyApp.Multilevel do
+  use Nebulex.Cache,
+    otp_app: :nebulex,
+    adapter: Nebulex.Adapters.Multilevel
+
+  defmodule L1 do
+    use Nebulex.Cache,
+      otp_app: :nebulex,
+      adapter: Nebulex.Adapters.Local
+  end
+
+  defmodule L2 do
+    use Nebulex.Cache,
+      otp_app: :nebulex,
+      adapter: Nebulex.Adapters.Partitioned
+  end
+end
+```
+
+Where the configuration for the cache and its levels must be in your
+application environment, usually defined in your `config/config.exs`:
+
+```elixir
+config :my_app, MyApp.Multilevel,
+  levels: [
+    {
+      MyApp.Multilevel.L1,
+      gc_interval: :timer.hours(12),
+      backend: :shards
+    },
+    {
+      MyApp.Multilevel.L2,
+      primary: [
+        gc_interval: :timer.hours(12),
+        backend: :shards
+      ]
+    }
+  ]
+```
+
+If your application was generated with a supervisor (by passing `--sup`
+to `mix new`) you will have a `lib/my_app/application.ex` file containing
+the application start callback that defines and starts your supervisor.
+You just need to edit the `start/2` function to start the cache as a
+supervisor on your application's supervisor:
+
+```elixir
+def start(_type, _args) do
+  children = [
+    {MyApp.Multilevel, []},
+    ...
+  ]
+```
+
 See the [online documentation][online_docs] for more information.
 
+[online_docs]: http://hexdocs.pm/nebulex_distributed
+
 ## Testing
 
 Since this adapter uses support modules and shared tests from `Nebulex`,
@@ -110,38 +182,39 @@ You will find the coverage report within `cover/excoveralls.html`.
 ## Benchmarks
 
 The adapter provides a set of basic benchmark tests using the library
-[benchee](https://github.com/PragTob/benchee), and they are located within
+[benchee](http://github.com/PragTob/benchee), and they are located within
 the directory [benchmarks](./benchmarks).
 
 To run a benchmark test you have to run:
 
 ```
-$ MIX_ENV=test mix run benchmarks/{BENCH_TEST_FILE}
+mix run benchmarks/BENCH_TEST_FILE
 ```
 
 Where `BENCH_TEST_FILE` can be any of:
 
   * `partitioned_bench.exs`: benchmark for the partitioned adapter using
     the `Nebulex.Adapters.Local` as primary storage.
+  * `multilevel_bench.exs`: benchmark for the multilevel adapter.
 
 ## Contributing
 
 Contributions to Nebulex are very welcome and appreciated!
 
-Use the [issue tracker](https://github.com/elixir-nebulex/nebulex_distributed/issues)
+Use the [issue tracker](http://github.com/elixir-nebulex/nebulex_distributed/issues)
 for bug reports or feature requests. Open a
-[pull request](https://github.com/elixir-nebulex/nebulex_distributed/pulls)
+[pull request](http://github.com/elixir-nebulex/nebulex_distributed/pulls)
 when you are ready to contribute.
 
 When submitting a pull request you should not update the
 [CHANGELOG.md](CHANGELOG.md), and also make sure you test your changes
 thoroughly, include unit tests alongside new or changed code.
 
-Before to submit a PR it is highly recommended to run `mix check` and ensure
+Before to submit a PR it is highly recommended to run `mix test.ci` and ensure
 all checks run successfully.
 
 ## Copyright and License
 
 Copyright (c) 2024 Carlos Andres Bolaños R.A.
 
-`Nebulex.Adapters.Local` source code is licensed under the [MIT License](LICENSE).
+`nebulex_distributed` source code is licensed under the [MIT License](LICENSE).

benchmarks/multilevel_bench.exs

@@ -0,0 +1,116 @@
+## Benchmarks
+
+_ = Application.start(:telemetry)
+
+defmodule BenchCache do
+  use Nebulex.Cache,
+    otp_app: :nebulex,
+    adapter: Nebulex.Adapters.Multilevel
+
+  defmodule L1 do
+    use Nebulex.Cache,
+      otp_app: :nebulex,
+      adapter: Nebulex.Adapters.Local
+  end
+
+  defmodule L2 do
+    use Nebulex.Cache,
+      otp_app: :nebulex,
+      adapter: Nebulex.Adapters.Partitioned
+  end
+end
+
+# gc interval
+gc_interval = :timer.hours(1)
+
+# start caches
+{:ok, local} =
+  BenchCache.start_link(
+    levels: [
+      {BenchCache.L1, gc_interval: gc_interval},
+      {BenchCache.L2, primary: [gc_interval: gc_interval]}
+    ]
+  )
+
+# samples
+keys = Enum.to_list(1..10_000)
+bulk = for x <- 1..100, do: {x, x}
+
+# init caches
+Enum.each(1..5000, &BenchCache.put(&1, &1))
+
+inputs = %{
+  "Redis Cache" => BenchCache
+}
+
+benchmarks = %{
+  "fetch" => fn {cache, random} ->
+    cache.fetch(random)
+  end,
+  "put!" => fn {cache, random} ->
+    cache.put!(random, random)
+  end,
+  "put_new!" => fn {cache, random} ->
+    cache.put_new!(random, random)
+  end,
+  "replace!" => fn {cache, random} ->
+    cache.replace!(random, random)
+  end,
+  "put_all!" => fn {cache, _random} ->
+    cache.put_all!(bulk)
+  end,
+  "delete!" => fn {cache, random} ->
+    cache.delete!(random)
+  end,
+  "take" => fn {cache, random} ->
+    cache.take(random)
+  end,
+  "has_key?" => fn {cache, random} ->
+    cache.has_key?(random)
+  end,
+  "ttl" => fn {cache, random} ->
+    cache.ttl(random)
+  end,
+  "expire!" => fn {cache, random} ->
+    cache.expire!(random, 1000)
+  end,
+  "incr!" => fn {cache, _random} ->
+    cache.incr!(:counter, 1)
+  end,
+  "update!" => fn {cache, random} ->
+    cache.update!(random, 1, &Kernel.+(&1, 1))
+  end,
+  "get_and_update!" => fn {cache, random} ->
+    cache.get_and_update!(random, fn
+      nil -> {nil, 1}
+      val -> {val, val * 2}
+    end)
+  end,
+  "get_all!" => fn {cache, _random} ->
+    cache.get_all!(in: [1, 2, 3, 4, 5, 6, 7, 8, 9])
+  end,
+  "count_all!" => fn {cache, _random} ->
+    cache.count_all!()
+  end,
+  "delete_all!" => fn {cache, _random} ->
+    cache.delete_all!(in: [1, 2, 3])
+  end
+}
+
+Benchee.run(
+  benchmarks,
+  inputs: inputs,
+  before_scenario: fn cache ->
+    {cache, Enum.random(keys)}
+  end,
+  formatters: [
+    {Benchee.Formatters.Console, comparison: false, extended_statistics: true},
+    {Benchee.Formatters.HTML, extended_statistics: true, auto_open: false}
+  ],
+  print: [
+    fast_warning: false
+  ]
+)
+
+# stop caches s
+if Process.alive?(local), do: Supervisor.stop(local)