ex_shards

v0.2.1

ex_shards v0.2.1 ExShards.Dist

Distributed Shards API – This is the equivalent module to shards_dist.

Despite we have the ExShards.Dist module, it is not recomended to use it directly. The idea is to use the ExShards wrapper instead. This module is used internaly by ExShards when you create a table with global scope (scope: :g) – let’s see the example below.

Example

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.

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

iex> 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:

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

From node b:

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

From node c:

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

Now, from any of previous nodes:

iex> 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:

iex> ExShards.delete :mytab, :k6
true

From any node:

iex> ExShards.lookup :mytab, :k6
[]

Let’s check again all:

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

Link to this section Summary

Functions

definitions()
delete(Elixir.arg1)
delete(Elixir.arg1, Elixir.arg2, Elixir.arg3)
delete_all_objects(Elixir.arg1, Elixir.arg2)
delete_object(Elixir.arg1, Elixir.arg2, Elixir.arg3)
drop(tab, keys, state \\ ExShards.State.new())

Drops the given keys from tab

fetch(tab, key, state \\ ExShards.State.new())

Fetches the value for a specific key in the given tab

fetch!(tab, key, state \\ ExShards.State.new())

Fetches the value for a specific key in the given tab, erroring out if tab doesn’t contain key

file2tab(Elixir.arg1)
file2tab(Elixir.arg1, Elixir.arg2)
foldl(Elixir.arg1, Elixir.arg2, Elixir.arg3, Elixir.arg4)
foldr(Elixir.arg1, Elixir.arg2, Elixir.arg3, Elixir.arg4)
get(tab, key, default \\ nil, state \\ ExShards.State.new())

Gets the value or a list of values for a specific key in tab

get_and_update(tab, key, fun, state \\ ExShards.State.new())

Gets the value from key and updates it, all in one pass

get_and_update!(tab, key, fun, state \\ ExShards.State.new())

Gets the value from key and updates it. Raises if there is no key

get_nodes(Elixir.arg1)
has_key?(tab, key, state \\ ExShards.State.new())

Returns whether the given key exists in the given tab

info(Elixir.arg1, Elixir.arg2)
info(Elixir.arg1, Elixir.arg2, Elixir.arg3)
insert(Elixir.arg1, Elixir.arg2, Elixir.arg3)
insert_new(Elixir.arg1, Elixir.arg2, Elixir.arg3)
join(Elixir.arg1, Elixir.arg2)
keys(tab, state \\ ExShards.State.new())

Returns all keys from tab

leave(Elixir.arg1, Elixir.arg2)
lookup(Elixir.arg1, Elixir.arg2, Elixir.arg3)
lookup_element(Elixir.arg1, Elixir.arg2, Elixir.arg3, Elixir.arg4)
match(Elixir.arg1, Elixir.arg2, Elixir.arg3)
match_delete(Elixir.arg1, Elixir.arg2, Elixir.arg3)
match_object(Elixir.arg1, Elixir.arg2, Elixir.arg3)
member(Elixir.arg1, Elixir.arg2, Elixir.arg3)
pop(tab, key, default \\ nil, state \\ ExShards.State.new())

Returns and removes the value(s) associated with key in tab

put(tab, key, value, state \\ ExShards.State.new())

Puts the given value under key in tab

put_new(tab, key, value, state \\ ExShards.State.new())

Puts the given value under key unless the entry key already exists in tab

remove(tab, key, state \\ ExShards.State.new())

Removes the entry in tab for a specific key

rename(Elixir.arg1, Elixir.arg2, Elixir.arg3)
select(Elixir.arg1, Elixir.arg2, Elixir.arg3)
select_count(Elixir.arg1, Elixir.arg2, Elixir.arg3)
select_delete(Elixir.arg1, Elixir.arg2, Elixir.arg3)
select_reverse(Elixir.arg1, Elixir.arg2, Elixir.arg3)
set(tab, obj_or_objs, state \\ ExShards.State.new())

This function is analogous to :shards.insert/2,3, but it returns the table name instead of true

tab2file(Elixir.arg1, Elixir.arg2, Elixir.arg3)
tab2file(Elixir.arg1, Elixir.arg2, Elixir.arg3, Elixir.arg4)
tab2list(Elixir.arg1, Elixir.arg2)
tabfile_info(Elixir.arg1)
take(Elixir.arg1, Elixir.arg2, Elixir.arg3)
take_and_drop(tab, keys, state \\ ExShards.State.new())

Drops the given keys from tab and returns a map with all dropped key-value pairs

update(tab, key, initial, fun, state \\ ExShards.State.new())

Updates the key in tab with the given function

update!(tab, key, fun, state \\ ExShards.State.new())

Updates key with the given function

update_counter(Elixir.arg1, Elixir.arg2, Elixir.arg3, Elixir.arg4)
update_counter(Elixir.arg1, Elixir.arg2, Elixir.arg3, Elixir.arg4, Elixir.arg5)
update_elem(tab, key, element_spec, state \\ ExShards.State.new())

This function is analogous to :shards.update_element/3,4, but it returns the table name instead of true

update_element(Elixir.arg1, Elixir.arg2, Elixir.arg3, Elixir.arg4)
values(tab, state \\ ExShards.State.new())

Returns all values from tab

Link to this section Functions

Link to this function delete(Elixir.arg1)
Link to this function delete(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function delete_all_objects(Elixir.arg1, Elixir.arg2)
Link to this function delete_object(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function drop(tab, keys, state \\ ExShards.State.new())

Drops the given keys from tab.

If keys contains keys that are not in tab, they’re simply ignored.

Examples 

iex> ExShards.set(:mytab, a: 1, b: 2, a: 3, c: 4)
iex> ExShards.drop(:mytab, [:a, :b, :e])
:mytab
iex> ExShards.keys(:mytab)
[:c]

Callback implementation for ExShards.Ext.drop/3.

Link to this function fetch(tab, key, state \\ ExShards.State.new())

Fetches the value for a specific key in the given tab.

If tab contains the given key with value value, then {:ok, value} is returned. If tab doesn’t contain key, :error is returned.

Keep in mind that only one result is returned always, in case of :bag or :duplicate bag, only the first match is returned.

Examples 

iex> ExShards.fetch(:mytab, :a)
{:ok, 1}
iex> ExShards.fetch(:mytab, :b)
:error

Callback implementation for ExShards.Ext.fetch/3.

Link to this function fetch!(tab, key, state \\ ExShards.State.new())

Fetches the value for a specific key in the given tab, erroring out if tab doesn’t contain key.

If tab contains the given key, the corresponding value is returned. If tab doesn’t contain key, a KeyError exception is raised.

Keep in mind that only one result is returned always, in case of :bag or :duplicate bag, only the first match is returned.

Examples 

iex> ExShards.fetch!(:mytab, :a)
1
iex> ExShards.fetch!(:mytab, :b)
** (KeyError) key :b not found in: :mytab

Callback implementation for ExShards.Ext.fetch!/3.

Link to this function file2tab(Elixir.arg1)
Link to this function file2tab(Elixir.arg1, Elixir.arg2)
Link to this function foldl(Elixir.arg1, Elixir.arg2, Elixir.arg3, Elixir.arg4)
Link to this function foldr(Elixir.arg1, Elixir.arg2, Elixir.arg3, Elixir.arg4)
Link to this function get(tab, key, default \\ nil, state \\ ExShards.State.new())

Gets the value or a list of values for a specific key in tab.

Return possibilities:

  • value – If key is present in tab with value value (only one element matches).
  • [value] – In case of multiple elements matches with the key key. This behaviour is expected when the table is either a :bag or a :duplicate_bag.
  • default – If key is not present in tab (default is nil unless specified otherwise).

Examples 

iex> ExShards.get(:mytab, :a)
nil
iex> :mytab |> ExShards.put(:a, 1) |> ExShards.get(:a)
1
iex> ExShards.get(:mytab, :b)
nil
iex> ExShards.get(:mytab, :b, 3)
3
iex> :mytab |> ExShards.set(c: 2, c: 3) |> ExShards.get(:c)
[2, 3]

Callback implementation for ExShards.Ext.get/4.

Link to this function get_and_update(tab, key, fun, state \\ ExShards.State.new())

Gets the value from key and updates it, all in one pass.

fun is called with the current value under key in tab (or nil if key is not present in tab) and must return a two-element tuple: the “get” value (the retrieved value, which can be operated on before being returned) and the new value to be stored under key. fun may also return :pop, which means the current value shall be removed from tab and returned (making this function behave like pop(tab, key).

The returned value is a tuple with the “get” value returned by fun and the new updated value under key.

Examples 

iex> :mytab |> ExShards.put(:a, 1) |> ExShards.get(:a)
1

iex> ExShards.get_and_update(:mytab, :a, fn current_value ->
...>   {current_value, "new value!"}
...> end)
{1, "new value!"}

iex> ExShards.get_and_update(:mytab, :b, fn current_value ->
...>   {current_value, "new value!"}
...> end)
{nil, "new value!"}

iex> ExShards.get_and_update(:mytab, :a, fn _ -> :pop end)
{"new value!", nil}

iex> ExShards.get_and_update(:mytab, :b, fn _ -> :pop end)
{nil, nil}

Callback implementation for ExShards.Ext.get_and_update/4.

Link to this function get_and_update!(tab, key, fun, state \\ ExShards.State.new())

Gets the value from key and updates it. Raises if there is no key.

Behaves exactly like get_and_update/3, but raises a KeyError exception if key is not present in tab.

Examples 

iex> :mytab |> ExShards.put(:a, 1) |> ExShards.get(:a)
1

iex> ExShards.get_and_update(:mytab, :a, fn current_value ->
...>   {current_value, "new value!"}
...> end)
{1, "new value!"}

iex> ExShards.get_and_update(:mytab, :b, fn current_value ->
...>   {current_value, "new value!"}
...> end)
** (KeyError) key :b not found in: :mytab

iex> ExShards.get_and_update(:mytab, :a, fn _ -> :pop end)
{"new value!", nil}

Callback implementation for ExShards.Ext.get_and_update!/4.

Link to this function get_nodes(Elixir.arg1)
Link to this function has_key?(tab, key, state \\ ExShards.State.new())

Returns whether the given key exists in the given tab.

Examples 

iex> ExShards.has_key?(:mytab, :a)
true
iex> ExShards.has_key?(:mytab, :b)
false

Callback implementation for ExShards.Ext.has_key?/3.

Link to this function info(Elixir.arg1, Elixir.arg2)
Link to this function info(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function insert(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function insert_new(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function join(Elixir.arg1, Elixir.arg2)
Link to this function keys(tab, state \\ ExShards.State.new())

Returns all keys from tab.

Examples 

iex> ExShards.set(:mytab, a: 1, b: 2, c: 3)
:mytab
iex> ExShards.keys(:mytab)
[:a, :b, :c]

WARNING: This is an expensive operation, try DO NOT USE IT IN PROD.

Callback implementation for ExShards.Ext.keys/2.

Link to this function leave(Elixir.arg1, Elixir.arg2)
Link to this function lookup(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function lookup_element(Elixir.arg1, Elixir.arg2, Elixir.arg3, Elixir.arg4)
Link to this function match(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function match_delete(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function match_object(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function member(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function pop(tab, key, default \\ nil, state \\ ExShards.State.new())

Returns and removes the value(s) associated with key in tab.

Return possibilities:

  • value – If key is present in tab with value value.
  • [value] – In case of multiple matches with the key key. This behaviour is expected when the table is either a :bag or a :duplicate_bag.
  • default – If key is not present in tab.

Examples 

iex> :mytab |> ExShards.set(a: 1, b: 2, a: 2) |> ExShards.pop(:a)
[1, 2]
iex> ExShards.pop(:mytab, :b)
2
iex> ExShards.pop(:mytab, :c)
nil
iex> ExShards.pop(:mytab, :c, 3)
3

Callback implementation for ExShards.Ext.pop/4.

Link to this function put(tab, key, value, state \\ ExShards.State.new())

Puts the given value under key in tab.

Examples 

iex> :mytab |> ExShards.put(:a, 1) |> ExShards.fetch!(:a)
1
iex> :mytab |> ExShards.put(:a, 3) |> ExShards.fetch!(:a)
3

Callback implementation for ExShards.Ext.put/4.

Link to this function put_new(tab, key, value, state \\ ExShards.State.new())

Puts the given value under key unless the entry key already exists in tab.

Examples 

iex> ExShards.put_new(:mytab, :a, 1) |> ExShards.fetch!(:a)
1
iex> ExShards.put_new(:mytab, :a, 3) |> ExShards.fetch!(:a)
1

Callback implementation for ExShards.Ext.put_new/4.

Link to this function remove(tab, key, state \\ ExShards.State.new())

Removes the entry in tab for a specific key.

If the key does not exist, returns tab unchanged.

Examples 

iex> :mytab |> ExShards.put(:a, 1) |> ExShards.fetch!(:a)
1
iex> ExShards.delete(:mytab, :a) |> ExShards.get(:a)
nil
iex> ExShards.delete(:mytab, :b) |> ExShards.get(:b)
nil

Callback implementation for ExShards.Ext.remove/3.

Link to this function rename(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function select(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function select_count(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function select_delete(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function select_reverse(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function set(tab, obj_or_objs, state \\ ExShards.State.new())

This function is analogous to :shards.insert/2,3, but it returns the table name instead of true.

Examples 

iex> :mytab |> ExShards.set(a:1, b: 2) |> ExShards.get(:a)
1
iex> :mytab |> ExShards.set(b: 3) |> ExShards.get(:b)
3

Callback implementation for ExShards.Ext.set/3.

Link to this function tab2file(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function tab2file(Elixir.arg1, Elixir.arg2, Elixir.arg3, Elixir.arg4)
Link to this function tab2list(Elixir.arg1, Elixir.arg2)
Link to this function tabfile_info(Elixir.arg1)
Link to this function take(Elixir.arg1, Elixir.arg2, Elixir.arg3)
Link to this function take_and_drop(tab, keys, state \\ ExShards.State.new())

Drops the given keys from tab and returns a map with all dropped key-value pairs.

If keys contains keys that are not in tab, they’re simply ignored.

Examples 

iex> ExShards.set(:mytab, a: 1, b: 2, a: 3, c: 4)
iex> ExShards.take_and_drop(:mytab, [:a, :b, :e])
%{a: [1, 3], b: 2}
iex> ExShards.get(:mytab, :a)
nil

Callback implementation for ExShards.Ext.take_and_drop/3.

Link to this function update(tab, key, initial, fun, state \\ ExShards.State.new())

Updates the key in tab with the given function.

If key is present in tab with value value, fun is invoked with argument value and its result is used as the new value of key. If key is not present in tab, initial is inserted as the value of key.

This functions only works for :set or :ordered_set tables.

Examples 

iex> :mytab |> ExShards.put(:a, 1) |> ExShards.update(:a, 13, &(&1 * 2)) |> ExShards.get(:a)
2
iex> :mytab |> ExShards.update(:b, 11, &(&1 * 2)) |> ExShards.get(:b)
11

Callback implementation for ExShards.Ext.update/5.

Link to this function update!(tab, key, fun, state \\ ExShards.State.new())

Updates key with the given function.

If key is present in tab with value value, fun is invoked with argument value and its result is used as the new value of key. If key is not present in tab, a KeyError exception is raised.

This functions only works for :set or :ordered_set tables.

Examples 

iex> :mytab |> ExShards.put(:a, 1) |> ExShards.update!(:a, &(&1 * 2)) |> ExShards.get(:a)
2
iex> :mytab |> ExShards.update(:b, &(&1 * 2))
** (KeyError) key :b not found in: :mytab

Callback implementation for ExShards.Ext.update!/4.

Link to this function update_counter(Elixir.arg1, Elixir.arg2, Elixir.arg3, Elixir.arg4)
Link to this function update_counter(Elixir.arg1, Elixir.arg2, Elixir.arg3, Elixir.arg4, Elixir.arg5)
Link to this function update_elem(tab, key, element_spec, state \\ ExShards.State.new())

This function is analogous to :shards.update_element/3,4, but it returns the table name instead of true.

This functions only works for :set or :ordered_set tables.

Examples 

iex> :mytab |> ExShards.put(:a, 1) |> ExShards.update_elem(:a, {2, 11}) |> ExShards.get(:a)
11
iex> :mytab |> ExShards.update_elem(:b, {2, 22}) |> ExShards.get(:b)
nil

Callback implementation for ExShards.Ext.update_elem/4.

Link to this function update_element(Elixir.arg1, Elixir.arg2, Elixir.arg3, Elixir.arg4)
Link to this function values(tab, state \\ ExShards.State.new())

Returns all values from tab.

Examples 

iex> ExShards.set(:mytab, a: 1, b: 2, c: 3)
:mytab
iex> ExShards.values(:mytab)
[:a, :b, :c]

WARNING: This is an expensive operation, try DO NOT USE IT IN PROD.

Callback implementation for ExShards.Ext.values/2.