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

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 the 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` (`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 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:
>
> ```elixir
> use Nebulex.Caching, cache: MyCache
> ```
>
> Therefore, you don't need to provide the `:cache` option at the decorator
> level.

# `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}
>
> 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`
*macro* 

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

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

---

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