cache.ex

defmodule Nebulex.Cache do
  @moduledoc """
  Cache's main interface; defines the cache abstraction layer which is
  highly inspired by [Ecto](https://github.com/elixir-ecto/ecto).

  A Cache maps to an underlying implementation, controlled by the
  adapter. For example, Nebulex ships with a default adapter that
  implements a local generational cache.

  When used, the Cache expects the `:otp_app` and `:adapter` as options.
  The `:otp_app` should point to an OTP application that has the cache
  configuration. For example, the Cache:

      defmodule MyApp.Cache do
        use Nebulex.Cache,
          otp_app: :my_app,
          adapter: Nebulex.Adapters.Local
      end

  Could be configured with:

      config :my_app, MyApp.Cache,
        backend: :shards,
        gc_interval: :timer.hours(12),
        max_size: 1_000_000,
        allocated_memory: 2_000_000_000,
        gc_cleanup_min_timeout: :timer.seconds(10),
        gc_cleanup_max_timeout: :timer.minutes(10)

  Most of the configuration that goes into the `config` is specific
  to the adapter. For this particular example, you can check
  [`Nebulex.Adapters.Local`](https://hexdocs.pm/nebulex/Nebulex.Adapters.Local.html)
  for more information. In spite of this, the following configuration values
  are shared across all adapters:

    * `:name` - The name of the Cache supervisor process.

    * `:telemetry_prefix` - It is recommend for adapters to publish events
      using the `Telemetry` library. By default, the telemetry prefix is based
      on the module name, so if your module is called `MyApp.Cache`, the prefix
      will be `[:my_app, :cache]`. See the "Telemetry events" section to see
      what events recommended for the  adapters to publish.. Note that if you
      have multiple caches, you should keep the `:telemetry_prefix` consistent
      for each of them and use the `:cache` and/or `:name` (in case of a named
      or dynamic cache) properties in the event metadata for distinguishing
      between caches.

    * `:telemetry` - An optional flag to tell the adapters whether Telemetry
      events should be emitted or not. Defaults to `true`.

    * `:stats` - Boolean to define whether or not the cache will provide stats.
      Defaults to `false`. Each adapter is responsible for providing stats by
      implementing `Nebulex.Adapter.Stats` behaviour. See the "Stats" section
      below.

  ## Telemetry events

  Similar to Ecto or Phoenix, Nebulex also provides built-in Telemetry events
  applied to all caches, and cache adapter-specific events.

  ### Nebulex built-in events

  The following events are emitted by all Nebulex caches:

    * `[:nebulex, :cache, :init]` - it is dispatched whenever a cache starts.
      The measurement is a single `system_time` entry in native unit. The
      metadata is the `:cache` and all initialization options under `:opts`.

  ### Adapter-specific events

  It is recommend the adapters to publish certain `Telemetry` events listed
  below. Those events will use the `:telemetry_prefix` outlined above which
  defaults to `[:my_app, :cache]`.

  For instance, to receive all events published by a cache called `MyApp.Cache`,
  one could define a module:

      defmodule MyApp.Telemetry do
        def handle_event(
              [:my_app, :cache, :command, event],
              measurements,
              metadata,
              config
            ) do
          case event do
            :start ->
              # Handle start event ...

            :stop ->
              # Handle stop event ...

            :exception ->
              # Handle exception event ...
          end
        end
      end

  Then, in the `Application.start/2` callback, attach the handler to this event
  using a unique handler id:

      :telemetry.attach(
        "my-app-handler-id",
        [:my_app, :cache, :command],
        &MyApp.Telemetry.handle_event/4,
        %{}
      )

  See [the telemetry documentation](https://hexdocs.pm/telemetry/)
  for more information.

  The following are the events you should expect from Nebulex. All examples
  below consider a cache named `MyApp.Cache`:

  #### `[:my_app, :cache, :command, :start]`

  This event should be invoked on every cache call sent to the adapter before
  the command logic is executed.

  The `:measurements` map will include the following:

    * `:system_time` - The current system time in native units from calling:
      `System.system_time()`.

  A Telemetry `:metadata` map including the following fields. Each cache adapter
  may emit different information here. For built-in adapters, it will contain:

    * `:adapter_meta` - The adapter metadata.
    * `:function_name` - The name of the invoked adapter function.
    * `:args` - The arguments of the invoked adapter function, omitting the
      first argument, since it is the adapter metadata already included into
      the event's metadata.

  #### `[:my_app, :cache, :command, :stop]`

  This event should be invoked on every cache call sent to the adapter after
  the command logic is executed.

  The `:measurements` map will include the following:

    * `:duration` - The time spent executing the cache command. The measurement
      is given in the `:native` time unit. You can read more about it in the
      docs for `System.convert_time_unit/3`.

  A Telemetry `:metadata` map including the following fields. Each cache adapter
  may emit different information here. For built-in adapters, it will contain:

    * `:adapter_meta` - The adapter metadata.
    * `:function_name` - The name of the invoked adapter function.
    * `:args` - The arguments of the invoked adapter function, omitting the
      first argument, since it is the adapter metadata already included into
      the event's metadata.
    * `:result` - The command result.

  #### `[:my_app, :cache, :command, :exception]`

  This event should be invoked when an error or exception occurs while executing
  the cache command.

  The `:measurements` map will include the following:

    * `:duration` - The time spent executing the cache command. The measurement
      is given in the `:native` time unit. You can read more about it in the
      docs for `System.convert_time_unit/3`.

  A Telemetry `:metadata` map including the following fields. Each cache adapter
  may emit different information here. For built-in adapters, it will contain:

    * `:adapter_meta` - The adapter metadata.
    * `:function_name` - The name of the invoked adapter function.
    * `:args` - The arguments of the invoked adapter function, omitting the
      first argument, since it is the adapter metadata already included into
      the event's metadata.
    * `:kind` - The type of the error: `:error`, `:exit`, or `:throw`.
    * `:reason` - The reason of the error.
    * `:stacktrace` - The stacktrace.

  **NOTE:** The events outlined above are the recommended for the adapters
  to dispatch. However, it is highly recommended to review the used adapter
  documentation to ensure it is fully compatible with these events, perhaps
  differences, or perhaps also additional events.

  ## Stats

  Stats are provided by the adapters by implementing the optional behaviour
  `Nebulex.Adapter.Stats`. This behaviour exposes a callback to return the
  current cache stats.  Nevertheless, the behaviour brings with a default
  implementation using [Erlang counters][counters], which is used by the
  local built-in adapter (`Nebulex.Adapters.Local`).

  [counters]: https://erlang.org/doc/man/counters.html

  One can enable the stats by setting the option `:stats` to `true`.
  For example, in the configuration file:

      config :my_app, MyApp.Cache,
        stats: true,
        ...

  > Remember to check if the underlying adapter implements the
    `Nebulex.Adapter.Stats` behaviour.

  See `c:Nebulex.Cache.stats/0` for more information.

  ## Dispatching stats via Telemetry

  It is possible to emit Telemetry events for the current stats via
  `c:Nebulex.Cache.dispatch_stats/1`, but it has to be invoked explicitly;
  Nebulex does not emit this Telemetry event automatically. But it is very
  easy to emit this event using [`:telemetry_poller`][telemetry_poller].

  [telemetry_poller]: https://github.com/beam-telemetry/telemetry_poller

  For example, one can define a custom pollable measurement:

      :telemetry_poller.start_link(
        measurements: [
          {MyApp.Cache, :dispatch_stats, []},
        ],
        # configure sampling period - default is :timer.seconds(5)
        period: :timer.seconds(30),
        name: :my_cache_stats_poller
      )

  Or you can also start the `:telemetry_poller` process along with your
  application supervision tree:

      def start(_type, _args) do
        my_cache_stats_poller_opts = [
          measurements: [
            {MyApp.Cache, :dispatch_stats, []},
          ],
          period: :timer.seconds(30),
          name: :my_cache_stats_poller
        ]

        children = [
          {MyApp.Cache, []},
          {:telemetry_poller, my_cache_stats_poller_opts}
        ]

        opts = [strategy: :one_for_one, name: MyApp.Supervisor]
        Supervisor.start_link(children, opts)
      end

  See [Nebulex Telemetry Guide](http://hexdocs.pm/nebulex/telemetry.html)
  for more information.

  ## Distributed topologies

  Nebulex provides the following adapters for distributed topologies:

    * `Nebulex.Adapters.Partitioned` - Partitioned cache topology.
    * `Nebulex.Adapters.Replicated` - Replicated cache topology.
    * `Nebulex.Adapters.Multilevel` - Multi-level distributed cache topology.

  These adapters work more as wrappers for an existing local adapter and provide
  the distributed topology on top of it. Optionally, you can set the adapter for
  the primary cache storage with the option `:primary_storage_adapter`. Defaults
  to `Nebulex.Adapters.Local`.
  """

  @type t :: module

  @typedoc "Cache entry key"
  @type key :: any

  @typedoc "Cache entry value"
  @type value :: any

  @typedoc "Cache entries"
  @type entries :: map | [{key, value}]

  @typedoc "Cache action options"
  @type opts :: Keyword.t()

  @doc false
  defmacro __using__(opts) do
    quote bind_quoted: [opts: opts] do
      @behaviour Nebulex.Cache

      alias Nebulex.Cache.{
        Entry,
        Persistence,
        Queryable,
        Stats,
        Storage,
        Transaction
      }

      alias Nebulex.Hook

      {otp_app, adapter, behaviours} = Nebulex.Cache.Supervisor.compile_config(opts)

      @otp_app otp_app
      @adapter adapter
      @opts opts
      @default_dynamic_cache opts[:default_dynamic_cache] || __MODULE__
      @default_key_generator opts[:default_key_generator] || Nebulex.Caching.SimpleKeyGenerator
      @before_compile adapter

      ## Config and metadata

      @impl true
      def config do
        {:ok, config} = Nebulex.Cache.Supervisor.runtime_config(__MODULE__, @otp_app, [])
        config
      end

      @impl true
      def __adapter__, do: @adapter

      @impl true
      def __default_key_generator__, do: @default_key_generator

      ## Process lifecycle

      @doc false
      def child_spec(opts) do
        %{
          id: __MODULE__,
          start: {__MODULE__, :start_link, [opts]},
          type: :supervisor
        }
      end

      @impl true
      def start_link(opts \\ []) do
        Nebulex.Cache.Supervisor.start_link(__MODULE__, @otp_app, @adapter, opts)
      end

      @impl true
      def stop(timeout \\ 5000) do
        Supervisor.stop(get_dynamic_cache(), :normal, timeout)
      end

      @compile {:inline, get_dynamic_cache: 0}

      @impl true
      def get_dynamic_cache do
        Process.get({__MODULE__, :dynamic_cache}, @default_dynamic_cache)
      end

      @impl true
      def put_dynamic_cache(dynamic) when is_atom(dynamic) or is_pid(dynamic) do
        Process.put({__MODULE__, :dynamic_cache}, dynamic) || @default_dynamic_cache
      end

      @impl true
      def with_dynamic_cache(name, fun) do
        default_dynamic_cache = get_dynamic_cache()

        try do
          _ = put_dynamic_cache(name)
          fun.()
        after
          _ = put_dynamic_cache(default_dynamic_cache)
        end
      end

      @impl true
      def with_dynamic_cache(name, module, fun, args) do
        with_dynamic_cache(name, fn -> apply(module, fun, args) end)
      end

      ## Entry

      @impl true
      def get(key, opts \\ []) do
        Entry.get(get_dynamic_cache(), key, opts)
      end

      @impl true
      def get!(key, opts \\ []) do
        Entry.get!(get_dynamic_cache(), key, opts)
      end

      @impl true
      def get_all(keys, opts \\ []) do
        Entry.get_all(get_dynamic_cache(), keys, opts)
      end

      @impl true
      def put(key, value, opts \\ []) do
        Entry.put(get_dynamic_cache(), key, value, opts)
      end

      @impl true
      def put_new(key, value, opts \\ []) do
        Entry.put_new(get_dynamic_cache(), key, value, opts)
      end

      @impl true
      def put_new!(key, value, opts \\ []) do
        Entry.put_new!(get_dynamic_cache(), key, value, opts)
      end

      @impl true
      def replace(key, value, opts \\ []) do
        Entry.replace(get_dynamic_cache(), key, value, opts)
      end

      @impl true
      def replace!(key, value, opts \\ []) do
        Entry.replace!(get_dynamic_cache(), key, value, opts)
      end

      @impl true
      def put_all(entries, opts \\ []) do
        Entry.put_all(get_dynamic_cache(), entries, opts)
      end

      @impl true
      def put_new_all(entries, opts \\ []) do
        Entry.put_new_all(get_dynamic_cache(), entries, opts)
      end

      @impl true
      def delete(key, opts \\ []) do
        Entry.delete(get_dynamic_cache(), key, opts)
      end

      @impl true
      def take(key, opts \\ []) do
        Entry.take(get_dynamic_cache(), key, opts)
      end

      @impl true
      def take!(key, opts \\ []) do
        Entry.take!(get_dynamic_cache(), key, opts)
      end

      @impl true
      def has_key?(key) do
        Entry.has_key?(get_dynamic_cache(), key)
      end

      @impl true
      def get_and_update(key, fun, opts \\ []) do
        Entry.get_and_update(get_dynamic_cache(), key, fun, opts)
      end

      @impl true
      def update(key, initial, fun, opts \\ []) do
        Entry.update(get_dynamic_cache(), key, initial, fun, opts)
      end

      @impl true
      def incr(key, amount \\ 1, opts \\ []) do
        Entry.incr(get_dynamic_cache(), key, amount, opts)
      end

      @impl true
      def decr(key, amount \\ 1, opts \\ []) do
        Entry.decr(get_dynamic_cache(), key, amount, opts)
      end

      @impl true
      def ttl(key) do
        Entry.ttl(get_dynamic_cache(), key)
      end

      @impl true
      def expire(key, ttl) do
        Entry.expire(get_dynamic_cache(), key, ttl)
      end

      @impl true
      def touch(key) do
        Entry.touch(get_dynamic_cache(), key)
      end

      ## Queryable

      if Nebulex.Adapter.Queryable in behaviours do
        @impl true
        def all(query \\ nil, opts \\ []) do
          Queryable.all(get_dynamic_cache(), query, opts)
        end

        @impl true
        def count_all(query \\ nil, opts \\ []) do
          Queryable.count_all(get_dynamic_cache(), query, opts)
        end

        @impl true
        def delete_all(query \\ nil, opts \\ []) do
          Queryable.delete_all(get_dynamic_cache(), query, opts)
        end

        @impl true
        def stream(query \\ nil, opts \\ []) do
          Queryable.stream(get_dynamic_cache(), query, opts)
        end

        ## Deprecated functions (for backwards compatibility)

        @impl true
        defdelegate size, to: __MODULE__, as: :count_all

        @impl true
        defdelegate flush, to: __MODULE__, as: :delete_all
      end

      ## Persistence

      if Nebulex.Adapter.Persistence in behaviours do
        @impl true
        def dump(path, opts \\ []) do
          Persistence.dump(get_dynamic_cache(), path, opts)
        end

        @impl true
        def load(path, opts \\ []) do
          Persistence.load(get_dynamic_cache(), path, opts)
        end
      end

      ## Transactions

      if Nebulex.Adapter.Transaction in behaviours do
        @impl true
        def transaction(opts \\ [], fun) do
          Transaction.transaction(get_dynamic_cache(), opts, fun)
        end

        @impl true
        def in_transaction? do
          Transaction.in_transaction?(get_dynamic_cache())
        end
      end

      ## Stats

      if Nebulex.Adapter.Stats in behaviours do
        @impl true
        def stats do
          Stats.stats(get_dynamic_cache())
        end

        @impl true
        def dispatch_stats(opts \\ []) do
          Stats.dispatch_stats(get_dynamic_cache(), opts)
        end
      end
    end
  end

  ## User callbacks

  @optional_callbacks init: 1

  @doc """
  A callback executed when the cache starts or when configuration is read.
  """
  @callback init(config :: Keyword.t()) :: {:ok, Keyword.t()} | :ignore

  ## Nebulex.Adapter

  @doc """
  Returns the adapter tied to the cache.
  """
  @callback __adapter__ :: Nebulex.Adapter.t()

  @doc """
  Returns the default key generator applied only when using
  **"declarative annotation-based caching"** via `Nebulex.Caching.Decorators`.

  Sometimes you may want to set a different key generator when using
  declarative caching. By default, the key generator is set to
  `Nebulex.Caching.SimpleKeyGenerator`. You can change the default
  key generator at compile time with:

      use Nebulex.Cache, default_key_generator: MyKeyGenerator

  See `Nebulex.Caching.Decorators` and `Nebulex.Caching.KeyGenerator`
  for more information.
  """
  @callback __default_key_generator__ :: Nebulex.Caching.KeyGenerator.t()

  @doc """
  Returns the adapter configuration stored in the `:otp_app` environment.

  If the `c:init/1` callback is implemented in the cache, it will be invoked.
  """
  @callback config() :: Keyword.t()

  @doc """
  Starts a supervision and return `{:ok, pid}` or just `:ok` if nothing
  needs to be done.

  Returns `{:error, {:already_started, pid}}` if the cache is already
  started or `{:error, term}` in case anything else goes wrong.

  ## Options

  See the configuration in the moduledoc for options shared between adapters,
  for adapter-specific configuration see the adapter's documentation.
  """
  @callback start_link(opts) ::
              {:ok, pid}
              | {:error, {:already_started, pid}}
              | {:error, term}

  @doc """
  Shuts down the cache.
  """
  @callback stop(timeout) :: :ok

  @doc """
  Returns the atom name or pid of the current cache
  (based on Ecto dynamic repo).

  See also `c:put_dynamic_cache/1`.
  """
  @callback get_dynamic_cache() :: atom() | pid()

  @doc """
  Sets the dynamic cache to be used in further commands
  (based on Ecto dynamic repo).

  There might be cases where we want to have different cache instances but
  accessing them through the same cache module. By default, when you call
  `MyApp.Cache.start_link/1`, it will start a cache with the name
  `MyApp.Cache`. But it is also possible to start multiple caches by using
  a different name for each of them:

      MyApp.Cache.start_link(name: :cache1)
      MyApp.Cache.start_link(name: :cache2, backend: :shards)

  You can also start caches without names by explicitly setting the name
  to `nil`:

      MyApp.Cache.start_link(name: nil, backend: :shards)

  > **NOTE:** There may be adapters requiring the `:name` option anyway,
    therefore, it is highly recommended to see the adapter's documentation
    you want to use.

  However, once the cache is started, it is not possible to interact directly
  with it, since all operations through `MyApp.Cache` are sent by default to
  the cache named `MyApp.Cache`. But you can change the default cache at
  compile-time:

      use Nebulex.Cache, default_dynamic_cache: :cache_name

  Or anytime at runtime by calling `put_dynamic_cache/1`:

      MyApp.Cache.put_dynamic_cache(:another_cache_name)

  From this moment on, all future commands performed by the current process
  will run on `:another_cache_name`.
  """
  @callback put_dynamic_cache(atom() | pid()) :: atom() | pid()

  @doc """
  Invokes the given function `fun` for the dynamic cache `name_or_pid`.

  ## Example

      MyCache.with_dynamic_cache(:my_cache, fn ->
        MyCache.put("foo", "var")
      end)

  See `c:get_dynamic_cache/0` and `c:put_dynamic_cache/1`.
  """
  @callback with_dynamic_cache(name_or_pid :: atom() | pid(), fun) :: term

  @doc """
  For the dynamic cache `name_or_pid`, invokes the given function name `fun`
  from `module` with the list of arguments `args`.

  ## Example

      MyCache.with_dynamic_cache(:my_cache, Module, :some_fun, ["foo", "bar"])

  See `c:get_dynamic_cache/0` and `c:put_dynamic_cache/1`.
  """
  @callback with_dynamic_cache(
              name_or_pid :: atom() | pid(),
              module,
              fun :: atom,
              args :: [term]
            ) :: term

  ## Nebulex.Adapter.Entry

  @doc """
  Gets a value from Cache where the key matches the given `key`.

  Returns `nil` if no result was found.

  See the configured adapter documentation for runtime options.

  ## Example

      iex> MyCache.put("foo", "bar")
      :ok

      iex>  MyCache.get("foo")
      "bar"

      iex> MyCache.get(:non_existent_key)
      nil

  """
  @callback get(key, opts) :: value

  @doc """
  Similar to `c:get/2` but raises `KeyError` if `key` is not found.

  See the configured adapter documentation for runtime options.

  ## Example

      MyCache.get!(:a)

  """
  @callback get!(key, opts) :: value

  @doc """
  Returns a `map` with all the key-value pairs in the Cache where the key
  is in `keys`.

  If `keys` contains keys that are not in the Cache, they're simply ignored.

  See the configured adapter documentation for runtime options.

  ## Example

      iex> MyCache.put_all([a: 1, c: 3])
      :ok

      iex> MyCache.get_all([:a, :b, :c])
      %{a: 1, c: 3}

  """
  @callback get_all(keys :: [key], opts) :: map

  @doc """
  Puts the given `value` under `key` into the Cache.

  If `key` already holds an entry, it is overwritten. Any previous
  time to live associated with the key is discarded on successful
  `put` operation.

  By default, `nil` values are skipped, which means they are not stored;
  the call to the adapter is bypassed.

  ## Options

    * `:ttl` - (positive integer or `:infinity`) Defines the time-to-live
      (or expiry time) for the given key  in **milliseconds**. Defaults
      to `:infinity`.

  See the configured adapter documentation for more runtime options.

  ## Example

      iex> MyCache.put("foo", "bar")
      :ok

  If the value is nil, then it is not stored (operation is skipped):

      iex> MyCache.put("foo", nil)
      :ok

  Put key with time-to-live:

      iex> MyCache.put("foo", "bar", ttl: 10_000)
      :ok

  Using Nebulex.Time for TTL:

      iex> MyCache.put("foo", "bar", ttl: :timer.hours(1))
      :ok

      iex> MyCache.put("foo", "bar", ttl: :timer.minutes(1))
      :ok

      iex> MyCache.put("foo", "bar", ttl: :timer.seconds(1))
      :ok

  """
  @callback put(key, value, opts) :: :ok

  @doc """
  Puts the given `entries` (key/value pairs) into the Cache. It replaces
  existing values with new values (just as regular `put`).

  ## Options

    * `:ttl` - (positive integer or `:infinity`) Defines the time-to-live
      (or expiry time) for the given key  in **milliseconds**. Defaults
      to `:infinity`.

  See the configured adapter documentation for more runtime options.

  ## Example

      iex> MyCache.put_all(apples: 3, bananas: 1)
      :ok

      iex> MyCache.put_all(%{apples: 2, oranges: 1}, ttl: 10_000)
      :ok

  Ideally, this operation should be atomic, so all given keys are put at once.
  But it depends purely on the adapter's implementation and the backend used
  internally by the adapter. Hence, it is recommended to review the adapter's
  documentation.
  """
  @callback put_all(entries, opts) :: :ok

  @doc """
  Puts the given `value` under `key` into the cache, only if it does not
  already exist.

  Returns `true` if a value was set, otherwise, `false` is returned.

  By default, `nil` values are skipped, which means they are not stored;
  the call to the adapter is bypassed.

  ## Options

    * `:ttl` - (positive integer or `:infinity`) Defines the time-to-live
      (or expiry time) for the given key  in **milliseconds**. Defaults
      to `:infinity`.

  See the configured adapter documentation for more runtime options.

  ## Example

      iex> MyCache.put_new("foo", "bar")
      true

      iex> MyCache.put_new("foo", "bar")
      false

  If the value is nil, it is not stored (operation is skipped):

      iex> MyCache.put_new("other", nil)
      true

  """
  @callback put_new(key, value, opts) :: boolean

  @doc """
  Similar to `c:put_new/3` but raises `Nebulex.KeyAlreadyExistsError` if the
  key already exists.

  See `c:put_new/3` for general considerations and options.

  ## Example

      iex> MyCache.put_new!("foo", "bar")
      true

  """
  @callback put_new!(key, value, opts) :: true

  @doc """
  Puts the given `entries` (key/value pairs) into the `cache`. It will not
  perform any operation at all even if just a single key already exists.

  Returns `true` if all entries were successfully set. It returns `false`
  if no key was set (at least one key already existed).

  ## Options

    * `:ttl` - (positive integer or `:infinity`) Defines the time-to-live
      (or expiry time) for the given key  in **milliseconds**. Defaults
      to `:infinity`.

  See the configured adapter documentation for more runtime options.

  ## Example

      iex> MyCache.put_new_all(apples: 3, bananas: 1)
      true

      iex> MyCache.put_new_all(%{apples: 3, oranges: 1}, ttl: 10_000)
      false

  Ideally, this operation should be atomic, so all given keys are put at once.
  But it depends purely on the adapter's implementation and the backend used
  internally by the adapter. Hence, it is recommended to review the adapter's
  documentation.
  """
  @callback put_new_all(entries, opts) :: boolean

  @doc """
  Alters the entry stored under `key`, but only if the entry already exists
  into the Cache.

  Returns `true` if a value was set, otherwise, `false` is returned.

  By default, `nil` values are skipped, which means they are not stored;
  the call to the adapter is bypassed.

  ## Options

    * `:ttl` - (positive integer or `:infinity`) Defines the time-to-live
      (or expiry time) for the given key  in **milliseconds**. Defaults
      to `:infinity`.

  See the configured adapter documentation for more runtime options.

  ## Example

      iex> MyCache.replace("foo", "bar")
      false

      iex> MyCache.put_new("foo", "bar")
      true

      iex> MyCache.replace("foo", "bar2")
      true

  Update current value and TTL:

      iex> MyCache.replace("foo", "bar3", ttl: 10_000)
      true

  """
  @callback replace(key, value, opts) :: boolean

  @doc """
  Similar to `c:replace/3` but raises `KeyError` if `key` is not found.

  See `c:replace/3` for general considerations and options.

  ## Example

      iex> MyCache.replace!("foo", "bar")
      true

  """
  @callback replace!(key, value, opts) :: true

  @doc """
  Deletes the entry in Cache for a specific `key`.

  See the configured adapter documentation for runtime options.

  ## Example

      iex> MyCache.put(:a, 1)
      :ok

      iex> MyCache.delete(:a)
      :ok

      iex> MyCache.get(:a)
      nil

      iex> MyCache.delete(:non_existent_key)
      :ok

  """
  @callback delete(key, opts) :: :ok

  @doc """
  Returns and removes the value associated with `key` in the Cache.
  If the `key` does not exist, then `nil` is returned.

  If `key` is `nil`, the call to the adapter is bypassed, and `nil` is returned.

  See the configured adapter documentation for runtime options.

  ## Examples

      iex> MyCache.put(:a, 1)
      :ok

      iex> MyCache.take(:a)
      1

      iex> MyCache.take(:a)
      nil

  """
  @callback take(key, opts) :: value

  @doc """
  Similar to `c:take/2` but raises `KeyError` if `key` is not found.

  See `c:take/2` for general considerations and options.

  ## Example

      MyCache.take!(:a)

  """
  @callback take!(key, opts) :: value

  @doc """
  Returns whether the given `key` exists in the Cache.

  ## Examples

      iex> MyCache.put(:a, 1)
      :ok

      iex> MyCache.has_key?(:a)
      true

      iex> MyCache.has_key?(:b)
      false

  """
  @callback has_key?(key) :: boolean

  @doc """
  Gets the value from `key` and updates it, all in one pass.

  `fun` is called with the current cached value under `key` (or `nil` if `key`
  hasn't been cached) and must return a two-element tuple: the current value
  (the retrieved value, which can be operated on before being returned) and
  the new value to be stored under `key`. `fun` may also return `:pop`, which
  means the current value shall be removed from Cache and returned.

  The returned value is a tuple with the current value returned by `fun` and
  the new updated value under `key`.

  ## Options

    * `:ttl` - (positive integer or `:infinity`) Defines the time-to-live
      (or expiry time) for the given key  in **milliseconds**. Defaults
      to `:infinity`.

  See the configured adapter documentation for more runtime options.

  ## Examples

  Update nonexistent key:

      iex> MyCache.get_and_update(:a, fn current_value ->
      ...>   {current_value, "value!"}
      ...> end)
      {nil, "value!"}

  Update existing key:

      iex> MyCache.get_and_update(:a, fn current_value ->
      ...>   {current_value, "new value!"}
      ...> end)
      {"value!", "new value!"}

  Pop/remove value if exist:

      iex> MyCache.get_and_update(:a, fn _ -> :pop end)
      {"new value!", nil}

  Pop/remove nonexistent key:

      iex> MyCache.get_and_update(:b, fn _ -> :pop end)
      {nil, nil}

  """
  @callback get_and_update(key, (value -> {current_value, new_value} | :pop), opts) ::
              {current_value, new_value}
            when current_value: value, new_value: value

  @doc """
  Updates the cached `key` with the given function.

  If `key` is present in Cache with value `value`, `fun` is invoked with
  argument `value` and its result is used as the new value of `key`.

  If `key` is not present in Cache, `initial` is inserted as the value of `key`.
  The initial value will not be passed through the update function.

  ## Options

    * `:ttl` - (positive integer or `:infinity`) Defines the time-to-live
      (or expiry time) for the given key  in **milliseconds**. Defaults
      to `:infinity`.

  See the configured adapter documentation for more runtime options.

  ## Examples

      iex> MyCache.update(:a, 1, &(&1 * 2))
      1

      iex> MyCache.update(:a, 1, &(&1 * 2))
      2

  """
  @callback update(key, initial :: value, (value -> value), opts) :: value

  @doc """
  Increments the counter stored at `key` by the given `amount`.

  If `amount < 0` (negative), the value is decremented by that `amount`
  instead.

  ## Options

    * `:ttl` - (positive integer or `:infinity`) Defines the time-to-live
      (or expiry time) for the given key  in **milliseconds**. Defaults
      to `:infinity`.

    * `:default` - If `key` is not present in Cache, the default value is
      inserted as initial value of key before the it is incremented.
      Defaults to `0`.

  See the configured adapter documentation for more runtime options.

  ## Examples

      iex> MyCache.incr(:a)
      1

      iex> MyCache.incr(:a, 2)
      3

      iex> MyCache.incr(:a, -1)
      2

      iex> MyCache.incr(:missing_key, 2, default: 10)
      12

  """
  @callback incr(key, amount :: integer, opts) :: integer

  @doc """
  Decrements the counter stored at `key` by the given `amount`.

  If `amount < 0` (negative), the value is incremented by that `amount`
  instead (opposite to `incr/3`).

  ## Options

    * `:ttl` - (positive integer or `:infinity`) Defines the time-to-live
      (or expiry time) for the given key  in **milliseconds**. Defaults
      to `:infinity`.

    * `:default` - If `key` is not present in Cache, the default value is
      inserted as initial value of key before the it is incremented.
      Defaults to `0`.

  See the configured adapter documentation for more runtime options.

  ## Examples

      iex> MyCache.decr(:a)
      -1

      iex> MyCache.decr(:a, 2)
      -3

      iex> MyCache.decr(:a, -1)
      -2

      iex> MyCache.decr(:missing_key, 2, default: 10)
      8

  """
  @callback decr(key, amount :: integer, opts) :: integer

  @doc """
  Returns the remaining time-to-live for the given `key`. If the `key` does not
  exist, then `nil` is returned.

  ## Examples

      iex> MyCache.put(:a, 1, ttl: 5000)
      :ok

      iex> MyCache.put(:b, 2)
      :ok

      iex> MyCache.ttl(:a)
      _remaining_ttl

      iex> MyCache.ttl(:b)
      :infinity

      iex> MyCache.ttl(:c)
      nil

  """
  @callback ttl(key) :: timeout | nil

  @doc """
  Returns `true` if the given `key` exists and the new `ttl` was successfully
  updated, otherwise, `false` is returned.

  ## Examples

      iex> MyCache.put(:a, 1)
      :ok

      iex> MyCache.expire(:a, 5)
      true

      iex> MyCache.expire(:a, :infinity)
      true

      iex> MyCache.ttl(:b, 5)
      false

  """
  @callback expire(key, ttl :: timeout) :: boolean

  @doc """
  Returns `true` if the given `key` exists and the last access time was
  successfully updated, otherwise, `false` is returned.

  ## Examples

      iex> MyCache.put(:a, 1)
      :ok

      iex> MyCache.touch(:a)
      true

      iex> MyCache.ttl(:b)
      false

  """
  @callback touch(key) :: boolean

  ## Deprecated Callbacks

  @doc """
  Returns the total number of cached entries.

  ## Examples

      iex> :ok = Enum.each(1..10, &MyCache.put(&1, &1))
      iex> MyCache.size()
      10

      iex> :ok = Enum.each(1..5, &MyCache.delete(&1))
      iex> MyCache.size()
      5

  """
  @doc deprecated: "Use count_all/2 instead"
  @callback size() :: integer

  @doc """
  Flushes the cache and returns the number of evicted keys.

  ## Examples

      iex> :ok = Enum.each(1..5, &MyCache.put(&1, &1))
      iex> MyCache.flush()
      5

      iex> MyCache.size()
      0

  """
  @doc deprecated: "Use delete_all/2 instead"
  @callback flush() :: integer

  ## Nebulex.Adapter.Queryable

  @optional_callbacks all: 2, count_all: 2, delete_all: 2, stream: 2

  @doc """
  Fetches all entries from cache matching the given `query`.

  May raise `Nebulex.QueryError` if query validation fails.

  ## Query values

  There are two types of query values. The ones shared and implemented
  by all adapters and the ones that are adapter specific.

  ### Common queries

  The following query values are shared and/or supported for all adapters:

    * `nil` - Returns a list with all cached entries based on the `:return`
      option.

  ### Adapter-specific queries

  The `query` value depends entirely on the adapter implementation; it could
  any term. Therefore, it is highly recommended to see adapters' documentation
  for more information about building queries. For example, the built-in
  `Nebulex.Adapters.Local` adapter uses `:ets.match_spec()` for queries,
  as well as other pre-defined ones like `:unexpired` and `:expired`.

  ## Options

    * `:return` - Tells the query what to return from the matched entries.
      See the possible values in the "Query return option" section below.
      The default depends on the adapter, for example, the default for the
      built-in adapters is `:key`. This option is supported by the built-in
      adapters, but it is recommended to see the adapter's documentation
      to confirm its compatibility with this option.

  See the configured adapter documentation for more runtime options.

  ## Query return option

  The following are the possible values for the `:return` option:

    * `:key` - Returns a list only with the keys.
    * `:value` - Returns a list only with the values.
    * `:entry` - Returns a list of `t:Nebulex.Entry.t/0`.
    * `{:key, :value}` - Returns a list of tuples in the form `{key, value}`.

  See adapters documentation to confirm what of these options are supported
  and what other added.

  ## Example

  Populate the cache with some entries:

      iex> :ok = Enum.each(1..5, &MyCache.put(&1, &1 * 2))

  Fetch all (with default params):

      iex> MyCache.all()
      [1, 2, 3, 4, 5]

  Fetch all entries and return values:

      iex> MyCache.all(nil, return: :value)
      [2, 4, 6, 8, 10]

  Fetch all entries and return them as key/value pairs:

      iex> MyCache.all(nil, return: {:key, :value})
      [{1, 2}, {2, 4}, {3, 6}, {4, 8}, {5, 10}]

  Fetch all entries that match with the given query assuming we are using
  `Nebulex.Adapters.Local` adapter:

      iex> query = [{{:_, :"$1", :"$2", :_, :_}, [{:>, :"$2", 5}], [:"$1"]}]
      iex> MyCache.all(query)
      [3, 4, 5]

  ## Query

  Query spec is defined by the adapter, hence, it is recommended to review
  adapters documentation. For instance, the built-in `Nebulex.Adapters.Local`
  adapter supports `nil | :unexpired | :expired | :ets.match_spec()` as query
  value.

  ## Examples

  Additional built-in queries for `Nebulex.Adapters.Local` adapter:

      iex> unexpired = MyCache.all(:unexpired)
      iex> expired = MyCache.all(:expired)

  If we are using Nebulex.Adapters.Local adapter, the stored entry tuple
  `{:entry, key, value, touched, ttl}`, then the match spec could be
  something like:

      iex> spec = [
      ...>   {{:entry, :"$1", :"$2", :_, :_},
      ...>   [{:>, :"$2", 5}], [{{:"$1", :"$2"}}]}
      ...> ]
      iex> MyCache.all(spec)
      [{3, 6}, {4, 8}, {5, 10}]

  The same previous query but using `Ex2ms`:

      iex> import Ex2ms
      Ex2ms

      iex> spec =
      ...>   fun do
      ...>     {_. key, value, _, _} when value > 5 -> {key, value}
      ...>   end

      iex> MyCache.all(spec)
      [{3, 6}, {4, 8}, {5, 10}]

  """
  @callback all(query :: term, opts) :: [any]

  @doc """
  Similar to `c:all/2` but returns a lazy enumerable that emits all entries
  from the cache matching the given `query`.

  If `query` is `nil`, then all entries in cache match and are returned
  when the stream is evaluated; based on the `:return` option.

  May raise `Nebulex.QueryError` if query validation fails.

  ## Query values

  See `c:all/2` callback for more information about the query values.

  ## Options

    * `:return` - Tells the query what to return from the matched entries.
      See the possible values in the "Query return option" section below.
      The default depends on the adapter, for example, the default for the
      built-in adapters is `:key`. This option is supported by the built-in
      adapters, but it is recommended to see the adapter's documentation
      to confirm its compatibility with this option.

    * `:page_size` - Positive integer (>= 1) that defines the page size
      internally used by the adapter for paginating the results coming
      back from the cache's backend. Defaults to `20`; it's unlikely
      this will ever need changing.

  See the configured adapter documentation for more runtime options.

  ## Query return option

  The following are the possible values for the `:return` option:

    * `:key` - Returns a list only with the keys.
    * `:value` - Returns a list only with the values.
    * `:entry` - Returns a list of `t:Nebulex.Entry.t/0`.
    * `{:key, :value}` - Returns a list of tuples in the form `{key, value}`.

  See adapters documentation to confirm what of these options are supported
  and what other added.

  ## Examples

  Populate the cache with some entries:

      iex> :ok = Enum.each(1..5, &MyCache.put(&1, &1 * 2))

  Stream all (with default params):

      iex> MyCache.stream() |> Enum.to_list()
      [1, 2, 3, 4, 5]

  Stream all entries and return values:

      iex> nil |> MyCache.stream(return: :value, page_size: 3) |> Enum.to_list()
      [2, 4, 6, 8, 10]

  Stream all entries and return them as key/value pairs:

      iex> nil |> MyCache.stream(return: {:key, :value}) |> Enum.to_list()
      [{1, 2}, {2, 4}, {3, 6}, {4, 8}, {5, 10}]

  Additional built-in queries for `Nebulex.Adapters.Local` adapter:

      iex> unexpired_stream = MyCache.stream(:unexpired)
      iex> expired_stream = MyCache.stream(:expired)

  If we are using Nebulex.Adapters.Local adapter, the stored entry tuple
  `{:entry, key, value, touched, ttl}`, then the match spec could be
  something like:

      iex> spec = [
      ...>   {{:entry, :"$1", :"$2", :_, :_},
      ...>   [{:>, :"$2", 5}], [{{:"$1", :"$2"}}]}
      ...> ]
      iex> MyCache.stream(spec, page_size: 100) |> Enum.to_list()
      [{3, 6}, {4, 8}, {5, 10}]

  The same previous query but using `Ex2ms`:

      iex> import Ex2ms
      Ex2ms

      iex> spec =
      ...>   fun do
      ...>     {_, key, value, _, _} when value > 5 -> {key, value}
      ...>   end

      iex> spec |> MyCache.stream(page_size: 100) |> Enum.to_list()
      [{3, 6}, {4, 8}, {5, 10}]

  """
  @callback stream(query :: term, opts) :: Enum.t()

  @doc """
  Deletes all entries matching the given `query`. If `query` is `nil`,
  then all entries in the cache are deleted.

  It returns the number of deleted entries.

  May raise `Nebulex.QueryError` if query validation fails.

  See the configured adapter documentation for runtime options.

  ## Query values

  See `c:all/2` callback for more information about the query values.

  ## Example

  Populate the cache with some entries:

      iex> :ok = Enum.each(1..5, &MyCache.put(&1, &1 * 2))

  Delete all (with default params):

      iex> MyCache.delete_all()
      5

  Delete all entries that match with the given query assuming we are using
  `Nebulex.Adapters.Local` adapter:

      iex> query = [{{:_, :"$1", :"$2", :_, :_}, [{:>, :"$2", 5}], [true]}]
      iex> MyCache.delete_all(query)

  > For the local adapter you can use [Ex2ms](https://github.com/ericmj/ex2ms)
    to build the match specs much easier.

  Additional built-in queries for `Nebulex.Adapters.Local` adapter:

      iex> unexpired = MyCache.delete_all(:unexpired)
      iex> expired = MyCache.delete_all(:expired)

  """
  @callback delete_all(query :: term, opts) :: integer

  @doc """
  Counts all entries in cache matching the given `query`.

  It returns the count of the matched entries.

  If `query` is `nil` (the default), then the total number of
  cached entries is returned.

  May raise `Nebulex.QueryError` if query validation fails.

  ## Query values

  See `c:all/2` callback for more information about the query values.

  ## Example

  Populate the cache with some entries:

      iex> :ok = Enum.each(1..5, &MyCache.put(&1, &1 * 2))

  Count all entries in cache:

      iex> MyCache.count_all()
      5

  Count all entries that match with the given query assuming we are using
  `Nebulex.Adapters.Local` adapter:

      iex> query = [{{:_, :"$1", :"$2", :_, :_}, [{:>, :"$2", 5}], [true]}]
      iex> MyCache.count_all(query)

  > For the local adapter you can use [Ex2ms](https://github.com/ericmj/ex2ms)
    to build the match specs much easier.

  Additional built-in queries for `Nebulex.Adapters.Local` adapter:

      iex> unexpired = MyCache.count_all(:unexpired)
      iex> expired = MyCache.count_all(:expired)

  """
  @callback count_all(query :: term, opts) :: integer

  ## Nebulex.Adapter.Persistence

  @optional_callbacks dump: 2, load: 2

  @doc """
  Dumps a cache to the given file `path`.

  Returns `:ok` if successful, or `{:error, reason}` if an error occurs.

  ## Options

  This operation relies entirely on the adapter implementation, which means the
  options depend on each of them. For that reason, it is recommended to review
  the documentation of the adapter to be used. The built-in adapters inherit
  the default implementation from `Nebulex.Adapter.Persistence`, hence, review
  the available options there.

  ## Examples

  Populate the cache with some entries:

      iex> entries = for x <- 1..10, into: %{}, do: {x, x}
      iex> MyCache.set_many(entries)
      :ok

  Dump cache to a file:

      iex> MyCache.dump("my_cache")
      :ok

  """
  @callback dump(path :: Path.t(), opts) :: :ok | {:error, term}

  @doc """
  Loads a dumped cache from the given `path`.

  Returns `:ok` if successful, or `{:error, reason}` if an error occurs.

  ## Options

  Similar to `c:dump/2`, this operation relies entirely on the adapter
  implementation, therefore, it is recommended to review the documentation
  of the adapter to be used. Similarly, the built-in adapters inherit the
  default implementation from `Nebulex.Adapter.Persistence`, hence, review
  the available options there.

  ## Examples

  Populate the cache with some entries:

      iex> entries = for x <- 1..10, into: %{}, do: {x, x}
      iex> MyCache.set_many(entries)
      :ok

  Dump cache to a file:

      iex> MyCache.dump("my_cache")
      :ok

  Load the cache from a file:

      iex> MyCache.load("my_cache")
      :ok

  """
  @callback load(path :: Path.t(), opts) :: :ok | {:error, term}

  ## Nebulex.Adapter.Transaction

  @optional_callbacks transaction: 2, in_transaction?: 0

  @doc """
  Runs the given function inside a transaction.

  A successful transaction returns the value returned by the function.

  See the configured adapter documentation for runtime options.

  ## Examples

      MyCache.transaction fn ->
        alice = MyCache.get(:alice)
        bob = MyCache.get(:bob)
        MyCache.put(:alice, %{alice | balance: alice.balance + 100})
        MyCache.put(:bob, %{bob | balance: bob.balance + 100})
      end

  Locking only the involved key (recommended):

      MyCache.transaction [keys: [:alice, :bob]], fn ->
        alice = MyCache.get(:alice)
        bob = MyCache.get(:bob)
        MyCache.put(:alice, %{alice | balance: alice.balance + 100})
        MyCache.put(:bob, %{bob | balance: bob.balance + 100})
      end

  """
  @callback transaction(opts, function :: fun) :: term

  @doc """
  Returns `true` if the current process is inside a transaction.

  ## Examples

      MyCache.in_transaction?
      #=> false

      MyCache.transaction(fn ->
        MyCache.in_transaction? #=> true
      end)

  """
  @callback in_transaction?() :: boolean

  ## Nebulex.Adapter.Stats

  @optional_callbacks stats: 0, dispatch_stats: 1

  @doc """
  Returns `Nebulex.Stats.t()` with the current stats values.

  If the stats are disabled for the cache, then `nil` is returned.

  ## Example

      iex> MyCache.stats()
      %Nebulex.Stats{
        measurements: {
          evictions: 0,
          expirations: 0,
          hits: 0,
          misses: 0,
          updates: 0,
          writes: 0
        },
        metadata: %{}
      }

  """
  @callback stats() :: Nebulex.Stats.t() | nil

  @doc """
  Emits a telemetry event when called with the current stats count.

  The telemetry `:measurements` map will include the same as
  `Nebulex.Stats.t()`'s measurements. For example:

    * `:evictions` - Current **evictions** count.
    * `:expirations` - Current **expirations** count.
    * `:hits` - Current **hits** count.
    * `:misses` - Current **misses** count.
    * `:updates` - Current **updates** count.
    * `:writes` - Current **writes** count.

  The telemetry `:metadata` map will include the same as `Nebulex.Stats.t()`'s
  metadata by default. For example:

    * `:cache` - The cache module, or the name (if an explicit name has been
      given to the cache).

  Additionally, you can add your own metadata fields by given the option
  `:metadata`.

  ## Options

    * `:event_prefix` – The prefix of the telemetry event.
      Defaults to `[:nebulex, :cache]`.

    * `:metadata` – A map with additional metadata fields. Defaults to `%{}`.

  ## Examples

      iex> MyCache.dispatch_stats()
      :ok

      iex> MyCache.Stats.dispatch_stats(
      ...>   event_prefix: [:my_cache],
      ...>   metadata: %{tag: "tag1"}
      ...> )
      :ok

  **NOTE:** Since `:telemetry` is an optional dependency, when it is not
  defined, a default implementation is provided without any logic, just
  returning `:ok`.
  """
  @callback dispatch_stats(opts) :: :ok
end