Nebulex Distributed

Distributed cache topologies adapters for Nebulex.

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:

• Nebulex.Adapters.Partitioned - Partitioned cache topology.
• Nebulex.Adapters.Multilevel - Multi-level distributed cache topology.

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

Add :nebulex_distributed to your list of dependencies in mix.exs:

def deps do
  [
    {:nebulex_distributed, "~> 3.0.0-rc.1"}
  ]
end

Usage

You can define a cache as follows:

defmodule MyApp.PartitionedCache do
  use Nebulex.Cache,
    otp_app: :my_app,
    adapter: Nebulex.Adapters.Partitioned
end

Where the configuration for the cache must be in your application environment, usually defined in your config/config.exs:

config :my_app, MyApp.PartitionedCache,
  primary: [
    gc_interval: :timer.hours(12),
    gc_memory_check_interval: :timer.seconds(10),
    max_size: 1_000_000,
    allocated_memory: 2_000_000_000
  ]

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:

def start(_type, _args) do
  children = [
    {MyApp.PartitionedCache, []},
  ]

  ...
end

See the online documentation for more information.

Testing

Since this adapter uses support modules and shared tests from Nebulex, but the test folder is not included in the Hex dependency, the following steps are required to run the tests.

First of all, make sure you set the environment variable NEBULEX_PATH to nebulex:

export NEBULEX_PATH=nebulex

Second, make sure you fetch :nebulex dependency directly from GtiHub by running:

mix nbx.setup

Third, fetch deps:

mix deps.get

Finally, you can run the tests:

mix test

Running tests with coverage:

mix coveralls.html

You will find the coverage report within cover/excoveralls.html.

Benchmarks

The adapter provides a set of basic benchmark tests using the library benchee, and they are located within the directory benchmarks.

To run a benchmark test you have to run:

$ MIX_ENV=test 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.

Contributing

Contributions to Nebulex are very welcome and appreciated!

Use the issue tracker for bug reports or feature requests. Open a pull request when you are ready to contribute.

When submitting a pull request you should not update the 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 test.ci and ensure all checks run successfully.

Copyright and License

Copyright (c) 2024 Carlos Andres Bolaños R.A.

nebulex_distributed source code is licensed under the MIT License.