Nebulex.Adapters.Cachex

A Nebulex adapter for Cachex.

About

This adapter provides a Nebulex interface on top of Cachex, a powerful in-memory caching library for Elixir. It combines Nebulex's unified caching API with Cachex's rich feature set.

Installation

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

def deps do
  [
    {:nebulex_adapters_cachex, "~> 3.0.0-rc.2"},
    {:telemetry, "~> 0.4 or ~> 1.0"}    # For observability/telemetry support
  ]
end

The :telemetry dependency is optional but highly recommended for observability and monitoring cache operations.

Usage

Define your cache:

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

Configure in your config/config.exs:

config :my_app, MyApp.Cache,
  stats: true

Add to your application supervision tree:

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

  Supervisor.start_link(children, strategy: :one_for_one)
end

The adapter supports all Cachex options. See Cachex.start_link/2 for configuration options including expiration, hooks, limits, and warmers.

For more details and examples, see the module documentation.

Distributed Caching Topologies

The Cachex adapter works seamlessly with Nebulex's distributed adapters. Use it as a local cache in multi-level topologies or as primary storage for partitioned caches.

Example: Multi-level cache (near cache pattern)

defmodule MyApp.NearCache do
  use Nebulex.Cache,
    otp_app: :my_app,
    adapter: Nebulex.Adapters.Multilevel

  defmodule L1 do
    use Nebulex.Cache,
      otp_app: :my_app,
      adapter: Nebulex.Adapters.Cachex
  end

  defmodule L2 do
    use Nebulex.Cache,
      otp_app: :my_app,
      adapter: Nebulex.Adapters.Partitioned,
      primary_storage_adapter: Nebulex.Adapters.Cachex
  end
end

Configuration:

config :my_app, MyApp.NearCache,
  model: :inclusive,
  levels: [
    {MyApp.NearCache.L1, []},
    {MyApp.NearCache.L2, primary: [transactions: true]}
  ]

You can also use Nebulex.Adapters.Redis for L2 to add persistence. See the module documentation and Nebulex examples for more topologies.

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 GitHub 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

Benchmarks were added using benchee, and they are located within the directory benchmarks.

To run the benchmarks:

MIX_ENV=test mix run benchmarks/benchmark.exs

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 submitting a PR it is highly recommended to run mix test.ci and ensure all checks run successfully.

Copyright and License

Copyright (c) 2020, Carlos Bolaños.

Nebulex.Adapters.Cachex source code is licensed under the MIT License.