Nebulex 🌌

In-Process and Distributed Caching Framework for Elixir.

Easily craft and deploy different distributed caching topologies in Elixir.

Nebulex is an in-process and distributed caching framework with a set of useful and powerful features such as:

Inspired by Ecto; simple and fluent API, flexible and pluggable architecture (based on adapters).
Built-in adapters: local (generational cache), distributed and multi-level.
Caching DSL to implement different cache usage patterns.
Support for different distributed caching topologies, such as: Partitioned, Near, Replicated, etc.
Different eviction mechanisms, such as time-based eviction through the expiry time property (expire_at) on the cached objects, multi-queue or generational caching (built-in adapter), etc.
Object versioning (via :version property); useful for Optimistic offline locks implementation.
Pre/Post execution hooks. Ability to hook any function call for a cache and add custom logic before and/or after function execution.
Transactions and key-locking (Nebulex.Adapter.Transaction).

See the getting started guide and the online documentation.

Usage

You need to add nebulex as a dependency to your mix.exs file. However, in the case you want to use an external (non built-in) cache adapter, you also have to add the proper dependency to your mix.exs file.

The supported caches and their adapters are:

Cache	Nebulex Adapter	Dependency
Generational	Nebulex.Adapters.Local	Built-In
Partitioned	Nebulex.Adapters.Dist	Built-In
Multi-level	Nebulex.Adapters.Multilevel	Built-In
Redis	NebulexRedisAdapter	nebulex_redis_adapter
Memcached	NebulexMemcachedAdapter	nebulex_memcached_adapter

For example, if you want to use a built-in cache, you just need to add nebulex to your mix.exs file:

def deps do
  [
    {:nebulex, "~> 1.1"}
  ]
end

Then run mix deps.get in your shell to fetch the dependencies. If you want to use another cache adapter, just choose the proper dependency from the table above.

Finally, in the cache definition, you will need to specify the adapter respective to the chosen dependency. For the local built-in cache it is:

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

Check out the getting started guide to learn more about it.

Important links

Testing

Testing by default spawns nodes internally for distributed tests. To run tests that do not require clustering, exclude the clustered tag:

$ mix test --exclude clustered

If you have issues running the clustered tests try running:

$ epmd -daemon

before running the tests.

Benchmarks

Some basic benchmarks were added using benchee; to learn more, check out the benchmarks directory.

To run the benchmarks:

$ mix run benchmarks/benchmark.exs

If you are interested to run more sophisticated load tests, perhaps you should checkout the Nebulex Load Tests example, it allows you to run your own performance/load tests against Nebulex, and it also comes with load tests results.

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 test to run tests
mix coveralls.html && open cover/excoveralls.html to run tests and check out code coverage (expected 100%).
mix format && mix credo --strict to format your code properly and find code style issues
mix dialyzer to run dialyzer for type checking; might take a while on the first invocation

Copyright and License

Nebulex source code is licensed under the MIT License.

polmiro/nebulex