sider v0.1.0 Sider View Source

Sider is an in-memory key-value store with the following characteristics:

  1. keys & values may be of any type
  2. Key-value pairs expire - once set in the store, they are only valid for a given time
  3. Sider has O(keys) + O(values) memory characteristics
  4. The cache maintains consistent access times - It will not degrade when reaping expired values

The usage of Sider is as follows. Usually, it will be started under a supervisor with a given name

children = [
  {Sider, %{capacity: 100, name: :my_cache}}
]
Supervisor.start_link(children, strategy: :one_for_one)

You can then call the cache via its given name, similar to this

Sider.get(:my_cache, :a)

Link to this section Summary

Functions

Returns an existing key, if it has not expired

Removes a key-value pair from the cache, if it exists. This function no-ops if the key is non-existant

Store a new key-value pair, with an optional timeout for when the pair should expire Returns :ok if successful, or {:error, :max_capacity} if the cache is full

Create a sider cache process. The behavior of the sider cache can be controlled by the following args reap_interval: The number of milliseconds to wait before removing keys that have expired capacity: The number of keys allowed in the store. This includes expired keys that have not been reaped

Link to this section Types

Link to this type

args() View Source
args() ::
  %{reap_interval: pos_integer(), capacity: pos_integer(), name: atom()}
  | %{name: atom(), capacity: pos_integer()}
  | %{capacity: pos_integer()}

Link to this section Functions

Link to this function

get(pid, key) View Source
get(GenServer.server(), key()) :: {:ok, value()} | {:error, :missing_key}

Returns an existing key, if it has not expired.

Examples

iex> {:ok, pid} = Sider.start_link(%{reap_interval: 1, capacity: 100})
iex> Sider.set(pid, :a, :foo)
iex> {:ok, :foo} = Sider.get(pid, :a)
iex> {:error, :missing_key} = Sider.get(pid, :b)
iex> :ok
:ok
Link to this function

remove(pid, key, opts \\ []) View Source
remove(GenServer.server(), key(), [] | [{:only, :expired}]) :: nil

Removes a key-value pair from the cache, if it exists. This function no-ops if the key is non-existant

If you pass in the only: :expired option, the value will only be removed if the entry has expired (See the timeout value in Sider.set/4)

Examples

iex> {:ok, pid} = Sider.start_link(%{reap_interval: 1000, capacity: 100})
iex> Sider.set(pid, :a, :foo)
iex> Sider.remove(pid, :a)
nil
Link to this function

set(pid, key, value, timeout \\ nil) View Source
set(GenServer.server(), key(), value(), pos_integer() | nil) ::
  :ok | {:error, :max_capacity}

Store a new key-value pair, with an optional timeout for when the pair should expire Returns :ok if successful, or {:error, :max_capacity} if the cache is full

If you call set() on a key that already exists in the store, that key-pair will be overwritten

Examples

iex> {:ok, pid} = Sider.start_link(%{reap_interval: 1000, capacity: 1})
iex> :ok = Sider.set(pid, :a, :foo, 1000) # Set a key with a value of :foo that expires after 1000ms
iex> :ok = Sider.set(pid, :a, {1, 2}, 1000) # Overwrite the key
iex> Sider.set(pid, :b, :bar) # The capacity is 1, so the key cannot be written
{:error, :max_capacity}

Create a sider cache process. The behavior of the sider cache can be controlled by the following args reap_interval: The number of milliseconds to wait before removing keys that have expired capacity: The number of keys allowed in the store. This includes expired keys that have not been reaped.

Examples

iex> {:ok, _pid} = Sider.start_link(%{reap_interval: 60_000, capacity: 1_000_000, name: :my_cache})
iex> :ok
:ok