Nebulex v1.2.2 Nebulex.Adapters.Local View Source

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_generations - Max number of Cache generations, defaults to 2.

  • :n_shards - The number of partitions for each Cache generation table. Defaults to System.schedulers_online(). See :shards.new/2.

  • :read_concurrency - Indicates whether the tables that :shards creates uses :read_concurrency or not (default: true). See :ets.new/2.

  • :write_concurrency - Indicates whether the tables that :shards creates uses :write_concurrency or not (default: true). See :ets.new/2.

  • :compressed - If this option is present, the table data is stored in a more compact format to consume less memory. However, it will make table operations slower (default: false). See :ets.new/2.

  • :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([]).

  • :allocated_memory - Max size in bytes allocated for a cache generation. If this option is set and the configured value is reached, a new generation is created so the oldest is deleted and force releasing memory space. If it is not set (nil), the cleanup check to release memory is not performed (the default).

  • :gc_cleanup_interval - The number of writes needed to run the cleanup check. Once this value is reached and only if allocated_memory option is set, the cleanup check is performed. Defaults to 10, so after 10 write operations the cleanup check is performed.

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.