Nebulex v2.0.0-rc.0 Nebulex.Adapter behaviour View Source
This module specifies the adapter API that a Cache adapter is required to implement.
Link to this section Summary
Functions
RExecutes the function fun passing as parameters the adapter and metadata
(from the init/1 callback) associated with the given cache name_or_pid.
Callbacks
The callback invoked in case the adapter needs to inject code.
Deletes a single entry from cache.
Returns true if the given key exists and the new ttl was successfully
updated, otherwise, false is returned.
Flushes the cache and returns the number of evicted keys.
Gets the value for a specific key in cache.
Gets a collection of entries from the Cache, returning them as Map.t() of
the values associated with the set of keys requested.
Returns whether the given key exists in cache.
Increments or decrements the counter mapped to the given key.
Initializes the adapter supervision tree by returning the children.
Puts the given value under key into the cache.
Puts the given entries (key/value pairs) into the cache.
Returns the total number of cached entries.
Returns and removes the entry with key key in the cache.
Returns true if the given key exists and the last access time was
successfully updated, otherwise, false is returned.
Returns the TTL (time-to-live) for the given key. If the key does not
exist, then nil is returned.
Link to this section Types
Specs
adapter_meta() :: map()
The metadata returned by the adapter init/1.
It must be a map and Nebulex itself will always inject two keys into the meta:
:cache- The cache module.:name- The nase of the cache.:pid- The PID returned by the child spec returned ininit/1
Specs
cache() :: Nebulex.Cache.t()
Specs
child_spec() :: :supervisor.child_spec() | {module(), term()} | module() | nil
Specs
entries() :: Nebulex.Cache.entries()
Specs
entry() :: Nebulex.Entry.t()
Specs
key() :: Nebulex.Cache.key()
Specs
on_write() :: :put | :put_new | :replace
Specs
opts() :: Nebulex.Cache.opts()
Specs
t() :: module()
Specs
ttl() :: timeout()
Specs
value() :: Nebulex.Cache.value()
Link to this section Functions
Specs
RExecutes the function fun passing as parameters the adapter and metadata
(from the init/1 callback) associated with the given cache name_or_pid.
It expects a name or a PID representing the cache.
Link to this section Callbacks
Specs
__before_compile__(term(), env :: Macro.Env.t()) :: Macro.t()
The callback invoked in case the adapter needs to inject code.
Specs
delete(adapter_meta(), key(), opts()) :: :ok
Deletes a single entry from cache.
Specs
expire(adapter_meta(), key(), ttl()) :: boolean()
Returns true if the given key exists and the new ttl was successfully
updated, otherwise, false is returned.
Specs
flush(adapter_meta()) :: integer()
Flushes the cache and returns the number of evicted keys.
Specs
get(adapter_meta(), key(), opts()) :: value()
Gets the value for a specific key in cache.
See Nebulex.Cache.get/2.
Specs
get_all(adapter_meta(), [key()], opts()) :: map()
Gets a collection of entries from the Cache, returning them as Map.t() of
the values associated with the set of keys requested.
For every key that does not hold a value or does not exist, that key is simply ignored. Because of this, the operation never fails.
Specs
has_key?(adapter_meta(), key()) :: boolean()
Returns whether the given key exists in cache.
Specs
Increments or decrements the counter mapped to the given key.
See Nebulex.Cache.incr/3.
Specs
init(opts()) :: {:ok, child_spec(), adapter_meta()}
Initializes the adapter supervision tree by returning the children.
Specs
Puts the given value under key into the cache.
Returns true if the value with key key is successfully inserted;
otherwise false is returned.
The ttl argument sets the time-to-live for the stored entry. If it is not
set, it means the entry hasn't a time-to-live, then it shouldn't expire.
OnWrite
The on_write argument supports the following values:
:put- If thekeyalready exists, it is overwritten. Any previous time-to-live associated with the key is discarded on successfulwriteoperation.:put_new- It only stores the entry if thekeydoes not already exist, otherwise,falseis returned.:replace- Alters the value stored under the givenkey, but only if the key already exists into the cache, otherwise,falseis returned.
See Nebulex.Cache.put/3, Nebulex.Cache.put_new/3, Nebulex.Cache.replace/3.
Specs
Puts the given entries (key/value pairs) into the cache.
Returns true if all the keys were inserted. If no key was inserted
(at least one key already existed), false is returned.
The ttl argument sets the time-to-live for the stored entry. If it is not
set, it means the entry hasn't a time-to-live, then it shouldn't expire.
The given ttl is applied to all keys.
OnWrite
The on_write argument supports the following values:
:put- If thekeyalready exists, it is overwritten. Any previous time-to-live associated with the key is discarded on successfulwriteoperation.:put_new- It only stores the entry if thekeydoes not already exist, otherwise,falseis returned.
Ideally, this operation should be atomic, so all given keys are set at once. But it depends purely on the adapter's implementation and the backend used internally by the adapter. Hence, it is recommended to checkout the adapter's documentation.
Specs
size(adapter_meta()) :: integer()
Returns the total number of cached entries.
See Nebulex.Cache.size/0.
Specs
take(adapter_meta(), key(), opts()) :: value()
Returns and removes the entry with key key in the cache.
See Nebulex.Cache.take/2.
Specs
touch(adapter_meta(), key()) :: boolean()
Returns true if the given key exists and the last access time was
successfully updated, otherwise, false is returned.
Specs
ttl(adapter_meta(), key()) :: ttl() | nil
Returns the TTL (time-to-live) for the given key. If the key does not
exist, then nil is returned.
See Nebulex.Cache.ttl/1.