Cachex

Cachex is an extremely fast in-memory key/value store with support for many useful features:

• Time-based key expirations
• Maximum size protection
• Pre/post execution hooks
• Proactive/reactive cache warming
• Transactions and row locking
• Asynchronous write operations
• Distribution across app nodes
• Syncing to a local filesystem
• Idiomatic cache streaming
• Batched write operations
• User command invocation
• Statistics gathering

All of these features are optional and are off by default so you can pick and choose those you wish to enable.

Installation

As of v0.8, Cachex is available on Hex. You can install the package via:

def deps do
  [{:cachex, "~> 3.6"}]
end

Usage

In general use of Cachex, you'll likely only need to add your cache as a child of your application. If you created your project via Mix, this is usually handled in lib/my_app/application.ex:

children = [
  {Cachex, name: :my_cache_name}
]

If you wish to start a cache manually (for example, in iex), you can use Cachex.start_link/2:

Cachex.start_link(name: :my_cache)

Once your cache has started you can call any of the main Cachex API using the name of your cache. All Cachex actions have an automatically generated "unsafe" equivalent (appended with !):

iex(1)> Cachex.get(:my_cache, "key")
{:ok, nil}
iex(2)> Cachex.get!(:my_cache, "key")
nil
iex(3)> Cachex.get(:missing_cache, "key")
{:error, :no_cache}
iex(4)> Cachex.get!(:missing_cache, "key")
** (Cachex.ExecutionError) Specified cache not running
    (cachex) lib/cachex.ex:249: Cachex.get!/3

Generally you should use the non-! versions to be more explicit in your code, but the ! version exists for convenience and to make assertions easier in unit testing. For further information or examples on supported features and options, please see the documentation.

Benchmarks

There are some very trivial benchmarks available using Benchee in the benchmarks/ directory. You can run the benchmarks using the following command:

# default benchmarks
$ mix bench

# enable benchmarks for compressed tests
$ CACHEX_BENCH_COMPRESS=true mix bench

# enable benchmarks for transactional tests
$ CACHEX_BENCH_TRANSACTIONS=true mix bench

Any combination of these environment variables is also possible, to allow you to test and benchmark your specific workflows.

Contributions

If you feel something can be improved, or have any questions about certain behaviours or pieces of implementation, please feel free to file an issue. Proposed changes should be taken to issues before any PRs to avoid wasting time on code which might not be merged upstream.

If you do make changes to the codebase, please make sure you test your changes thoroughly, and include any unit tests alongside new or changed behaviours. Cachex currently uses the excellent excoveralls to track code coverage.

$ mix test # --exclude=distributed to skip slower tests
$ mix credo
$ mix coveralls
$ mix coveralls.html && open cover/excoveralls.html