Adapter module for Local Generational Cache.

It uses Shards as in-memory backend (ETS tables are used internally).

Features

• Support for generational cache – inspired by epocxy.

• Support for Sharding – handled by :shards.

• Support for garbage collection via Nebulex.Adapters.Local.Generation

• Support for transactions via Erlang global name registration facility

Options

These options can be set through the config file:

• :n_shards - The number of partitions for each Cache generation table. Defaults to :erlang.system_info(:schedulers_online).

• :n_generations - Max number of Cache generations, defaults to 2.

• :read_concurrency - Indicates whether the tables that :shards creates uses :read_concurrency or not (default: true).

• :write_concurrency - Indicates whether the tables that :shards creates uses :write_concurrency or not (default: true).

• :gc_interval - Interval time in seconds to garbage collection to run, delete the oldest generation and create a new one. If this option is not set, garbage collection is never executed, so new generations must be created explicitly, e.g.: MyCache.new_generation([]).

Example

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

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.LocalCache,
  n_shards: 2,
  gc_interval: 3600,
  write_concurrency: true

For more information about the usage, check out Nebulex.Cache.

Extended API

This adapter provides some additional functions to the Nebulex.Cache API. Most of these functions are used internally by the adapter, but there is one function which is indeed provided to be used from the Cache API, and it is the function to create new generations: new_generation/1.

MyApp.LocalCache.new_generation

Other additional function that might be useful is: __metadata__, which is used to retrieve the Cache Metadata.

MyApp.LocalCache.__metadata__

The rest of the functions as we mentioned before, are for internal use.

Queryable API

The adapter supports as query parameter the following values:

• query - nil | :all_unexpired | :all_expired | :ets.match_spec()

Internally, an entry is represented by the tuple {key, val, vsn, exp}, which means the match pattern within the :ets.match_spec() must be something like {:"$1", :"$2", :"$3", :"$4"}. In order to make query building easier, you can use Ex2ms library.

Examples

# built-in queries
MyCache.all()
MyCache.all(:all_unexpired)
MyCache.all(:all_expired)

# using a custom match spec (all values > 10)
spec = [{{:"$1", :"$2", :_, :_}, [{:>, :"$2", 10}], [{{:"$1", :"$2"}}]}]
MyCache.all(spec)

# using Ex2ms
import Ex2ms

spec =
  fun do
    {key, value, _version, _expire_at} when value > 10 -> {key, value}
  end

MyCache.all(spec)

The :return option applies only for built-in queries, such as: nil | :all_unexpired | :all_expired, if you are using a custom :ets.match_spec(), the return value depends on it.

The same applies to stream function.