Nebulex v1.2.0 Nebulex View Source

Nebulex is split into 2 main components:

• Nebulex.Cache - caches are wrappers around the in-memory data store. Via the cache, we can insert, retrieve, update and delete entries from the in-memory data store. A cache needs an adapter to communicate to the in-memory data store.

• Nebulex.Object - this is the struct used by caches to handle data back and forth, entries in cache are stored and retrieved as objects, but this is totally handled by the cache adapter.

In the following sections, we will provide an overview of those components and how they interact with each other. Feel free to access their respective module documentation for more specific examples, options and configuration.

If you want to quickly check a sample application using Nebulex, please check the getting started guide.

Caches

Nebulex.Cache is the wrapper around the Cache. We can define a cache as follows:

defmodule MyApp.MyCache 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.MyCache,
  n_shards: 2,
  gc_interval: 3600

Each cache in Nebulex defines a start_link/1 function that needs to be invoked before using the cache. In general, this function is not called directly, but used as part of your application supervision tree.

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 repo as a supervisor on your application's supervisor:

def start(_type, _args) do
  children = [
    {MyApp.Cache, []}
  ]

  opts = [strategy: :one_for_one, name: MyApp.Supervisor]
  Supervisor.start_link(children, opts)
end

You can use the cache from your application whatever you want. For example, let's suppose we want to handle user sessions in cache:

defmodule MyApp.UserSession do
  alias MyApp.Repo
  alias MyApp.Cache
  alias MyApp.User

  def new(username, password) do
    case Repo.get(User, username) do
      %User{password: ^password} = user ->
        sesion_token =
          username
          |> generate_token(password)
          |> Cache.set(user, ttl: 3600)

        {:ok, sesion_token}

      _ ->
        {:error, :unauthorized}
    end
  end

  def get(token) do
    case Cache.get(token) do
      nil -> {:error, :not_found}
      user -> {:ok, user}
    end
  end

  ## Helpers

  defp generate_token(username, password) do
    # your code ...
  end
end

Object

Nebulex.Object is the struct used by the caches to store and retrieve data.

By default, when we perform an action (set, get, delete, etc.) on a cache entry, the cache returns only the value of that entry, but you can ask for return the whole object:

iex> MyCache.set("foo", "bar", return: :object)
%Nebulex.Object{key: "foo", expire_at: nil, value: "bar", version: nil}

iex> MyCache.get("foo", return: :object)
%Nebulex.Object{key: "foo", expire_at: nil, value: "bar", version: nil}

See Nebulex.Object to learn more about it.

Object Versioning (Optimistic Offline Locks)

It is also possible to set a version (or ETag) on the object to be cached; in the case you want to implement something like "Optimistic Locking" through a version property on cached objects.

Supposing we have a "serial" version generator:

iex> MyCache.set("foo", "bar", return: :object)
%Nebulex.Object{key: "foo", expire_at: nil, value: "bar", version: 1}

iex> MyCache.set("foo", "bar", version: 1, return: :object)
%Nebulex.Object{key: "foo", expire_at: nil, value: "bar", version: 2}

iex> MyCache.set("foo", "bar", version: 2, return: :object)
%Nebulex.Object{key: "foo", expire_at: nil, value: "bar", version: 3}