Nebulex.Adapter.KV behaviour (Nebulex v3.0.0-rc.1)

View Source

Specifies 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

adapter_meta()

@type adapter_meta() :: Nebulex.Adapter.adapter_meta()

Proxy type to the adapter meta

entries()

@type entries() :: Nebulex.Cache.entries()

Proxy type to the cache entries

keep_ttl()

@type keep_ttl() :: boolean()

Keep TTL flag

key()

@type key() :: Nebulex.Cache.key()

Proxy type to the cache key

on_write()

@type on_write() :: :put | :put_new | :replace

Write command type

opts()

@type opts() :: Nebulex.Cache.opts()

Proxy type to the cache options

ttl()

@type ttl() :: timeout()

TTL for a cache entry

value()

@type value() :: Nebulex.Cache.value()

Proxy type to the cache value

Callbacks

delete(adapter_meta, key, opts)

@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.

See Nebulex.Cache.delete/2.

expire(adapter_meta, key, ttl, opts)

@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.

See Nebulex.Cache.expire/3.

fetch(adapter_meta, key, opts)

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.

See Nebulex.Cache.fetch/2.

has_key?(adapter_meta, key, opts)

@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.

See Nebulex.Cache.has_key?/2.

put(adapter_meta, key, value, on_write, ttl, keep_ttl, opts)

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 the key already exists, it is overwritten. Any previous time-to-live associated with the key is discarded on a successful write operation.

  • :put_new - It only stores the entry if the key does not exist. Otherwise, {:ok, false} is returned.

  • :replace - Alters the value stored under the given key, 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.

put_all(adapter_meta, entries, on_write, ttl, opts)

@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 the key already exists, it is overwritten. Any previous time-to-live associated with the key is discarded on a successful write 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.

take(adapter_meta, key, opts)

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.

touch(adapter_meta, key, opts)

@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.

See Nebulex.Cache.touch/2.

ttl(adapter_meta, key, opts)

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.

update_counter(adapter_meta, key, amount, default, ttl, opts)

@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.