kiss_cache

A simple, fast ETS-based cache with timed expiry for Erlang and Elixir.

Copyright CrankWheel ehf. 2025. Initially developed for CrankWheel Screen Sharing back in 2021, (https://crankwheel.com/).

Authored by Jói Sigurdsson (https://joisig.com/).

Features

Philosophy

kiss_cache (Keep It Simple, Stupid) is designed to be the simplest possible timed-expiry cache you can think of for Erlang/Elixir. It's based on ETS and adds minimal complexity while solving common caching problems.

The motivation for writing this cache was that other solutions we tried would sometimes deadlock under heavy load, likely due to transactions. We needed something foolproof but simpler.

This implementation is fairly battle tested with several years in the field and some high-contention use cases that have happened multiple times.

Installation

Elixir (mix)

Add to your mix.exs:

def deps do
  [
    {:kiss_cache, "~> 1.0"}
  ]
end

Erlang (rebar3)

Add to your rebar.config:

{deps, [
  {kiss_cache, "1.0.0"}
]}.

Usage

⚠️ Important: ETS Table Ownership

Cache tables are ETS tables owned by the process that creates them. If that process dies, the cache is deleted. Always create caches from a long-lived, supervised process.

Recommended approach: Pass cache names to the supervisor: 

{ok, _Pid} = kiss_cache_sup:start_link([my_cache, other_cache]).

Alternative: Call start_cache/1 from your own supervised GenServer/worker.

See Architecture for integration details.

Basic Usage

% Create a cache table (do this once, from a long-lived process)
kiss_cache:start_cache(my_cache).

% Put values with default 10 second expiry
kiss_cache:put(my_cache, my_key, my_value).

% Put with custom expiry (in milliseconds)
kiss_cache:put(my_cache, my_key, my_value, 60000).  % 60 seconds

% Get values
Value = kiss_cache:get(my_cache, my_key).

% Get with default if not found
Value = kiss_cache:get(my_cache, my_key, default_value).

% Delete a key
kiss_cache:delete(my_cache, my_key).

Elixir Example

# Create cache
:kiss_cache.start_cache(:my_cache)

# Store and retrieve
:kiss_cache.put(:my_cache, :user_123, %{name: "Alice"})
user = :kiss_cache.get(:my_cache, :user_123)

# With custom expiry (30 seconds)
:kiss_cache.put(:my_cache, :session, session_data, 30_000)

Serialized Fetch (Advanced)

For expensive operations that many processes might request simultaneously, use fetch/4+ to serialize the computation and cache the result:

% First, start the supervisor with your cache names (do this once in your app)
% This creates the caches AND supervises the fetcher processes
{ok, Pid} = kiss_cache_sup:start_link([my_cache]).

% Now fetch will serialize calls to expensive_function/1
Result = kiss_cache:fetch(my_cache, my_module, expensive_function, [arg1]).

% Even if 1000 processes call this simultaneously, expensive_function
% will only be called once (assuming the result isn't already cached).

The serialized fetch prevents "thundering herd" problems where many processes simultaneously try to compute the same expensive value.

Note: Passing cache names to start_link/1 ensures the supervisor owns the ETS tables, guaranteeing they survive for the lifetime of your application.

Cleanup Behavior

Cache cleanup is lazy and efficient:

You can control cleanup behavior:

% Never trigger cleanup on this write
kiss_cache:put(my_cache, key, value, 10000, false).

% Always trigger cleanup on this write
kiss_cache:put(my_cache, key, value, 10000, true).

% Trigger cleanup 1 in N times (here: 1 in 500)
kiss_cache:put(my_cache, key, value, 10000, 500).

API Reference

Core Functions

Fetch Functions (Requires Supervisor)

Architecture

Basic operations (put/get/delete) require no supervisor. Only use the supervisor if you need the fetch/* functions for serialized fetching.

Table Ownership and Supervision

Cache tables are ETS tables with ownership semantics: the table belongs to the process that creates it and is automatically deleted when that process terminates.

Integration patterns:

  1. Using kiss_cache_sup (Recommended)

    Erlang:

    % In your application supervisor
init([]) ->
  Children = [
    {kiss_cache_sup, {kiss_cache_sup, start_link, [[cache1, cache2]]},
     permanent, 5000, supervisor, [kiss_cache_sup]},
    % ... other children
  ],
  {ok, {{one_for_one, 10, 10}, Children}}.

    Elixir:

    # In your application supervisor
def init(_) do
  children = [
    {kiss_cache_sup, [[cache1, cache2]]},
    # ... other children
  ]

  Supervisor.init(children, strategy: :one_for_one)
end

    The supervisor creates and owns the caches, ensuring they persist for your app's lifetime.

  2. Custom worker pattern

    Erlang:

    % In your own GenServer's init/1
init(_Args) ->
  kiss_cache:start_cache(my_cache),
  {ok, #state{}}.

    Elixir:

    # In your own GenServer's init/1
def init(_args) do
  :kiss_cache.start_cache(:my_cache)
  {:ok, %{}}
end

    Your GenServer owns the cache. If your GenServer is supervised, the cache survives restarts.

  3. Basic operations only (no supervisor needed)

    Erlang:

    % Create cache from a long-lived process
kiss_cache:start_cache(my_cache),

% Use basic operations
kiss_cache:put(my_cache, key, value),
kiss_cache:get(my_cache, key).

    Elixir:

    # Create cache from a long-lived process
:kiss_cache.start_cache(:my_cache)

# Use basic operations
:kiss_cache.put(:my_cache, :key, :value)
:kiss_cache.get(:my_cache, :key)

    Suitable if you don't need the fetch/* serialization features.

Warning: Never create caches from the Erlang shell or temporary processes in production, as they will be deleted when that process terminates.

Trade-offs

This cache is designed to be simple and fast at the cost of some consistency guarantees:

These trade-offs are acceptable for use cases where:

If you need stronger consistency guarantees, consider using the serialized fetch/* functions or a different caching solution.

License

MIT

Links