ExShards

This is a wrapper on top of ETS and Shards.

Shards is a simple library to scale-out ETS tables, which implements the same ETS API. Taking advantage of this, what ExShards does is provides a wrapper to use either ets or shards totally transparent.

Installation and Usage

To start playing with ex_shards you just have to follow these simple steps:

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

def deps do
  [{:ex_shards, "~> 0.1.0"}]
end

1. Because ex_shards uses shards, make sure that shards is started before your application:

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

Build

$ git clone https://github.com/cabol/ex_shards.git
$ cd ex_shards
$ mix deps.get && mix compile

Getting Started!

Start an Elixir console:

$ iex -S mix

Once into the Elixir console:

# create a table with default options
> ExShards.new :mytab
:mytab

> ExShards.insert :mytab, [k1: 1, k2: 2, k3: 3]
true

> for k <- [:k1, :k2, :k3] do
[{_, v}] = ExShards.lookup(:mytab, k)
v
end
[1, 2, 3]

> ExShards.delete :mytab, :k3
true
> ExShards.lookup :mytab, :k3
[]

# let's create another table
> ExShards.new :mytab2, [{:n_shards, 4}]
:mytab2

# start the observer so you can see how shards behaves
> :observer.start
:ok

As you might have noticed, it's extremely easy, such as you were using ETS API directly.

Distributed ExShards

Let's see how ExShards works in distributed fashion.

1. Let's start 3 Elixir consoles running ExShards:

Node a:

$ iex --sname a@localhost -S mix

Node b:

$ iex --sname b@localhost -S mix

Node c:

$ iex --sname c@localhost -S mix

2. Create a table with global scope (scope: :g) on each node and then join them.

> ExShards.new :mytab, scope: :g, nodes: [:b@localhost, :c@localhost]
:mytab

> ExShards.get_nodes :mytab
[:a@localhost, :b@localhost, :c@localhost]

3. Now ExShards cluster is ready, let's do some basic operations:

From node a:

> ExShards.insert :mytab, k1: 1, k2: 2
true

From node b:

> ExShards.insert :mytab, k3: 3, k4: 4
true

From node c:

> ExShards.insert :mytab, k5: 5, k6: 6
true

Now, from any of previous nodes:

> for k <- [:k1, :k2, :k3, :k4, :k5, :k6] do
[{_, v}] = ExShards.lookup(:mytab, k)
v
end
[1, 2, 3, 4, 5, 6]

All nodes should return the same result.

Let's do some deletions, from any node:

> ExShards.delete :mytab, :k6
true

From any node:

> ExShards.lookup :mytab, :k6
[]

Let's check again all:

> for k <- [:k1, :k2, :k3, :k4, :k5] do
[{_, v}] = ExShards.lookup(:mytab, k)
v
end
[1, 2, 3, 4, 5]

References

For more information about shards you can go to these links:

• shards: Original Erlang project.
• API Reference: Shards API Reference.
• Blog Post about Shards.

Copyright and License

Copyright (c) 2016 Carlos Andres Bolaños R.A.

ExShards source code is licensed under the MIT License.