@spec build_keyref(Nebulex.Cache.t(), term()) :: keyref()

A convenience function for building a cache key reference when using the cacheable decorator. If you want to build an external reference, which is, referencing a key stored in an external cache, you have to provide the cache where the key is located to. The cache argument is optional, and by default is nil, which means, the referenced key is in the same cache provided via :key or :key_generator options (internal reference).

NOTE: In case you need to build a reference, consider using the macro Nebulex.Caching.keyref/2 instead.

See cacheable/3 decorator for more information about external references.

Examples

iex> Nebulex.Caching.Decorators.build_keyref("my-key")
{:"$nbx_cache_keyref", nil, "my-key"}
iex> Nebulex.Caching.Decorators.build_keyref(MyCache, "my-key")
{:"$nbx_cache_keyref", MyCache, "my-key"}

Provides a way of annotating functions to be evicted (eviction aspect).

On function's completion, the given key or keys (depends on the :key and :keys options) are deleted from the cache.

Options

• :keys - Defines the set of keys to be evicted from cache on function completion. It overrides :key and :key_generator options.

• :all_entries - Defines if all entries must be removed on function completion. Defaults to false.

• :before_invocation - Boolean to indicate whether the eviction should occur after (the default) or before the function executes. The former provides the same semantics as the rest of the annotations; once the function completes successfully, an action (in this case eviction) on the cache is executed. If the function does not execute (as it might be cached) or an exception is raised, the eviction does not occur. The latter (before_invocation: true) causes the eviction to occur always, before the function is invoked; this is useful in cases where the eviction does not need to be tied to the function outcome.

See the "Shared options" section at the module documentation.

Examples

defmodule MyApp.Example do
  use Nebulex.Caching

  alias MyApp.Cache

  @decorate cache_evict(cache: Cache, key: id)
  def delete(id) do
    # your logic (maybe write/delete data to the SoR)
  end

  @decorate cache_evict(cache: Cache, keys: [object.name, object.id])
  def delete_object(object) do
    # your logic (maybe write/delete data to the SoR)
  end

  @decorate cache_evict(cache: Cache, all_entries: true)
  def delete_all do
    # your logic (maybe write/delete data to the SoR)
  end
end

The Write-through pattern is supported by this decorator. Your function provides the logic to write data to the system-of-record (SoR) and the rest is provided by the decorator under-the-hood. But in contrast with update decorator, when the data is written to the SoR, the key for that value is deleted from cache instead of updated.

Provides a way of annotating functions to be evicted; but updating the cached key instead of deleting it.

The content of the cache is updated without interfering with the function execution. That is, the method would always be executed and the result cached.

The difference between cacheable/3 and cache_put/3 is that cacheable/3 will skip running the function if the key exists in the cache, whereas cache_put/3 will actually run the function and then put the result in the cache.

Options

• :keys - The set of cached keys to be updated with the returned value on function completion. It overrides :key and :key_generator options.

See the "Shared options" section at the module documentation.

Examples

defmodule MyApp.Example do
  use Nebulex.Caching

  alias MyApp.Cache

  @ttl :timer.hours(1)

  @decorate cache_put(cache: Cache, key: id, opts: [ttl: @ttl])
  def update!(id, attrs \\ %{}) do
    # your logic (maybe write data to the SoR)
  end

  @decorate cache_put(
              cache: Cache,
              key: id,
              match: &match_fun/1,
              opts: [ttl: @ttl]
            )
  def update(id, attrs \\ %{}) do
    # your logic (maybe write data to the SoR)
  end

  @decorate cache_put(
              cache: Cache,
              keys: [object.name, object.id],
              match: &match_fun/1,
              opts: [ttl: @ttl]
            )
  def update_object(object) do
    # your logic (maybe write data to the SoR)
  end

  defp match_fun({:ok, updated}), do: {true, updated}
  defp match_fun({:error, _}), do: false
end

The Write-through pattern is supported by this decorator. Your function provides the logic to write data to the system-of-record (SoR) and the rest is provided by the decorator under-the-hood.

@spec cache_put(module(), {:"$keys", term()} | term(), term(), Keyword.t()) :: :ok

Convenience function for cache_put annotation.

NOTE: For internal purposes only.

Provides a way of annotating functions to be cached (cacheable aspect).

The returned value by the code block is cached if it doesn't exist already in cache, otherwise, it is returned directly from cache and the code block is not executed.

Options

• :references - (Optional) (references/0) Indicates the key given by the option :key references another key given by the option :references. In other words, when it is present, this option tells the cacheable decorator to store the function's block result under the referenced key given by the option :references, and the referenced key under the key given by the option :key. The value could be:

  • nil - (Default) It is ignored (no key references).

  • (term -> keyref | term) - An anonymous function receiving the result of the function's code block evaluation and must return the referenced key. There is also a special type of return in case you want to reference a key located in an external/different cache than the one defined with the options :key or :key_generator. In this scenario, you must return a special type keyref/0, which can be build with the macro keyref/2. See the "External referenced keys" section below.

  • any - It could be an explicit term or value, for example, a fixed value or a function argument.

  See the "Referenced keys" section for more information.

See the "Shared options" section at the module documentation.

Examples

defmodule MyApp.Example do
  use Nebulex.Caching

  alias MyApp.Cache

  @ttl :timer.hours(1)

  @decorate cacheable(cache: Cache, key: id, opts: [ttl: @ttl])
  def get_by_id(id) do
    # your logic (maybe the loader to retrieve the value from the SoR)
  end

  @decorate cacheable(cache: Cache, key: email, references: & &1.id)
  def get_by_email(email) do
    # your logic (maybe the loader to retrieve the value from the SoR)
  end

  @decorate cacheable(cache: Cache, key: clauses, match: &match_fun/1)
  def all(clauses) do
    # your logic (maybe the loader to retrieve the value from the SoR)
  end

  defp match_fun([]), do: false
  defp match_fun(_), do: true
end

The Read-through pattern is supported by this decorator. The loader to retrieve the value from the system-of-record (SoR) is your function's logic and the rest is provided by the macro under-the-hood.

Referenced keys

Referenced keys are particularly useful when you have multiple different keys keeping the same value. For example, let's imagine we have an schema User with more than one unique field, like :id, :email, and :token. We may have a module with functions retrieving the user account by any of those fields, like so:

defmodule MyApp.UserAccounts do
  use Nebulex.Caching

  alias MyApp.Cache

  @decorate cacheable(cache: Cache, key: id)
  def get_user_account(id) do
    # your logic ...
  end

  @decorate cacheable(cache: Cache, key: email)
  def get_user_account_by_email(email) do
    # your logic ...
  end

  @decorate cacheable(cache: Cache, key: token)
  def get_user_account_by_token(token) do
    # your logic ...
  end

  @decorate cache_evict(
              cache: Cache,
              keys: [user.id, user.email, user.token]
            )
  def update_user_account(user) do
    # your logic ...
  end
end

As you notice, all the three functions will end up storing the same user record under a different key. This is not very efficient in terms of memory space, is it? Besides, when the user record is updated, we have to invalidate the previously cached entries, which means, we have to specify in the cache_evict decorator all the different keys the user account has ben cached under.

By means of the referenced keys, we can address it in a better and simpler way. The module will look like this:

defmodule MyApp.UserAccounts do
  use Nebulex.Caching

  alias MyApp.Cache

  @decorate cacheable(cache: Cache, key: id)
  def get_user_account(id) do
    # your logic ...
  end

  @decorate cacheable(cache: Cache, key: email, references: & &1.id)
  def get_user_account_by_email(email) do
    # your logic ...
  end

  @decorate cacheable(cache: Cache, key: token, references: & &1.id)
  def get_user_account_by_token(token) do
    # your logic ...
  end

  @decorate cache_evict(cache: Cache, key: user.id)
  def update_user_account(user) do
    # your logic ...
  end
end

With the option :references we are indicating to the cacheable decorator to store the user id (& &1.id - assuming the function returns an user record) under the key email and the key token, and the user record itself under the user id, which is the referenced key. This time, instead of storing the same object three times, it will be stored only once under the user id, and the other entries will just keep a reference to it. When the functions get_user_account_by_email/1 or get_user_account_by_token/1 are executed, the decorator will automatically handle it; under-the-hood, it will fetch the referenced key given by email or token first, and then get the user record under the referenced key.

On the other hand, in the eviction function update_user_account/1, since the user record is stored only once under the user's ID, we could set the option :key to the user's ID, without specifying multiple keys like in the previous case. However, there is a caveat: "the cache_evict decorator doesn't evict the references automatically". See the "CAVEATS" section below.

External referenced keys

Previously, we saw how to work with referenced keys but on the same cache, like "internal references." Despite this being the typical case scenario, there could be situations where you may want to reference a key stored in a different or external cache. Why would I want to reference a key located in a separate cache? There may be multiple reasons, but let's give a few examples.

• One example is when you have a Redis cache; in such case, you likely want to optimize the calls to Redis as much as possible. Therefore, you should store the referenced keys in a local cache and the values in Redis. This way, we only hit Redis to access the keys with the actual values, and the decorator resolves the referenced keys locally.

• Another example is for keeping the cache key references isolated, preferably locally. Then, apply a different eviction (or garbage collection) policy for the references; one may want to expire the references more often to avoid having dangling keys since the cache_evict decorator doesn't remove the references automatically, just the defined key (or keys). See the "CAVEATS" section below.

Let us modify the previous "user accounts" example based on the Redis scenario:

defmodule MyApp.UserAccounts do
  use Nebulex.Caching

  alias MyApp.{LocalCache, RedisCache}

  @decorate cacheable(cache: RedisCache, key: id)
  def get_user_account(id) do
    # your logic ...
  end

  @decorate cacheable(
              cache: LocalCache,
              key: email,
              references: &keyref(RedisCache, &1.id)
            )
  def get_user_account_by_email(email) do
    # your logic ...
  end

  @decorate cacheable(
              cache: LocalCache,
              key: token,
              references: &keyref(RedisCache, &1.id)
            )
  def get_user_account_by_token(token) do
    # your logic ...
  end

  @decorate cache_evict(cache: RedisCache, key: user.id)
  def update_user_account(user) do
    # your logic ...
  end
end

The functions get_user_account/1 and update_user_account/2 use RedisCache to store the real value in Redis while get_user_account_by_email/1 and get_user_account_by_token/1 use LocalCache to store the referenced keys. Then, with the option references: &keyref(RedisCache, &1.id) we are telling the cacheable decorator the referenced key given by &1.id is located in the cache RedisCache; underneath, the macro keyref/2 builds the special return type for the external cache reference.

CAVEATS

• When the cache_evict decorator annotates a key (or keys) to evict, the decorator removes only the entry associated with that key. Therefore, if the key has references, those are not automatically removed, which means dangling keys. However, there are multiple ways to address dangling keys (or references):

  • The first (and the simplest) sets a TTL to the reference. For example: cacheable(key: name, references: & &1.id, opts: [ttl: @ttl]). You can also specify a different TTL for the referenced key: references: &keyref(&1.id, ttl: @another_ttl).

  • The second alternative, perhaps the most recommended, is having a separate cache to keep the references (e.g., a cache using the local adapter). This way, you could provide a different eviction or GC configuration to run the GC more often and keep the references cache clean. See "External referenced keys".

  • The third alternative uses the :keys option for specifying a key and its references. For example, if you have @decorate cacheable(key: email, references: & &1.id), the eviction may look like this @decorate cache_evict(keys: [user.id, user.email]). This one is perhaps the least ideal option because it is cumbersome; you have to know and specify the key and all its references, and at the same time, you will need to have access to the key and references in the arguments, which sometimes is not possible because you may receive only the ID, but not the email.

@spec eval_cacheable(
  module(),
  term(),
  references(),
  Keyword.t(),
  on_error_opt(),
  match_fun(),
  (-> term())
) :: term()

Convenience function for evaluating the cacheable decorator in runtime.

NOTE: For internal purposes only.

@spec eval_match(term(), match_fun(), module(), term(), Keyword.t()) :: boolean()

Convenience function for evaluating the :match function in runtime.

NOTE: For internal purposes only.

NOTE: Workaround to avoid dialyzer warnings when using declarative annotation-based caching via decorators.

@spec run_cmd(module(), atom(), [term()], on_error_opt(), term()) :: term()

Convenience function for ignoring cache errors when :on_error option is set to :nothing

NOTE: For internal purposes only.