Nebulex

v1.1.0

Nebulex v1.1.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

Types

cache()
key()
object()
opts()
t()

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

Link to this type

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

Link to this type

key() View Source 
key() :: Nebulex.Cache.key()

Link to this type

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

Link to this type

opts() View Source 
opts() :: Nebulex.Cache.opts()

Link to this type

t() View Source 
t() :: module()

Link to this section Callbacks

Link to this macrocallback

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

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

Link to this callback

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

Deletes a single object from cache.

See Nebulex.Cache.delete/2.

Link to this callback

expire(cache, key, ttl) View Source 
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.

Link to this callback

flush(cache) View Source 
flush(cache()) :: :ok

Flushes the cache.

See Nebulex.Cache.flush/0.

Link to this callback

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

Retrieves a single object from cache.

See Nebulex.Cache.get/2.

Link to this callback

get_many(cache, list, opts) View Source 
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.

Link to this callback

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

Returns whether the given key exists in cache.

See Nebulex.Cache.has_key?/1.

Link to this callback

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

Initializes the adapter supervision tree by returning the children

Link to this callback

object_info(cache, key, attr) View Source 
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.

Link to this callback

set(cache, object, opts) View Source 
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.

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, nil 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.

Link to this callback

set_many(cache, list, opts) View Source 
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.

Link to this callback

size(cache) View Source 
size(cache()) :: integer()

Returns the total number of cached entries.

See Nebulex.Cache.size/0.

Link to this callback

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

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

See Nebulex.Cache.take/2.

Link to this callback

update_counter(cache, key, incr, opts) View Source 
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.