@callback delete(adapter_meta(), key(), opts()) :: :ok | Nebulex.Cache.error_tuple()

Deletes a single entry from cache.

Returns the bare :ok on success (not {:ok, _}), whether or not the key existed. Nebulex relies on this exact value, for example to count deletions in the stats and in the default Nebulex.Adapter.CompositeKV implementation.

If there's an error with executing the command, {:error, reason} is returned, where reason is the cause of the error.

See Nebulex.Cache.delete/2.

@callback expire(adapter_meta(), key(), ttl(), opts()) ::
  Nebulex.Cache.ok_error_tuple(boolean())

Returns {:ok, true} if the given key exists and the new ttl is successfully updated; otherwise, {:ok, false} is returned.

If there's an error with executing the command, {:error, reason} is returned; where reason is the cause of the error.

See Nebulex.Cache.expire/3.

@callback fetch(adapter_meta(), key(), opts()) ::
  Nebulex.Cache.ok_error_tuple(value(), Nebulex.Cache.fetch_error_reason())

Fetches the value for a specific key in the cache.

If the cache contains the given key, then its value is returned in the shape of {:ok, value}.

If there's an error with executing the command, {:error, reason} is returned. reason is the cause of the error and can be Nebulex.KeyError if the cache does not contain key, Nebulex.Error otherwise.

See Nebulex.Cache.fetch/2.

@callback has_key?(adapter_meta(), key(), opts()) ::
  Nebulex.Cache.ok_error_tuple(boolean())

Determines if the cache contains an entry for the specified key.

More formally, it returns {:ok, true} if the cache contains the given key. If the cache doesn't contain key, {:ok, false} is returned.

If there's an error with executing the command, {:error, reason} is returned, where reason is the cause of the error.

See Nebulex.Cache.has_key?/2.

@callback put(adapter_meta(), key(), value(), on_write(), ttl(), keep_ttl(), opts()) ::
  Nebulex.Cache.ok_error_tuple(boolean())

Puts the given value under key into the cache.

Returns {:ok, true} if the value with key key is successfully inserted. Otherwise, {:ok, false} is returned.

If there's an error with executing the command, {:error, reason} is returned, where reason is the cause of the error.

The ttl argument defines the time-to-live for the stored entry. If it is not set, it means the entry doesn't have a time-to-live, so it shouldn't expire.

The keep_ttl argument tells whether to retain the time to live associated with the key. Otherwise, the TTL is always overwritten.

on_write argument

The on_write argument supports the following values:

• :put - If the key already exists, it is overwritten. Any previous time-to-live associated with the key is discarded on a successful write, unless keep_ttl is true.

• :put_new - Stores the entry only if the key does not exist. Otherwise, {:ok, false} is returned.

• :replace - Alters the value stored under the given key, but only if the key already exists in the cache. Otherwise, {:ok, false} is returned.

See Nebulex.Cache.put/3, Nebulex.Cache.put_new/3, Nebulex.Cache.replace/3.

@callback put_all(adapter_meta(), entries(), on_write(), ttl(), opts()) ::
  Nebulex.Cache.ok_error_tuple(boolean())

Puts the given entries (key/value pairs) into the cache. The operation should be atomic when the backend supports it.

If there's an error with executing the command, {:error, reason} is returned, where reason is the cause of the error.

The ttl argument works the same as put/7 but applies to all keys.

on_write argument

The on_write argument supports the following values:

• :put - Stores all entries and returns {:ok, true}. If a key already exists, it is overwritten, and any previous time-to-live associated with it is discarded on a successful write.

• :put_new - Inserts all entries only if none of them exist in the cache, and returns {:ok, true}. Otherwise, {:ok, false} is returned.

See Nebulex.Cache.put_all/2 and Nebulex.Cache.put_new_all/2.

@callback take(adapter_meta(), key(), opts()) ::
  Nebulex.Cache.ok_error_tuple(value(), Nebulex.Cache.fetch_error_reason())

Removes and returns the value associated with key in the cache.

If key is present in the cache, its value is removed and returned as {:ok, value}.

If there's an error with executing the command, {:error, reason} is returned. reason is the cause of the error and can be Nebulex.KeyError if the cache does not contain key or Nebulex.Error otherwise.

See Nebulex.Cache.take/2.

@callback touch(adapter_meta(), key(), opts()) :: Nebulex.Cache.ok_error_tuple(boolean())

Returns {:ok, true} if the given key exists and the last access time is successfully updated; otherwise, {:ok, false} is returned.

If there's an error with executing the command, {:error, reason} is returned, where reason is the cause of the error.

See Nebulex.Cache.touch/2.

@callback ttl(adapter_meta(), key(), opts()) ::
  Nebulex.Cache.ok_error_tuple(timeout(), Nebulex.Cache.fetch_error_reason())

Returns the remaining time-to-live for the given key.

If key is present in the cache, then its remaining TTL is returned in the shape of {:ok, ttl}.

If there's an error with executing the command, {:error, reason} is returned. reason is the cause of the error and can be Nebulex.KeyError if the cache does not contain key, Nebulex.Error otherwise.

See Nebulex.Cache.ttl/2.

@callback update_counter(adapter_meta(), key(), amount, default, ttl(), opts()) ::
  Nebulex.Cache.ok_error_tuple(integer())
when amount: integer(), default: integer()

Updates the counter mapped to the given key.

If amount > 0, the counter is incremented by the given amount. If amount < 0, the counter is decremented by the given amount. If amount == 0, the counter is not updated.

If there's an error with executing the command, {:error, reason} is returned, where reason is the cause of the error.

The ttl is set only when the key doesn't exist. Otherwise, only the counter is updated and the TTL set when the counter was first created is kept.

See Nebulex.Cache.incr/3. See Nebulex.Cache.decr/3.