Skip to content

README.md

Latest commit

 

History

History
167 lines (122 loc) · 4.5 KB

README.md

File metadata and controls

167 lines (122 loc) · 4.5 KB
Raw

Nebulex.Adapters.Cachex

A Nebulex adapter for Cachex.

CI Codecov Hex Version Documentation

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"},
    {: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,
      adapter_opts: [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

The test suite uses support modules and shared tests from the Nebulex repository, which are not included in the Hex package. Fetch the dependencies, clone Nebulex with mix nbx.setup, and run the tests with NEBULEX_PATH pointing to that checkout:

mix deps.get
mix nbx.setup
NEBULEX_PATH=nebulex mix test

Running tests with coverage:

NEBULEX_PATH=nebulex 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

Use the issue tracker for bug reports and feature requests. Contributions are welcome through pull requests.

Include tests for new or changed behavior, and leave CHANGELOG.md unchanged. Before submitting a pull request, run NEBULEX_PATH=nebulex mix precommit and fix any failures.

Copyright and License

Copyright (c) 2020, Carlos Bolaños.

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