Nebulex.Adapters.Cachex

A Nebulex adapter for Cachex.

See the online documentation for more information.

NOTE: This adapter only supports Nebulex v2.0.0 onwards.

Installation

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

def deps do
  [
    {:nebulex_adapters_cachex, "~> 2.1"}
  ]
end

Usage

You can define a cache using Cachex as follows:

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

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

config :my_app, MyApp.Cache,
  limit: 1_000_000,
  stats: true,
  ...

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.Cache, []},
  ]

  ...
end

Since Cachex uses macros for some configuration options, you could also pass the options in runtime when the cache is started, either by calling MyApp.Cache.start_link/1 directly, or in your app supervision tree:

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

  ...
end

defp cachex_opts do
  import Cachex.Spec

  [
    expiration: expiration(
      # default record expiration
      default: :timer.seconds(60),

      # how often cleanup should occur
      interval: :timer.seconds(30),

      # whether to enable lazy checking
      lazy: true
    ),

    # complex limit
    limit: limit(
      size: 500,
      policy: Cachex.Policy.LRW,
      reclaim: 0.5,
      options: []
    ),

    ...
  ]
end

See Cachex.start_link/1 for more information about the options.

Distributed caching topologies

In the same way we use the distributed adapters and the multilevel one to create distributed topologies, we can also do the same but instead of using the built-in local adapter using Cachex.

For example, let's define a multi-level cache (near cache topology), where the L1 is a local cache using Cachex and the L2 is a partitioned cache.

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

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

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

And the configuration may look like:

config :my_app, MyApp.NearCache,
  model: :inclusive,
  levels: [
    {MyApp.NearCache.L1, [limit: 100_000]},
    {MyApp.NearCache.L2, primary: [limit: 1_000_000]}
  ]

NOTE: You could also use NebulexRedisAdapter for L2, it would be matter of changing the adapter for the L2 and the configuration for set up Redis adapter.

See Nebulex examples. You will find examples for all different topologies, even using other adapters like Redis; for all examples you just have to replace Nebulex.Adapters.Local by Nebulex.Adapters.Cachex.

Testing

Since Nebulex.Adapters.Cachex uses the support modules and shared tests from Nebulex and by default its test folder is not included in the Hex dependency, the following steps are required for running 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

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

Copyright and License

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

cabol / nebulex_adapters_cachex