Nebulex.Caching (Nebulex v3.0.0-rc.1)

View Source

At its core, the abstraction applies caching to Elixir functions, reducing thus the number of executions based on the information available in the cache. That is, each time a targeted function is invoked, the abstraction will apply a caching behavior checking whether the function has been already executed and its result cached for the given arguments. If it has, then the cached result is returned without having to execute the actual function; if it has not, then function is executed, the result cached and returned to the user so that, the next time the method is invoked, the cached result is returned. This way, expensive functions (whether CPU or IO bound) can be executed only once for a given set of parameters and the result reused without having to actually execute the function again. The caching logic is applied transparently without any interference to the invoker.

See Nebulex.Caching.Decorators to learn more about the caching decorators and their usage.

Compilation time options

The following are the available compilation time options when defining the caching usage via use Nebulex.Caching:

  • :default_key_generator (Nebulex.Caching.Decorators.key/0) - Defines the default key generation function for all decorated functions in the module. It can be overridden at the decorator level via :key option.

    The function must be provided in the format &Mod.fun/arity.

    The default value is &Nebulex.Caching.Decorators.generate_key/1.

  • :cache (atom/0) - Defines the cache for all decorated functions in the module. It can be overridden at the decorator level.

  • :on_error (Nebulex.Caching.Decorators.on_error/0) - Whether to raise an exception or do nothing when there is a cache error. It applies to all decorated functions in the module. It can be overridden at the decorator level. The default value is :nothing.

  • :match (Nebulex.Caching.Decorators.match/0) - The match function for all decorated functions in the module. It can be overridden at the decorator level.

    The function must be provided in the format &Mod.fun/arity.

    The default value is &Nebulex.Caching.Decorators.default_match/1.

  • :opts (keyword/0) - The options to use globally for all decorated functions in the module when invoking cache commands. The default value is [].

See the "Shared Options" section in the decorators module for more information.

use Nebulex.Caching, opts

These options apply to all decorated functions in a module, but each decorator declaration can overwrite them. They act as a global or default configuration for the decorators. For example, if the cache is the same for all decorated functions in a module, one can configure it globally like this:

use Nebulex.Caching, cache: MyCache

Therefore, you don't need to provide the :cache option at the decorator level.

Summary

Functions

Creates a dynamic cache tuple form to use in the decorated function (wrapper macro for Nebulex.Caching.Decorators.dynamic_cache_spec/2).

Creates a reference tuple form to use in the decorated function (wrapper macro for Nebulex.Caching.Decorators.keyref_spec/3).

Functions

dynamic_cache(cache, name)

(macro)

Creates a dynamic cache tuple form to use in the decorated function (wrapper macro for Nebulex.Caching.Decorators.dynamic_cache_spec/2).

The first argument, cache, specifies the defined cache module, and the second argument, name, is the actual name of the cache.

Using dynamic_cache

This macro is automatically imported and then available when using use Nebulex.Caching.

Example

defmodule MyApp.Users do
  use Nebulex.Caching

  @decorate cacheable(cache: dynamic_cache(MyApp.Cache, :users))
  def get_user(id) do
    # your logic ...
  end
end

See the ":cache option" section in the Nebulex.Caching.Decorators module documentation for more information.

keyref(key, opts \\ [])

(macro)

Creates a reference tuple form to use in the decorated function (wrapper macro for Nebulex.Caching.Decorators.keyref_spec/3).

Using keyref

This macro is automatically imported and then available when using use Nebulex.Caching.

Options

  • :cache - The cache where the referenced key is stored.

  • :ttl - The TTL for the referenced key. If configured, it overrides the TTL given in the decorator's option :opts.

See Nebulex.Caching.Decorators.cacheable/3 decorator for more information.