* polycache

Polycache is a KVS cache that uses ETS and hashes.

It works like a KVS store, but each key is hashed. When a hash collision
occures the previous value is replaced.

Polycache is built on top of ETS. Insertions and lookups go directly
to ETS without any serialization or locking. This allows concurrent
access without bottlenecks.

*Projects using this library should implement locking based on their specific requirements.*

** Build

Polycache is built using rebar3.

You can include it in your projects as a dependency in rebar.config:
#+BEGIN_SRC erlang
  {deps, [%% ... Other dependencies
         {polycache, {git, "https://github.com/hyperimpose/polycache.git", {branch, "master"}}}]}.
#+END_SRC

or compile it by running ~$ rebar3 compile~

** API Usage

The ~polycache~ module contains the API that should be used by other
programs.

Three functions are exported by polycache: new/1, get/2, set/3, set/4.

#+BEGIN_SRC erlang
  %% First, make sure that the application has been started.
  application:start(polycache).

  %% Create a new cache with: new(Size)
  %%
  %% Size is the maximum number of elements allowed in the cache.
  %% The function returns a reference to the new cache.
  Cache = polycache:new(1_000_000).

  %% Insert a new entry to the cache: set(Cache, Key, Value).
  polycache:set(Cache, key, 5).

  %% You can also set an expiration timestamp for this entry. If get/2
  %% is called after the entry has expired not_found will be returned.
  Ttl = erlang:system_time(seconds) + 300.  % Expires in 5 minutes
  polycache:set(Cache, key, 5, #{ttl => Ttl}).

  %% Retrieve a value from the cache.
  case polycache:get(Cache, key) of
      {ok, Hit} -> Hit;       % Hit is the value saved in the cache
      not_found -> not_found  % No value has been set for this key
  end.
#+END_SRC

** Future work

- Polycache can be extended to work accross multiple nodes by sharing the contents
of each local cache.
- Two ETS tables could be used for each cache similarly to the 2-random algorithm.

** License

polycache is licensed under the [[https://spdx.org/licenses/BSD-3-Clause.html][BSD 3-Clause "New" or "Revised" License]].
A copy of this license is included in the file [[./COPYING][COPYING]].