Adapter module for distributed or partitioned cache.

A distributed, or partitioned, cache is a clustered, fault-tolerant cache that has linear scalability. Data is partitioned among all the machines of the cluster. For fault-tolerance, partitioned caches can be configured to keep each piece of data on one or more unique machines within a cluster. This adapter in particular hasn’t fault-tolerance built-in, each piece of data is kept in a single node/machine (sharding), therefore, if a node fails, the data kept by this node won’t be available for the rest of the cluster.

This adapter depends on a local cache adapter, it adds a thin layer on top of it in order to distribute requests across a group of nodes, where is supposed the local cache is running already.

PG2 is used by the adapter to manage the cluster nodes. When the distributed cache is started in a node, it creates a PG2 group and joins it (the cache supervisor PID is joined to the group). Then, when a function is invoked, the adapter picks a node from the node list (using the PG2 group members), and then the function is executed on that node. In the same way, when the supervisor process of the distributed cache dies, the PID of that process is automatically removed from the PG2 group; this is why it’s recommended to use a distributed hashing algorithm for the node picker.

Features

• Support for Distributed Cache
• Support for Sharding; handled by Nebulex.Adapters.Dist.NodePicker
• Support for transactions via Erlang global name registration facility

Options

These options should be set in the config file and require recompilation in order to make an effect.

• :adapter - The adapter name, in this case, Nebulex.Adapters.Dist.

• :local - The Local Cache module. The value to this option should be Nebulex.Adapters.Local, unless you want to provide a custom local cache adapter.

• :node_picker - The module that implements the node picker interface Nebulex.Adapters.Dist.NodePicker. If this option is not set, the default implementation provided by the interface is used.

Example

Nebulex.Cache is the wrapper around the Cache. We can define the local and distributed cache as follows:

defmodule MyApp.LocalCache do
  use Nebulex.Cache, otp_app: :my_app, adapter: Nebulex.Adapters.Local
end

defmodule MyApp.DistCache do
  use Nebulex.Cache, otp_app: :my_app, adapter: Nebulex.Adapters.Dist
end

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

config :my_app, MyApp.LocalCache,
  n_shards: 2,
  gc_interval: 3600

config :my_app, MyApp.DistCache,
  local: MyApp.LocalCache

For more information about the usage, check Nebulex.Cache.

Extended API

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

pick_node/1

This function invokes Nebulex.Adapters.Dist.NodePicker.pick_node/2 internally.

MyCache.pick_node("mykey")

nodes/0

Returns the nodes that belongs to the caller Cache.

MyCache.nodes()

new_generation/1

Creates a new generation in all nodes that belongs to the caller Cache.

MyCache.new_generation()

Limitations

This adapter has some limitation for two functions: get_and_update/4 and update/5. They both have a parameter that is an anonymous function, and the anonymous function is compiled into the module where it was created, which means it necessarily doesn’t exists on remote nodes. To ensure they work as expected, you must provide functions from modules existing in all nodes of the group.