Mentat (Mentat v0.6.1) View Source

Elixir CI Module Version Hex Docs Total Download License Last Updated

Provides a super simple cache with ttls.

Usage

A cache must be given a name when its started.

Mentat.start_link(name: :my_cache)

After its been started you can store and retrieve values:

Mentat.put(:my_cache, user_id, user)
user = Mentat.get(:my_cache, user_id)

TTLs

Both put and fetch operations allow you to specify the key's TTL. If no TTL is provided then the TTL is set to :infinity. TTL times are always in milliseconds.

Mentat.put(:my_cache, :key, "value", [ttl: 5_000])

Mentat.fetch(:my_cache, :key, [ttl: 5_000], fn key ->
  {:commit, "value"}
end)

Default TTLs

You can set a global TTL for all new keys

Limits

Mentat supports optional limits per cache.

Mentat.start_link(name: LimitedCache, limit: [size: 100])

When the limit is reached, the janitor will asynchronously reclaim a percentage of the keys.

Telemetry

Mentat publishes multiple telemetry events.

  • [:mentat, :get] - executed after retrieving a value from the cache. Measurements are:

    • :status - Can be either :hit or :miss depending on if the key was found in the cache. Metadata are:
      • :key - The key requested
      • :cache - The cache name
  • [:mentat, :put] - executed when putting a key into the cache. No measurements are provided.

    Metadata are:

    • :key - The key requested
    • :cache - The name of the cache
  • [:mentat, :janitor, :cleanup] - executed after old keys are cleaned from the cache. Measurements are:

    • :duration - the time it took to clean up the old keys. Time is in :native units.
    • total_removed_keys - The count of keys removed from the cache. Metadata are:
      • cache - The cache name.

Installation

def deps do
  [
    {:mentat, "~> 0.5"}
  ]
end

Should I use this?

There are (many) other caching libraries out there that provide many more features than Mentat. But, it turns out, I don't need most of those features. Mentat is intended to be very small while still providing the necessary components. The test suite is sparse, but we've been using this implementation in production for a while now so I feel pretty confident in it.

Link to this section Summary

Functions

Deletes a key from the cache

Fetches a value or executes the fallback function. The function can return either {:commit, term()} or {:ignore, term()}. If {:commit, term()} is returned, the value will be stored in the cache before its returned. See the "TTLs" section for a list of options.

Retrieves a value from a the cache. Returns nil if the key is not found.

Callback implementation for Supervisor.init/1.

Returns a list of all keys.

Removes all keys from the cache.

Puts a new key into the cache. See the "TTLs" section for a list of options.

Starts a new cache.

Updates a keys inserted at time. This is useful in conjunction with limits when you want to evict the oldest keys.

Link to this section Functions

Deletes a key from the cache

Link to this function

fetch(cache, key, opts \\ [], fallback)

View Source

Fetches a value or executes the fallback function. The function can return either {:commit, term()} or {:ignore, term()}. If {:commit, term()} is returned, the value will be stored in the cache before its returned. See the "TTLs" section for a list of options.

Example

Mentat.fetch(:cache, user_id, fn user_id ->
  case get_user(user_id) do
    {:ok, user} ->
      {:commit, user}

    error ->
      {:ignore, error}
  end
end)
Link to this function

get(cache, key, opts \\ [])

View Source

Retrieves a value from a the cache. Returns nil if the key is not found.

Callback implementation for Supervisor.init/1.

Returns a list of all keys.

Removes all keys from the cache.

Link to this function

put(cache, key, value, opts \\ [])

View Source

Puts a new key into the cache. See the "TTLs" section for a list of options.

Starts a new cache.

Options:

  • :name - Required.

  • :cleanup_interval - How often the janitor process will remove old keys. The default value is 5000.

  • :ets_args - Additional arguments to pass to :ets.new/2. The default value is [].

  • :limit - false Limits to the number of keys a cache will store. The default value is [].

  • :ttl - false Default ttl in milliseconds to use for all keys The default value is :infinity.

Link to this function

touch(cache, key, opts \\ [])

View Source

Updates a keys inserted at time. This is useful in conjunction with limits when you want to evict the oldest keys.