ExDiceRoller v1.0.0-rc.2 ExDiceRoller.Cache View Source

Functionality for managing caching for compiled roll functions.

In many cases, ExDiceRoller can be used to compile a dice roll during project compilation, and using it within its local area, or pass it as an argument elsewhere. However, dice rolls can be generated during runtime. Repeated tokenizing, parsing, and compiling of runtime dice rolls can add up. The more complex the dice roll, the higher the cost.

Local testing has revealed that there can be a relatively signifcant performance savings by caching compiled dice rolls and reusing the cached values instead of repeated interpretation. While these savings are on the order of microseconds (not milliseconds), they can add up in applications that have complex rules and are regularly generating dice rolls during runtime.

In an effort to avoid this, ExDiceRoller allows for dice rolls to be cached and reused.

iex> ExDiceRoller.start_cache()
iex> ExDiceRoller.Cache.all()
[]
iex> ExDiceRoller.roll("2d6+1d5", cache: true)
9
iex> [{"2d6+1d5", _}] = ExDiceRoller.Cache.all()
iex> ExDiceRoller.roll("2d6+1d5", cache: true)
11
iex> [{"2d6+1d5", _}] = ExDiceRoller.Cache.all()
iex> ExDiceRoller.roll("1d4+x", [x: 3, cache: true])
7
iex> [{"1d4+x", _}, {"2d6+1d5", _}] = ExDiceRoller.Cache.all()
iex> ExDiceRoller.roll("1d4+x", [x: 3, cache: true])
7

Link to this section Summary

Functions

Retrieves all cached rolls

Empties the specified cache

Deletes the cache entry stored under roll_string. Note that if roll_string is anything but a string, {:error, {:invalid_roll_key, roll_string}} will be returned

Looks up the roll in cache and returns its compiled function. Note that if the roll is not yet cached, it will be compiled, cached, and the compiled function returned

Creates an entry in cache with roll_string as the key and roll_fun as the value

Start the caching system, using the :ex_dice_roller config’s :cache_table value

Starts the caching system, using name for the cache table

Link to this section Types

Link to this type cache_entry() View Source
cache_entry() :: {roll_string(), roll_fun()}
Link to this type roll_fun() View Source
roll_fun() :: function()
Link to this type roll_string() View Source
roll_string() :: String.t()

Link to this section Functions

Link to this function all(cache \\ ExDiceRoller.Cache) View Source
all(atom() | none()) :: [cache_entry()]

Retrieves all cached rolls.

Link to this function clear(cache \\ ExDiceRoller.Cache) View Source
clear(atom() | none()) :: :ok

Empties the specified cache.

Link to this function delete(cache \\ ExDiceRoller.Cache, roll_string) View Source
delete(atom() | none(), roll_string()) ::
  :ok | {:error, {:invalid_roll_key, any()}}

Deletes the cache entry stored under roll_string. Note that if roll_string is anything but a string, {:error, {:invalid_roll_key, roll_string}} will be returned.

Link to this function obtain(cache \\ ExDiceRoller.Cache, roll_string) View Source
obtain(atom() | none(), roll_string()) :: roll_fun()

Looks up the roll in cache and returns its compiled function. Note that if the roll is not yet cached, it will be compiled, cached, and the compiled function returned.

Link to this function put(cache \\ ExDiceRoller.Cache, roll_string, fun) View Source
put(atom() | none(), roll_string(), roll_fun()) :: :ok

Creates an entry in cache with roll_string as the key and roll_fun as the value.

Link to this function start_link() View Source
start_link() :: {:ok, atom()}

Start the caching system, using the :ex_dice_roller config’s :cache_table value.

Link to this function start_link(name) View Source
start_link(atom()) :: {:ok, atom()}

Starts the caching system, using name for the cache table.