Nebulex Local

A generational local cache adapter for Nebulex.

See the online documentation for more information.

Installation

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

def deps do
  [
    {:nebulex_local, "~> 3.0"}
  ]
end

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 Nebulex.Adapters.Local 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

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

Copyright and License

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

nebulex_local source code is licensed under the MIT License.