ConCache Documentation

ConCache supports TTL for cache items. You can set a global TTL and a check interval for the background process that cleans up expired items.

Key concepts:

• ttl_check_interval: How often the background process checks for expired items. Recommended to be at least 1 second.
• global_ttl: The default expiry for all items.
• touch_on_read: If true, reading an item renews its TTL.
• :infinity: Setting TTL to :infinity prevents an item from ever expiring.
• ConCache.Item: Use this struct to set custom TTLs per item.

# Global configuration
{ConCache, [
  name: :my_cache,
  ttl_check_interval: :timer.seconds(1),
  global_ttl: :timer.seconds(5),
  touch_on_read: true
]}

# Per-item custom TTL
ConCache.put(:my_cache, :key, %ConCache.Item{value: "value", ttl: :timer.seconds(25)})

# Update value without resetting TTL
ConCache.put(:my_cache, :key, %ConCache.Item{value: "value", ttl: :no_update})

# Manually renew TTL
ConCache.touch(:my_cache, :key)

To initialize a new cache, use ConCache.Owner.start_link(options). The options map allows you to configure the cache behavior, including TTL (Time To Live), ETS options, and naming.

Supported configuration keys in options:

• name: The name of the cache.
• ttl: The default time-to-live for items (defaults to :infinity).
• ttl_check: An integer specifying how often (in milliseconds) the TTL manager checks for expired items. If provided, it enables automatic expiration.
• ets_options: A list of ETS configuration options (e.g., [:named_table, :compressed]).
• acquire_lock_timeout: Timeout for acquiring locks (defaults to 5000).
• touch_on_read: Boolean indicating if reading an item should refresh its TTL (defaults to false).
• callback: A function to be called when an item expires.
• time_size: Used to calculate max_time for the internal TTL loop.

ConCache.Owner.start_link([
  name: :my_cache,
  ttl: 60_000,
  ttl_check: 1_000,
  ets_options: [:named_table]
])

ConCache uses a custom mutex implementation to provide isolation. While modification operations (update, put, delete) automatically acquire a lock on a per-row basis, you can use ConCache.isolated/3 to perform isolated reads or use arbitrary IDs to implement custom locking granularity.

Important Notes:

• Isolation is not transactional (atomic). If a series of calls within an isolated block fails, any modifications already made to ETS will persist.
• Isolation operations can be nested, though it is not recommended.
• If a lock cannot be acquired within the acquire_lock_timeout (default 5 seconds), an exception is raised. Use ConCache.try_isolated/3 to return {:error, :locked} immediately instead of raising an exception.

# Perform an isolated read on a specific key
ConCache.isolated(cache, key, fn() ->
  ConCache.get(cache, key)
end)

# Use an arbitrary ID for custom locking granularity
ConCache.isolated(cache, my_lock_id, fn() ->
  ...
end)

# Attempt isolation but return error immediately if locked
ConCache.try_isolated(cache, my_lock_id, fn() ->
  ...
end)

ConCache provides synchronized operations that are isolated on a row level. Modifications to a specific key (like update, put, or delete) will wait for the current operation on that key to finish, but other keys remain unaffected. Reads during an update are always dirty.

# Update an existing key
ConCache.update(:my_cache, :key, fn(old_value) ->
  {:ok, "new_value"}
end)

# Update only if the key exists; returns {:error, :not_existing} otherwise
ConCache.update_existing(:my_cache, :key, fn(old_value) ->
  {:ok, "new_value"}
end)

# Returns existing value, or calls function and stores the result.
# If multiple processes call this for the same key, the function runs only once.
ConCache.get_or_store(:my_cache, :key, fn() ->
  "initial_value"
end)

# Similar to get_or_store, but only caches if the function returns an :ok tuple.
ConCache.fetch_or_store(:my_cache, :key, fn ->
  case call_api() do
    {:ok, data} -> {:ok, process_data(data)}
    {:error, _reason} = error -> error
  end
end)