Nebulex v2.0.0-rc.0 Nebulex.Adapters.Replicated View Source

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.

We can define a replicated cache as follows:

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

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

config :my_app, MyApp.ReplicatedCache,
  primary: [
    adapter: Nebulex.Adapters.Local,
    gc_interval: 86_400_000,
    backend: :shards,
    partitions: System.schedulers_online()
  ]

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 store. These options depend on the adapter to use, except for the shared option adapter: (see shared primary options below).

  • 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 Primary Options

  • :adapter - The adapter to be used for the replicated cache as the local primary store. Defaults to Nebulex.Adapters.Local.

The rest of the options depend on the adapter to use.

Runtime options

These options apply to all adapter's functions.

  • :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 one additional convenience function for retrieving the cluster nodes associated with the given cache name:

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