# `Nebulex.Caching`
[🔗](https://github.com/elixir-nebulex/nebulex/blob/v3.1.0/lib/nebulex/caching.ex#L2)

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` (`t: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` (`t:atom/0`) - Defines the default cache for all decorated functions in the module.

* `:on_error` (`t: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` (`t: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` (`t: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` (`t: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"][shared_opts] section in the decorators module
for more information.

[shared_opts]: `m:Nebulex.Caching.Decorators#module-shared-options`

> #### `use Nebulex.Caching, opts` {: .info}
>
> 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:
>
> ```elixir
> use Nebulex.Caching, cache: MyCache
> ```
>
> and leave the `:cache` option out of the decorator declarations.

# `dynamic_cache`
*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` {: .info}
>
> `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"](`m:Nebulex.Caching.Decorators#module-cache-configuration`)
section in the `Nebulex.Caching.Decorators` module documentation for more
information.

# `keyref`
*macro* 

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

> #### Using `keyref` {: .info}
>
> `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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*