Nebulex.Caching (Nebulex v3.1.0)

Copy Markdown View Source

Applies caching to Elixir functions so they run fewer times. Each time a decorated function is called, the decorator checks whether a result for the given arguments is already in the cache. If it is, the cached result is returned and the function body is skipped. If it is not, the function runs, its result is stored in the cache, and the next call with the same arguments gets the cached result. An expensive function (CPU or IO bound) therefore runs once per set of arguments. The caller does not see any of this; it calls the function as usual.

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. This can be overridden at the decorator level using the :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 default cache for all decorated functions in the module.

  • :on_error (Nebulex.Caching.Decorators.on_error/0) - Defines the default error handling behavior for all decorated functions in the module when a cache error occurs. The default value is :nothing.

  • :transaction (boolean/0) - Defines the default transaction behavior for all decorated functions in the module. When set to true, decorators wrap the function execution and cache operations in a transaction. The default value is false.

  • :match (Nebulex.Caching.Decorators.match/0) - Defines the default match function for all decorated functions in the module.

    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 default 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 are defaults for all decorated functions in the module; each decorator declaration can override them. For example, if every decorated function in a module uses the same cache, set it once:

use Nebulex.Caching, cache: MyCache

and leave the :cache option out of the decorator declarations.

Summary

Functions

dynamic_cache(cache, name)

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

keyref(key, opts \\ [])

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

use Nebulex.Caching imports this macro, so it is available in the module without further setup.

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 configuration" 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

use Nebulex.Caching imports this macro, so it is available in the module without further setup.

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.