Adapter module for Multi-level Cache.

This is just a simple layer on top of local or distributed cache implementations that enables to have a cache hierarchy by levels. Multi-level caches generally operate by checking the fastest, level 1 (L1) cache first; if it hits, the adapter proceeds at high speed. If that first cache misses, the next fastest cache (level 2, L2) is checked, and so on, before accessing external memory (that can be handled by a :fallback function).

Beware this behaviour only takes place for get/3 function, rest of the functions behaves most like a bypass.

Options

These options should be set in the config file and require recompilation in order to make an effect.

• :adapter - The adapter name, in this case, Nebulex.Adapters.Multilevel

• :cache_model - Specifies the cache model: :inclusive or :exclusive; defaults to :inclusive. In an inclusive cache, the same data can be present in all caches/levels. In an exclusive cache, data can be present in only one cache/level and a key cannot be found in the rest of caches at the same time. This option affects get operation only.

• :levels - The list of caches where each cache corresponds to a level. The order of the caches in the list defines the the order of the levels as well, for example, the first cache in the list will be the L1 cache (level 1) and so on; the Nth elemnt will be the LN cache. This option is mandatory, if it is not set or empty, an exception will be raised.

• :fallback - Defines a fallback function when a key is not present in any cache level. Function is defined as: (key -> value).

The :fallback can be defined in two ways: at compile-time and at run-time. At compile-time, in the cache config, set the module that implements the function:

config :my_app, MyApp.MultilevelCache,
  fallback: &MyMapp.AnyModule/1

And at run-time, passing the function as an option within the opts argument (only valid for get function):

MultilevelCache.get("foo", fallback: fn(key) -> key * 2 end)

Shared Options

Some functions below accept the following options:

• :level - It may be an integer greater than 0 that specifies the cache level where the operation will take place, or it may be also :all to execute the operation in all cache levels. By default it’s set to 1, which means the set will only be evaluated at the first cache level.

Example

Nebulex.Cache is the wrapper around the Cache. We can define the multi-level cache as follows:

defmodule MyApp.MultilevelCache do
  use Nebulex.Cache, otp_app: :nebulex, adapter: Nebulex.Adapters.Multilevel

  defmodule L1 do
    use Nebulex.Cache, otp_app: :nebulex, adapter: Nebulex.Adapters.Local
  end

  defmodule L2 do
    use Nebulex.Cache, otp_app: :nebulex, adapter: Nebulex.Adapters.Dist
  end

  def fallback(_key) do
    # maybe fetch the data from Database
    nil
  end
end

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.MultilevelCache,
  levels: [
    MyApp.MultilevelCache.L1,
    MyApp.MultilevelCache.L2
  ],
  fallback: &MyApp.MultilevelCache.fallback/1

config :my_app, MyApp.MultilevelCache.L1,
  n_shards: 2,
  gc_interval: 3600

config :my_app, MyApp.MultilevelCache.L2,
  local: MyApp.LocalCache

config :my_app, MyApp.LocalCache,
  n_shards: 2,
  gc_interval: 3600

Extended API

This adapter provides some additional functions to the Nebulex.Cache API.

__levels__

This function returns the configured level list.

MyCache.__levels__

__model__

This function returns the multi-level cache model.

MyCache.__model__

__fallback__

This function returns the default fallback function.

MyCache.__fallback__

Limitations

Because this adapter reuses other existing/configured adapters, it inherits all their limitations too. Therefore, it is highly recommended to check the documentation of the used adapters.