aroyer / cachex

A powerful caching library for Elixir with support for transactions, fallbacks and expirations -

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
• Statistics gathering
• Multi-layered caching/key fallbacks
• Transactions and row locking
• Asynchronous write operations
• Syncing to a local filesystem
• User command invocation

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

Table of Contents

• Installation
• Getting Started
  • Starting Your Cache
  • Main Interface
• Action Blocks
  • Execution Blocks
  • Transaction Blocks
• Cache Limits
  • Configuration
  • Policies
• Custom Commands
  • Defining Commands
  • Invoking A Command
• Disk Interaction
• Execution Hooks
  • Creating Hooks
  • Provisions
• Fallback Caching
  • Common Use Cases
  • Expirations
  • Handling Errors
• TTL Implementation
  • Janitor Processes
  • On Demand Expiration
• Benchmarks
• Contributions

Installation

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

1. Add cachex to your list of dependencies in mix.exs:

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

2. Ensure cachex is started before your application:

def application do
  [applications: [:cachex]]
end

Usage

The typical use of Cachex is to set up using a Supervisor, so that it can be handled automatically:

Supervisor.start_link(
  [
    worker(Cachex, [:my_cache, []])
  ]
)

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

Cachex.start_link(:my_cache, [])

For anything else, please see the documentation.

Benchmarks

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

# default benchmarks, no modifiers
$ mix bench

# use a state instead of a cache name
$ CACHEX_BENCH_STATE=true mix bench

# use a lock write context for all writes
$ CACHEX_BENCH_TRANSACTIONS=true mix bench

# use both a state and lock write context
$ CACHEX_BENCH_STATE=true CACHEX_BENCH_TRANSACTIONS=true mix bench

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
$ mix credo
$ mix coveralls
$ mix coveralls.html && open cover/excoveralls.html