View Source segmented_cache (segmented_cache v0.3.1)
segmented_cache
is a key/value pairs cache library implemented in rotating segments.
For more information, see the README, and the function documentation.
Summary
Functions
Delete an entry in all ets segments
Delete a pattern in all ets segments
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.
See also: start_link/2.
See also: start_link/2.
See also: start_link/2.
Start and link a cache entity in the local node
Types
-type key() :: term().
-type merger_fun(Value) :: fun((Value, Value) -> Value).
-type name() :: atom().
-type opts() :: #{scope => scope(), strategy => strategy(), segment_num => non_neg_integer(), ttl => timeout() | {erlang:time_unit(), non_neg_integer()}, merger_fun => merger_fun(term())}.
-type scope() :: atom().
-type strategy() :: fifo | lru.
-type value() :: term().
Functions
Delete an entry in all ets segments
Might raise a telemetry error if the request fails: name: [segmented_cache, Name, delete_error] measurements: #{} metadata: #{name => atom(), delete_type => entry, value => Key, class => throw | error | exit, reason => term()}
-spec delete_pattern(name(), ets:match_pattern()) -> true.
Delete a pattern in all ets segments
Might raise a telemetry error if the request fails: name: [segmented_cache, Name, delete_error] measurements: #{} metadata: #{name => atom(), delete_type => pattern, value => Pattern, class => throw | error | exit, reason => term()}
Get the entry for Key in cache
Raises telemetry span name: [segmented_cache, Name, request, _] start metadata: #{name => atom()} stop metadata: #{name => atom(), hit => boolean()}
Check if Key is cached
Raises telemetry span name: [segmented_cache, Name, request, _] start metadata: #{name => atom()} stop metadata: #{name => atom(), hit => 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.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 the compare_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.
-spec start(name()) -> gen_server:start_ret().
See also: start_link/2.
-spec start(name(), opts()) -> gen_server:start_ret().
See also: start_link/2.
-spec start_link(name()) -> gen_server:start_ret().
See also: start_link/2.
-spec start_link(name(), opts()) -> gen_server:start_ret().
Start and link a cache entity in the local node
Name
must be an atom. Then the cache will be identified by the pair {segmented_cache, 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. scope
is a pg
scope. Defaults to pg
. 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(term())
type.