Nebulex v1.2.0 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 to2
.:n_shards
- The number of partitions for each Cache generation table. Defaults toSystem.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 ifallocated_memory
option is set, the cleanup check is performed. Defaults to10
, 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.