Mentat v0.4.0 Mentat View Source

Provides a basic 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)

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.

Link to this section Summary

Functions

Returns a specification to start this module under a supervisor.

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

Returns a specification to start this module under a supervisor.

See Supervisor.

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 - Limits to the number of keys a cache will store. The default value is :none.

    • :size - Required. The maximum number of values to store in the cache.

    • :reclaim - The percentage of keys to reclaim if the limit is exceeded. The default value is 0.1.

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.