Popularity
9.1
Growing
Activity
6.3
Growing
620
6
29

Description

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; supporting local, distributed and multi-level caching.

- 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 on the cached objects, multi-queue or generational caching (built-in local cache), etc.

- Object versioning (through the :version property); enabling Optimistic offline locks

- Pre/Post execution hooks

- Transactions and key-locking

Monthly Downloads: 14,941
Programming language: Elixir
License: MIT License
Tags: Caching     Frameworks     ETS     Elixir    
Latest version: v2.0.0-rc.1

Nebulex alternatives and similar packages

Based on the "Caching" category.
Alternatively, view nebulex alternatives based on common mentions on social networks and blogs.

Do you think we are missing an alternative of Nebulex or a related project?

Add another 'Caching' Package

README

Nebulex 🌌

In-Process and Distributed Cache Toolkit for Elixir.

Easily craft and deploy distributed cache topologies and cache usage patterns.

CI Coverage Status Inline docs Hex Version Docs

Nebulex provides support for transparently adding caching into an existing Elixir application. Similar to Ecto, the caching abstraction allows consistent use of various caching solutions with minimal impact on the code. Furthermore, it enables the implementation of different cache usage patterns, distributed cache topologies, and more.

Supposing we are using Ecto and we want to apply caching declaratively on some functions:

# In the config/config.exs file
config :my_app, MyApp.PartitionedCache,
  primary: [
    gc_interval: :timer.seconds(3600),
    backend: :shards,
    partitions: 2
  ]

# Defining a Cache with a partitioned topology
defmodule MyApp.PartitionedCache do
  use Nebulex.Cache,
    otp_app: :my_app,
    adapter: Nebulex.Adapters.Partitioned,
    primary_storage_adapter: Nebulex.Adapters.Local
end

# Some Ecto schema
defmodule MyApp.Accounts.User do
  use Ecto.Schema

  schema "users" do
    field(:username, :string)
    field(:password, :string)
    field(:role, :string)
  end

  def changeset(user, attrs) do
    user
    |> cast(attrs, [:username, :password, :role])
    |> validate_required([:username, :password, :role])
  end
end

# The Accounts context
defmodule MyApp.Accounts do
  use Nebulex.Caching

  alias MyApp.Accounts.User
  alias MyApp.PartitionedCache, as: Cache
  alias MyApp.Repo

  @ttl Nebulex.Time.expiry_time(1, :hour)

  @decorate cacheable(cache: Cache, key: {User, id}, opts: [ttl: @ttl])
  def get_user!(id) do
    Repo.get!(User, id)
  end

  @decorate cacheable(cache: Cache, key: {User, username}, opts: [ttl: @ttl])
  def get_user_by_username(username) do
    Repo.get_by(User, [username: username])
  end

  @decorate cache_put(
              cache: Cache,
              keys: [{User, usr.id}, {User, usr.username}],
              match: &match_update/1
            )
  def update_user(%User{} = usr, attrs) do
    usr
    |> User.changeset(attrs)
    |> Repo.update()
  end

  defp match_update({:ok, usr}), do: {true, usr}
  defp match_update({:error, _}), do: false

  @decorate cache_evict(cache: Cache, keys: [{User, usr.id}, {User, usr.username}])
  def delete_user(%User{} = usr) do
    Repo.delete(usr)
  end

  def create_user(attrs \\ %{}) do
    %User{}
    |> User.changeset(attrs)
    |> Repo.insert()
  end
end

Nebulex is commonly used to interact with different cache implementations and/or stores (such as Redis, Memcached, or other implementations of cache in Elixir), being completely agnostic from them, avoiding the vendor lock-in.

See the getting started guide and the online documentation for more information.

Usage

You need to add nebulex as a dependency to your mix.exs file. However, in the case you want to use an external (a non built-in adapter) 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 Local Cache (ETS + Shards) Nebulex.Adapters.Local Built-In
Partitioned (layer on top of a local cache) Nebulex.Adapters.Partitioned Built-In
Replicated (layer on top of a local cache) Nebulex.Adapters.Replicated Built-In
Multilevel (layer on top of existing caches) Nebulex.Adapters.Multilevel Built-In
Redis NebulexRedisAdapter nebulex_redis_adapter
Memcached NebulexMemcachedAdapter nebulex_memcached_adapter
FoundationDB NebulexFdbAdapter nebulex_fdb_adapter

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

def deps do
  [
    {:nebulex, "~> 2.0"},
    {:shards, "~> 0.6"},   #=> For using :shards as backend
    {:decorator, "~> 1.3"} #=> For using Caching Annotations
  ]
end

In order to give more flexibility and loading only needed dependencies, Nebulex makes all its dependencies as optional. For example:

  • For intensive workloads, we may want to use :shards as the backend for the local adapter and having partitioned tables. In such a case, you have to add :shards to the dependency list.

  • For enabling the usage of declarative annotation-based caching via decorators, you have to add :decorator to the dependency list.

  • Also, all the external adapters have to be added as a dependency as well.

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
end

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](./benchmarks) directory.

To run the benchmarks:

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

Copyright (c) 2017, Carlos Bolaños.

Nebulex source code is licensed under the [MIT License](LICENSE).


*Note that all licence references and agreements mentioned in the Nebulex README section above are relevant to that project's source code only.