Nebulex.Adapter.KV behaviour (Nebulex v3.0.0-rc.1)
View SourceSpecifies the adapter Key/Value API.
This behaviour specifies all read/write key-based functions, applied to a specific cache key.
Summary
Types
Proxy type to the adapter meta
Proxy type to the cache entries
Keep TTL flag
Proxy type to the cache key
Write command type
Proxy type to the cache options
TTL for a cache entry
Proxy type to the cache value
Callbacks
Deletes a single entry from cache.
Returns {:ok, true}
if the given key
exists and the new ttl
is
successfully updated; otherwise, {:ok, false}
is returned.
Fetches the value for a specific key
in the cache.
Determines if the cache contains an entry for the specified key
.
Puts the given value
under key
into the cache
.
Puts the given entries
(key/value pairs) into the cache
atomically
or fail otherwise.
Removes and returns the value associated with key
in the cache.
Returns {:ok, true}
if the given key
exists and the last access time is
successfully updated; otherwise, {:ok, false}
is returned.
Returns the remaining time-to-live for the given key
.
Updates the counter mapped to the given key
.
Types
@type adapter_meta() :: Nebulex.Adapter.adapter_meta()
Proxy type to the adapter meta
@type entries() :: Nebulex.Cache.entries()
Proxy type to the cache entries
@type keep_ttl() :: boolean()
Keep TTL flag
@type key() :: Nebulex.Cache.key()
Proxy type to the cache key
@type on_write() :: :put | :put_new | :replace
Write command type
@type opts() :: Nebulex.Cache.opts()
Proxy type to the cache options
@type ttl() :: timeout()
TTL for a cache entry
@type value() :: Nebulex.Cache.value()
Proxy type to the cache value
Callbacks
@callback delete(adapter_meta(), key(), opts()) :: :ok | Nebulex.Cache.error_tuple()
Deletes a single entry from cache.
If there's an error with executing the command, {:error, reason}
is returned, where reason
is the cause of the error.
@callback expire(adapter_meta(), key(), ttl(), opts()) :: Nebulex.Cache.ok_error_tuple(boolean())
Returns {:ok, true}
if the given key
exists and the new ttl
is
successfully updated; otherwise, {:ok, false}
is returned.
If there's an error with executing the command, {:error, reason}
is returned; where reason
is the cause of the error.
@callback fetch(adapter_meta(), key(), opts()) :: Nebulex.Cache.ok_error_tuple(value(), Nebulex.Cache.fetch_error_reason())
Fetches the value for a specific key
in the cache.
If the cache contains the given key
, then its value is returned
in the shape of {:ok, value}
.
If there's an error with executing the command, {:error, reason}
is returned. reason
is the cause of the error and can be
Nebulex.KeyError
if the cache does not contain key
,
Nebulex.Error
otherwise.
@callback has_key?(adapter_meta(), key(), opts()) :: Nebulex.Cache.ok_error_tuple(boolean())
Determines if the cache contains an entry for the specified key
.
More formally, it returns {:ok, true}
if the cache contains the given key
.
If the cache doesn't contain key
, {:ok, false}
is returned.
If there's an error with executing the command, {:error, reason}
is returned, where reason
is the cause of the error.
@callback put(adapter_meta(), key(), value(), on_write(), ttl(), keep_ttl(), opts()) :: Nebulex.Cache.ok_error_tuple(boolean())
Puts the given value
under key
into the cache
.
Returns {:ok, true}
if the value
with key key
is successfully inserted.
Otherwise, {:ok, false}
is returned.
If there's an error with executing the command, {:error, reason}
is returned, where reason
is the cause of the error.
The ttl
argument defines the time-to-live for the stored entry. If it is not
set, it means the entry doesn't have a time-to-live, so it shouldn't expire.
The keep_ttl
argument tells whether to retain the time to live associated
with the key. Otherwise, the TTL is always overwritten.
on_write
argument
The on_write
argument supports the following values:
:put
- If thekey
already exists, it is overwritten. Any previous time-to-live associated with the key is discarded on a successfulwrite
operation.:put_new
- It only stores the entry if thekey
does not exist. Otherwise,{:ok, false}
is returned.:replace
- Alters the value stored under the givenkey
, but only if the key already exists in the cache. Otherwise,{ok, false}
is returned.
See Nebulex.Cache.put/3
, Nebulex.Cache.put_new/3
,
Nebulex.Cache.replace/3
.
@callback put_all(adapter_meta(), entries(), on_write(), ttl(), opts()) :: Nebulex.Cache.ok_error_tuple(boolean())
Puts the given entries
(key/value pairs) into the cache
atomically
or fail otherwise.
If there's an error with executing the command, {:error, reason}
is returned, where reason
is the cause of the error.
The ttl
argument works the same as put/7
but applies to all keys.
on_write
argument
The on_write
argument supports the following values:
:put
- If thekey
already exists, it is overwritten. Any previous time-to-live associated with the key is discarded on a successfulwrite
operation.:put_new
- Insert all entries only if none exist in the cache, and it returns{:ok, true}
. Otherwise,{:ok, false}
is returned.
See Nebulex.Cache.put_all/2
and Nebulex.Cache.put_new_all/2
.
@callback take(adapter_meta(), key(), opts()) :: Nebulex.Cache.ok_error_tuple(value(), Nebulex.Cache.fetch_error_reason())
Removes and returns the value associated with key
in the cache.
If key
is present in the cache, its value is removed and returned as
{:ok, value}
.
If there's an error with executing the command, {:error, reason}
is returned. reason
is the cause of the error and can be
Nebulex.KeyError
if the cache does not contain key
or
Nebulex.Error
otherwise.
See Nebulex.Cache.take/2
.
@callback touch(adapter_meta(), key(), opts()) :: Nebulex.Cache.ok_error_tuple(boolean())
Returns {:ok, true}
if the given key
exists and the last access time is
successfully updated; otherwise, {:ok, false}
is returned.
If there's an error with executing the command, {:error, reason}
is returned, where reason
is the cause of the error.
@callback ttl(adapter_meta(), key(), opts()) :: Nebulex.Cache.ok_error_tuple(value(), Nebulex.Cache.fetch_error_reason())
Returns the remaining time-to-live for the given key
.
If key
is present in the cache, then its remaining TTL is returned
in the shape of {:ok, ttl}
.
If there's an error with executing the command, {:error, reason}
is returned. reason
is the cause of the error and can be
Nebulex.KeyError
if the cache does not contain key
,
Nebulex.Error
otherwise.
See Nebulex.Cache.ttl/2
.
@callback update_counter(adapter_meta(), key(), amount, default, ttl(), opts()) :: Nebulex.Cache.ok_error_tuple(integer()) when amount: integer(), default: integer()
Updates the counter mapped to the given key
.
If amount
> 0, the counter is incremented by the given amount
.
If amount
< 0, the counter is decremented by the given amount
.
If amount
== 0, the counter is not updated.
If there's an error with executing the command, {:error, reason}
is returned, where reason
is the cause of the error.
The ttl
is set when the key doesn't exist. Otherwise, only the counter is
updated keeping the TTL when the counter was updated for the first time.
See Nebulex.Cache.incr/3
.
See Nebulex.Cache.decr/3
.