Built-in adapter for replicated cache topology.

The replicated cache excels in its ability to handle data replication, concurrency control and failover in a cluster, all while delivering in-memory data access speeds. A clustered replicated cache is exactly what it says it is: a cache that replicates its data to all cluster nodes.

There are several challenges to building a reliably replicated cache. The first is how to get it to scale and perform well. Updates to the cache have to be sent to all cluster nodes, and all cluster nodes have to end up with the same data, even if multiple updates to the same piece of data occur at the same time. Also, if a cluster node requests a lock, ideally it should not have to get all cluster nodes to agree on the lock or at least do it in a very efficient way (:global is used for this), otherwise it will scale extremely poorly; yet in the case of a cluster node failure, all of the data and lock information must be kept safely.

The best part of a replicated cache is its access speed. Since the data is replicated to each cluster node, it is available for use without any waiting. This is referred to as "zero latency access," and is perfect for situations in which an application requires the highest possible speed in its data access.

However, there are some limitations:

• <ins>Cost Per Update</ins> - Updating a replicated cache requires pushing the new version of the data to all other cluster members, which will limit scalability if there is a high frequency of updates per member.

• <ins>Cost Per Entry</ins> - The data is replicated to every cluster member, so Memory Heap space is used on each member, which will impact performance for large caches.

Based on "Distributed Caching Essential Lessons" by Cameron Purdy.

When used, the Cache expects the :otp_app and :adapter as options. The :otp_app should point to an OTP application that has the cache configuration. For example:

defmodule MyApp.ReplicatedCache do
  use Nebulex.Cache,
    otp_app: :my_app,
    adapter: Nebulex.Adapters.Replicated
end

Optionally, you can configure the desired primary storage adapter with the option :primary_storage_adapter; defaults to Nebulex.Adapters.Local.

defmodule MyApp.ReplicatedCache do
  use Nebulex.Cache,
    otp_app: :my_app,
    adapter: Nebulex.Adapters.Replicated,
    primary_storage_adapter: Nebulex.Adapters.Local
end

The configuration for the cache must be in your application environment, usually defined in your config/config.exs:

config :my_app, MyApp.ReplicatedCache,
  primary: [
    gc_interval: 3_600_000,
    backend: :shards
  ]

For more information about the usage, see Nebulex.Cache documentation.

Options

This adapter supports the following options and all of them can be given via the cache configuration:

• :primary - The options that will be passed to the adapter associated with the local primary storage. These options will depend on the local adapter to use.

• task_supervisor_opts - Start-time options passed to Task.Supervisor.start_link/1 when the adapter is initialized.

• :bootstrap_timeout - a timeout in milliseconds that bootstrap process will wait after the cache supervision tree is started so the data can be imported from remote nodes. Defaults to 1000.

Shared options

Almost all of the cache functions outlined in Nebulex.Cache module accept the following options:

• :timeout - The time-out value in milliseconds for the command that will be executed. If the timeout is exceeded, then the current process will exit. For executing a command on remote nodes, this adapter uses Task.await/2 internally for receiving the result, so this option tells how much time the adapter should wait for it. If the timeout is exceeded, the task is shut down but the current process doesn't exit, only the result associated with that task is skipped in the reduce phase.

Extended API

This adapter provides some additional convenience functions to the Nebulex.Cache API.

Retrieving the primary storage or local cache module:

MyCache.__primary__()

Retrieving the cluster nodes associated with the given cache name:

MyCache.nodes()
MyCache.nodes(:cache_name)