segmented_cache (segmented_cache v0.1.1)
segmented_cache
is a key/value pairs cache library implemented in rotating segments.
Link to this section Summary
Functions
Get the entry for Key in cache
Check if Key is cached
Merge a new entry into an existing one, or add it at the front if none is found.
Add an entry to the first table in the segments.
Start a cache entity in the local node
Link to this section Types
iterative_fun/1
Specs
iterative_fun(Term) :: fun((ets:tid(), Term) -> {continue | stop, not_found | term()}).
merger_fun/1
Specs
merger_fun(Term) :: fun((Term, Term) -> Term).
name/0
Specs
name() :: atom().
opts/0
Specs
opts() :: #{strategy => strategy(), segment_num => non_neg_integer(), ttl => timeout() | {erlang:time_unit(), non_neg_integer()}, merger_fun => merger_fun(term())}.
strategy/0
Specs
strategy() :: fifo | lru.
Link to this section Functions
assert_parameters(Opts)
delete_entry(Name, Key)
Specs
delete_entry(name(), term()) -> true.
delete_pattern(Name, Pattern)
Specs
delete_pattern(name(), term()) -> true.
ets_settings()
get_entry(Name, Key)
Specs
get_entry(name(), term()) -> term() | not_found.
Get the entry for Key in cache
Raises telemetry event name: [?MODULE, request] measurements: #{hit => boolean(), time => microsecond()} metadata: #{name => atom()}is_member(Name, Key)
Specs
is_member(name(), term()) -> boolean().
Check if Key is cached
Raises telemetry event name: [?MODULE, request] measurements: #{hit => boolean(), time => microsecond()} metadata: #{name => atom()}iterate_fun_in_tables(Name, Key, IterativeFun)
Specs
iterate_fun_in_tables(name(), Key, IterativeFun) -> term() when Key :: term(), IterativeFun :: iterative_fun(Key).
iterate_fun_in_tables(IterativeFun, Key, Segments, Int, Int, Int)
Specs
iterate_fun_in_tables(iterative_fun(Key), Key, tuple(), Int, Int, Int) -> {not_found | non_neg_integer(), Value} when Key :: term(), Value :: term(), Int :: non_neg_integer().
measurements()
merge_entry(Name, Key, Value)
Specs
merge_entry(name(), term(), term()) -> boolean().
Merge a new entry into an existing one, or add it at the front if none is found.
Race conditions considerations:compare_and_swap
will ensure they both succeed sequentiallyput_entry_front
apply.post_insert_check_should_retry(_, Index, _)
Specs
post_insert_check_should_retry(boolean(), integer(), integer()) -> boolean().
put_entry(Name, Key, Value)
Specs
put_entry(name(), term(), term()) -> boolean().
Add an entry to the first table in the segments.
Possible race conditions:
ets:insert_new
, resulting in only one of them succeeding. The one that fails, will retry three times a compare_and_swap
, attempting to merge the values and ensuring no data is lost.To treat the data race with the cleaner, after a successful insert, we re-check the index, and if it has changed, we restart the whole operation again: we can be sure that no more rotations will be triggered in a while, so the second round will be final.
Strategy considerations: under a fifo strategy, no other writes can happen, but under a lru strategy, many other workers might attemp to move a record forward. In this case, the forwarding movement doesn't modify the record, and therefore thecompare_and_swap
operation should succeed at once; then, once the record is in the front, all other workers shouldn't be attempting to move it.
send_to_group(Name, Msg)
start(Name)
Specs
start(name()) -> {ok, pid()}.
Start a cache entity in the local node
Name
must be an atom. Then the cache will be identified by the pair {?MODULE, Name}
, and an entry in persistent_term will be created and the worker will join a pg group of the same name. Opts
is a map containing the configuration. strategy
can be fifo or lru. Default is fifo
. segment_num
is the number of segments for the cache. Default is 3
ttl
is the live, in minutes, of _each_ segment. Default is 480
, i.e., 8 hours. merger_fun
is a function that, given a conflict, takes in order the old and new values and applies a merging strategy. See the merger_fun/1
type
start(Name, Opts)
Specs
start_link(Name)
Specs
start_link(name()) -> {ok, pid()}.