Nebulex v1.1.1 Nebulex.Adapter behaviour View Source

This module specifies the adapter API that a Cache adapter is required to implement.

Link to this section Summary

Callbacks

__before_compile__(env)

The callback invoked in case the adapter needs to inject code.

delete(cache, key, opts)

Deletes a single object from cache.

expire(cache, key, ttl)

Returns the expiry timestamp for the given key, if the timeout ttl (in seconds) is successfully updated.

flush(cache)

Flushes the cache.

get(cache, key, opts)

Retrieves a single object from cache.

get_many(cache, list, opts)

Returns a map with the objects for all specified keys. 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.

has_key?(cache, key)

Returns whether the given key exists in cache.

init(opts)

Initializes the adapter supervision tree by returning the children

object_info(cache, key, attr)

Returns the information associated with attr for the given key, or returns nil if key doesn't exist.

set(cache, object, opts)

Sets the given object under key into the cache.

set_many(cache, list, opts)

Sets the given objects, replacing existing ones, just as regular set.

size(cache)

Returns the total number of cached entries.

take(cache, key, opts)

Returns and removes the object with key key in the cache.

update_counter(cache, key, incr, opts)

Updates (increment or decrement) the counter mapped to the given key.

Link to this section Types

cache()

cache() :: Nebulex.Cache.t()

key()

key() :: Nebulex.Cache.key()

object()

object() :: Nebulex.Object.t()

opts()

opts() :: Nebulex.Cache.opts()

t()

t() :: module()

Link to this section Callbacks

__before_compile__(env)

__before_compile__(term(), env :: Macro.Env.t()) :: Macro.t()

The callback invoked in case the adapter needs to inject code.

delete(cache, key, opts)

delete(cache(), key(), opts()) :: :ok

Deletes a single object from cache.

See Nebulex.Cache.delete/2.

expire(cache, key, ttl)

expire(cache(), key(), ttl :: timeout()) :: timeout() | nil

Returns the expiry timestamp for the given key, if the timeout ttl (in seconds) is successfully updated.

If key doesn't exist, nil is returned.

See Nebulex.Cache.expire/2.

flush(cache)

flush(cache()) :: :ok

Flushes the cache.

See Nebulex.Cache.flush/0.

get(cache, key, opts)

get(cache(), key(), opts()) :: object() | nil

Retrieves a single object from cache.

See Nebulex.Cache.get/2.

get_many(cache, list, opts)

get_many(cache(), [key()], opts()) :: map()

Returns a map with the objects for all specified keys. 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.

See Nebulex.Cache.get_many/2.

has_key?(cache, key)

has_key?(cache(), key()) :: boolean()

Returns whether the given key exists in cache.

See Nebulex.Cache.has_key?/1.

init(opts)

init(opts()) ::
  {:ok, [:supervisor.child_spec() | {module(), term()} | module()]}

Initializes the adapter supervision tree by returning the children

object_info(cache, key, attr)

object_info(cache(), key(), attr :: :ttl | :version) :: any() | nil

Returns the information associated with attr for the given key, or returns nil if key doesn't exist.

See Nebulex.Cache.object_info/2.

set(cache, object, opts)

set(cache(), object(), opts()) :: boolean()

Sets the given object under key into the cache.

If the object already exists, it is overwritten. Any previous time to live associated with the key is discarded on successful set operation.

Returns true if an object with key key is found and successfully inserted, otherwise false.

Options

Besides the "Shared options" section in Nebulex.Cache documentation, it accepts:

:action - It may be one of :add, :replace, :set (the default). See the "Actions" section for more information.

Actions

The :action option supports the following values:

:add - Only set the key if it does not already exist. If it does, false is returned.
:replace - Alters the object stored under key, but only if the object already exists into the cache.
:set - Set key to hold the given object (default).

See Nebulex.Cache.set/3, Nebulex.Cache.add/3, Nebulex.Cache.replace/3.

set_many(cache, list, opts)

set_many(cache(), [object()], opts()) :: :ok | {:error, failed_keys :: [key()]}

Sets the given objects, replacing existing ones, just as regular set.

Returns :ok if the all objects were successfully set, otherwise {:error, failed_keys}, where failed_keys contains the keys that could not be set.

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.

See Nebulex.Cache.set_many/2.

size(cache)

size(cache()) :: integer()

Returns the total number of cached entries.

See Nebulex.Cache.size/0.

take(cache, key, opts)

take(cache(), key(), opts()) :: object() | nil

Returns and removes the object with key key in the cache.

See Nebulex.Cache.take/2.

update_counter(cache, key, incr, opts)

update_counter(cache(), key(), incr :: integer(), opts()) :: integer()

Updates (increment or decrement) the counter mapped to the given key.

See Nebulex.Cache.update_counter/3.