Nebulex Local

A generational local cache adapter for Nebulex.

About

This adapter provides a high-performance generational local cache for Nebulex, inspired by epocxy. It uses a generational garbage collection with two-generation approach (new and old) for efficient memory management.

See the module documentation for detailed information about generational caching, concurrency handling, and configuration options.

Installation

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

def deps do
  [
    {:nebulex_local, "~> 3.0"},
    {:telemetry, "~> 0.4 or ~> 1.0"}, # For observability/telemetry support
    {:decorator, "~> 1.4"},           # For declarative caching
    {:shards, "~> 1.1"},              # For high concurrency workloads with partitioning
    {:ex2ms, "~> 1.7"}                # For match specification query helpers
  ]
end

To provide more flexibility and load only the needed dependencies, this adapter makes some dependencies optional:

:telemetry - Add when you want to emit and consume telemetry events for monitoring cache operations (recommended).
:decorator - Add when you want to enable declarative decorator-based caching (recommended).
:shards - Add when using backend: :shards for intensive workloads that benefit from partitioning across multiple ETS tables.
:ex2ms - Add when using match specification query helpers for advanced querying.

Usage

You can define a cache as follows:

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

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

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

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

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

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:

local_with_ets_bench.exs: benchmark for the local adapter using :ets backend.
local_with_shards_bench.exs: benchmark for the local adapter using :shards backend.

For example, for running the benchmark for the local adapter using :shards backend:

$ MIX_ENV=test mix run benchmarks/local_with_shards_bench.exs

Additionally, you can also run performance tests using :basho_bench. See nebulex_bench example for more information.

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

nebulex_local source code is licensed under the MIT License.