Stash (Stash v2.0.0)

This module provides a convenient interface around ETS/DTS without taking large performance hits. Designed for being thrown into a project for basic memory-based storage, perhaps with some form of persistence required.

Summary

Functions

clear()

Removes all items from all namespaces.

delete(namespace, key)

Removes a value from the namespace.

drop(namespace)

Removes all items from a namespace.

empty?(namespace)

Checks whether the namespace is empty.

exists?(namespace, key)

Determines whether a given key exists inside the namespace.

get(namespace, key, default \\ nil)

Retrieves a value from the namespace.

increment(namespace, key, count \\ 1, initial \\ 0)

Increments a key directly in the namespace by count. If the key does not exist it is set to initial before then being incremented.

info()

Returns information about the backing ETS table.

keys(namespace)

Retrieves all keys from the namespace, and returns them as an (unordered) list.

load(path)

Loads a namespace into memory from DTS storage.

persist(path)

Persists a namespace onto disk to allow reload after the process dies.

put(namespace, key, value)

Places a value in the namespace against a given key.

remove(namespace, key, default \\ nil)

Removes a key from the namespace, whilst also returning the last known value.

size(namespace)

Determines the size of the namespace.

Functions

clear()

@spec clear() :: true

Removes all items from all namespaces.

Examples

iex> Stash.put(:namespace1, "key1", "value1")
iex> Stash.put(:namespace2, "key2", "value2")
iex> Stash.put(:namespace3, "key3", "value3")

iex> Stash.clear()
true

iex> Stash.size(:namespace1)
0

iex> Stash.size(:namespace2)
0

iex> Stash.size(:namespace3)
0

delete(namespace, key)

@spec delete(atom(), any()) :: true

Removes a value from the namespace.

Examples

iex> Stash.put(:my_namespace, "key", "value")
iex> Stash.get(:my_namespace, "key")
"value"

iex> Stash.delete(:my_namespace, "key")
true

iex> Stash.get(:my_namespace, "key")
nil

drop(namespace)

@spec drop(atom()) :: true

Removes all items from a namespace.

Examples

iex> Stash.put(:namespace, "key1", "value1")
iex> Stash.put(:namespace, "key2", "value2")
iex> Stash.put(:namespace, "key3", "value3")

iex> Stash.drop(:namespace)
true

iex> Stash.size(:namespace)
0

empty?(namespace)

@spec empty?(atom()) :: boolean()

Checks whether the namespace is empty.

Examples

iex> Stash.put(:my_namespace, "key1", "value1")
iex> Stash.put(:my_namespace, "key2", "value2")
iex> Stash.put(:my_namespace, "key3", "value3")
iex> Stash.empty?(:my_namespace)
false

iex> Stash.clear(:my_namespace)
true

iex> Stash.empty?(:my_namespace)
true

exists?(namespace, key)

@spec exists?(atom(), any()) :: true | false

Determines whether a given key exists inside the namespace.

Examples

iex> Stash.put(:my_namespace, "key", "value")
iex> Stash.exists?(:my_namespace, "key")
true

iex> Stash.exists?(:my_namespace, "missing_key")
false

get(namespace, key, default \\ nil)

@spec get(atom(), any(), any()) :: any()

Retrieves a value from the namespace.

Examples

iex> Stash.put(:my_namespace, "key", "value")
iex> Stash.get(:my_namespace, "key")
"value"

iex> Stash.get(:my_namespace, "missing_key")
nil

iex> Stash.get(:my_namespace, "missing_key, "default")
"default

increment(namespace, key, count \\ 1, initial \\ 0)

@spec increment(atom(), any(), number(), number()) :: number()

Increments a key directly in the namespace by count. If the key does not exist it is set to initial before then being incremented.

Examples

iex> Stash.put(:my_namespace, "key", 1)
iex> Stash.increment(:my_namespace, "key")
2

iex> Stash.increment(:my_namespace, "key", 2)
4

iex> Stash.increment(:my_namespace, "missing_key", 1)
1

iex> Stash.increment(:my_namespace, "a_missing_key", 1, 5)
6

info()

@spec info() :: [{atom(), any()}]

Returns information about the backing ETS table.

Examples

iex> Stash.info()
[read_concurrency: true, write_concurrency: true, compressed: false,
 memory: 1361, owner: #PID<0.126.0>, heir: :none, name: :my_namespace, size: 2,
 node: :nonode@nohost, named_table: true, type: :set, keypos: 1,
 protection: :public]

keys(namespace)

@spec keys(atom()) :: [any()]

Retrieves all keys from the namespace, and returns them as an (unordered) list.

Examples

iex> Stash.put(:my_namespace, "key1", "value1")
iex> Stash.put(:my_namespace, "key2", "value2")
iex> Stash.put(:my_namespace, "key3", "value3")
iex> Stash.keys(:my_namespace)
[ "key2", "key1", "key3" ]

iex> Stash.keys(:empty_namespace)
[]

load(path)

@spec load(binary()) :: atom()

Loads a namespace into memory from DTS storage.

Examples

iex> Stash.load("/tmp/temporary.dat")
:ok

persist(path)

@spec persist(binary()) :: atom()

Persists a namespace onto disk to allow reload after the process dies.

Examples

iex> Stash.persist(:my_namespace, "/tmp/temporary.dat")
:ok

put(namespace, key, value)

@spec put(atom(), any(), any()) :: true

Places a value in the namespace against a given key.

Examples

iex> Stash.put(:my_namespace, "key", "value")
true

remove(namespace, key, default \\ nil)

@spec remove(atom(), any(), any()) :: any()

Removes a key from the namespace, whilst also returning the last known value.

Examples

iex> Stash.put(:my_namespace, "key", "value")
iex> Stash.remove(:my_namespace, "key")
"value"

iex> Stash.get(:my_namespace, "key")
nil

iex> Stash.remove(:my_namespace, "missing_key")
nil

iex> Stash.remove(:my_namespace, "missing_key, "default")
"default"

size(namespace)

@spec size(atom()) :: number()

Determines the size of the namespace.

Examples

iex> Stash.put(:my_namespace, "key1", "value1")
iex> Stash.put(:my_namespace, "key2", "value2")
iex> Stash.put(:my_namespace, "key3", "value3")
iex> Stash.size(:my_namespace)
3