Nebulex v1.2.2 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}