ex_shards

v0.2.1

ex_shards v0.2.1 ExShards.Ext behaviour

This module extends the Shards API providing some extra functions.

To use the extended functions you have to do it through any of the modules in which these functions are injected: ExShards.Local or ExShards.Dist. Besides, you can use ExShards as well, since it is a wrapper on top of ExShards.Local and ExShards.Dist modules.

Examples 

# using ExShards
iex> ExShards.new :mytab
:mytab
iex> ExShards.set :mytab, a: 1, b: 2
:mytab
iex> ExShards.get :mytab, :a
1
iex> ExShards.fetch :mytab, :c
:error

# using ExShards.Local
iex> ExShards.Local.new :mytab
:mytab
iex> ExShards.Local.set :mytab, a: 1, b: 2
:mytab
iex> ExShards.Local.get :mytab, :a
1
iex> ExShards.Local.fetch :mytab, :c
:error

# using ExShards.Dist
iex> ExShards.Dist.new :mytab
:mytab
iex> ExShards.Dist.set :mytab, a: 1, b: 2
:mytab
iex> ExShards.Dist.get :mytab, :a
1
iex> ExShards.Dist.fetch :mytab, :c
:error

Link to this section Summary

Types

key()
state()
tab()
value()

Callbacks

drop(tab, arg1, state)

Drops the given keys from tab

fetch(tab, key, state)

Fetches the value for a specific key in the given tab

fetch!(tab, key, state)

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

get(tab, key, value, state)

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

get_and_update(tab, key, function, state)

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

get_and_update!(tab, key, function, state)

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

has_key?(tab, key, state)

Returns whether the given key exists in the given tab

keys(tab, state)

Returns all keys from tab

pop(tab, key, value, state)

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

put(tab, key, value, state)

Puts the given value under key in tab

put_new(tab, key, value, state)

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

remove(tab, key, state)

Removes the entry in tab for a specific key

set(tab, arg1, state)

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

take_and_drop(tab, arg1, state)

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

update(tab, key, value, function, state)

Updates the key in tab with the given function

update!(tab, key, function, state)

Updates key with the given function

update_elem(tab, key, term, state)

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

values(tab, state)

Returns all values from tab

Link to this section Types

Link to this type key() 
key() :: term
Link to this type tab() 
tab() :: atom
Link to this type value() 
value() :: term

Link to this section Callbacks

Link to this callback drop(tab, arg1, state) 
drop(tab, Enumerable.t, state) :: tab

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]
Link to this callback fetch(tab, key, state) 
fetch(tab, key, state) :: {:ok, value} | :error

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
Link to this callback fetch!(tab, key, state) 
fetch!(tab, key, state) :: value | no_return

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
Link to this callback get(tab, key, value, state) 
get(tab, key, value, state) :: value | [value]

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]
Link to this callback get_and_update(tab, key, function, state) 
get_and_update(tab, key, (value -> {get, update} | :pop), state) :: {get, update} when get: term, update: term

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}
Link to this callback get_and_update!(tab, key, function, state) 
get_and_update!(tab, key, (value -> {get, update} | :pop), state) ::
  {get, update} |
  no_return when get: term, update: term

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}
Link to this callback has_key?(tab, key, state) 
has_key?(tab, key, state) :: boolean

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
Link to this callback keys(tab, state) 
keys(tab, state) :: [key]

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.

Link to this callback pop(tab, key, value, state) 
pop(tab, key, value, state) :: value | [value]

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
Link to this callback put(tab, key, value, state) 
put(tab, key, value, state) :: tab

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
Link to this callback put_new(tab, key, value, state) 
put_new(tab, key, value, state) :: tab

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
Link to this callback remove(tab, key, state) 
remove(tab, key, state) :: tab

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
Link to this callback set(tab, arg1, state) 
set(tab, tuple | [tuple], state) :: tab

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
Link to this callback take_and_drop(tab, arg1, state) 
take_and_drop(tab, Enumerable.t, state) :: map

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
Link to this callback update(tab, key, value, function, state) 
update(tab, key, value, (value -> value), state) :: tab

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
Link to this callback update!(tab, key, function, state) 
update!(tab, key, (value -> value), state) ::
  tab |
  no_return

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
Link to this callback update_elem(tab, key, term, state) 
update_elem(tab, key, term, state) :: tab

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
Link to this callback values(tab, state) 
values(tab, state) :: [value]

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.