ets v0.8.0 ETS.Bag View Source

Module for creating and interacting with :ets tables of the type :bag and :duplicate_bag.

Bags contain "records" which are tuples. Bags are configured with a key position via the keypos: integer option. If not specified, the default key position is 1. The element of the tuple record at the key position is that records key. For example, setting the keypos to 2 means the key of an inserted record {:a, :b} is :b:

iex> {:ok, bag} = Bag.new(keypos: 2)
iex> Bag.add!(bag, {:a, :b})
iex> Bag.lookup(bag, :a)
{:ok, []}
iex> Bag.lookup(bag, :b)
{:ok, [{:a, :b}]}

When a record is added to the table with add_new will only add the record if a matching key doesn't already exist.

Examples

iex> {:ok, bag} = Bag.new()
iex> Bag.add_new!(bag, {:a, :b, :c})
iex> Bag.to_list!(bag)
[{:a, :b, :c}]
iex> Bag.add_new!(bag, {:d, :e, :f})
iex> Bag.to_list!(bag)
[{:d, :e, :f}, {:a, :b, :c}]
iex> Bag.add_new!(bag, {:a, :g, :h})
iex> Bag.to_list!(bag)
[{:d, :e, :f}, {:a, :b, :c}]

add and add_new take either a single tuple or a list of tuple records. When adding multiple records, they are added in an atomic an isolated manner. add_new doesn't add any records if any of the new keys already exist in the bag.

By default, Bags allow duplicate records (each element of the tuple record is identical). To prevent duplicate records, set the duplicate: false opt when creating the Bag (if you want to prevent duplicate keys, use an ETS.Set instead). Note that duplicate: false will increase the time it takes to add records as the table must be checked for duplicates prior to insert. duplicate: true maps to the :ets table type :duplicate_bag, duplicate: false maps to :bag.

Working with named tables

The functions on ETS.Bag require that you pass in an ETS.Bag as the first argument. In some design patterns, you may have the table name but an instance of an ETS.Bag may not be available to you. If this is the case, you should use wrap_existing/1 to turn your table name atom into an ETS.Bag. For example, a GenServer that handles writes within the server, but reads in the client process would be implemented like this:

defmodule MyExampleGenServer do
  use GenServer
  alias ETS.Bag

  # Client Functions

  def get_roles_for_user(user_id) do
    :my_role_table
    |> Bag.wrap_existing!()
    |> Bag.lookup!(user_id)
    |> Enum.map(&elem(&1, 1))
  end

  def add_role_for_user(user_id, role) do
    GenServer.call(__MODULE__, {:add_role_for_user, user_id, role})
  end

  # Server Functions

  def init(_) do
    {:ok, %{bag: Bag.new!(name: :my_role_table)}}
  end

  def handle_call({:add_role_for_user, user_id, role}, _from, %{bag: bag}) do
    Bag.add(bag, {user_id, role})
  end
end

Link to this section Summary

Types

bag_options()

t()

Functions

add(bag, record)

Adds tuple record or list of tuple records to table.

add!(bag, record_or_records)

Same as add/3 but unwraps or raises on error.

add_new(bag, record)

Same as add/2 but doesn't add any records if one of the given keys already exists.

add_new!(bag, record_or_records)

Same as add_new/2 but unwraps or raises on error.

delete(bag)

Deletes specified Bag.

delete(bag, key)

Deletes record with specified key in specified Bag.

delete!(bag)

Same as delete/1 but unwraps or raises on error.

delete!(bag, key)

Same as delete/2 but unwraps or raises on error.

delete_all(bag)

Deletes all records in specified Bag.

delete_all!(bag)

Same as delete_all/1 but unwraps or raises on error.

get_table(bag)

Returns underlying :ets table reference.

get_table!(bag)

Same as get_table/1 but unwraps or raises on error

has_key(bag, key)

Determines if specified key exists in specified bag.

has_key!(bag, key)

Same as has_key/2 but unwraps or raises on error.

info(bag, force_update \\ false)

Returns information on the bag.

info!(bag, force_update \\ false)

Same as info/1 but unwraps or raises on error.

lookup(bag, key)

Returns list of records with specified key.

lookup!(bag, key)

Same as lookup/3 but unwraps or raises on error.

lookup_element(bag, key, pos)

Returns list of elements in specified position of records with specified key.

lookup_element!(bag, key, pos)

Same as lookup_element/3 but unwraps or raises on error.

match(continuation)

Matches next bag of records from a match/3 or match/1 continuation.

match(bag, pattern)

Returns records in the Bag that match the specified pattern.

match(bag, pattern, limit)

Same as match/2 but limits number of results to the specified limit.

match!(continuation)

Same as match/1 but unwraps or raises on error.

match!(bag, pattern)

Same as match/2 but unwraps or raises on error.

match!(bag, pattern, limit)

Same as match/3 but unwraps or raises on error.

new(opts \\ [])

Creates new bag module with the specified options.

new!(opts \\ [])

Same as new/1 but unwraps or raises on error.

select(bag, spec)

Returns records in the specified Bag that match the specified match specification.

select!(bag, spec)

Same as select/2 but unwraps or raises on error.

select_delete(bag, spec)

Deletes records in the specified Bag that match the specified match specification.

select_delete!(bag, spec)

Same as select_delete/2 but unwraps or raises on error.

to_list(bag)

Returns contents of table as a list.

to_list!(bag)

Same as to_list/1 but unwraps or raises on error.

wrap_existing(table_identifier)

Wraps an existing :ets :bag or :duplicate_bag in a Bag struct.

wrap_existing!(table_identifier)

Same as wrap_existing/1 but unwraps or raises on error.

Link to this section Types

bag_options()

bag_options() :: [ETS.Base.option() | {:duplicate, boolean()}]

t()

t() :: %ETS.Bag{
  duplicate: boolean(),
  info: keyword(),
  table: ETS.table_reference()
}

Link to this section Functions

add(bag, record)

add(ETS.Bag.t(), tuple() | [tuple()]) :: {:ok, ETS.Bag.t()} | {:error, any()}

Adds tuple record or list of tuple records to table.

If Bag has duplicate: false, will overwrite duplicate records (full tuple must match, not just key).

Inserts multiple records in an atomic and isolated manner.

Examples

iex> {:ok, bag} = Bag.new()
iex> {:ok, _} = Bag.add(bag, [{:a, :b, :c}, {:d, :e, :f}])
iex> {:ok, _} = Bag.add(bag, {:a, :h, :i})
iex> {:ok, _} = Bag.add(bag, {:d, :x, :y})
iex> {:ok, _} = Bag.add(bag, {:d, :e, :f})
iex> Bag.to_list(bag)
{:ok, [{:d, :e, :f}, {:d, :x, :y}, {:d, :e, :f}, {:a, :b, :c}, {:a, :h, :i}]}

iex> {:ok, bag} = Bag.new(duplicate: false)
iex> {:ok, _} = Bag.add(bag, [{:a, :b, :c}, {:d, :e, :f}])
iex> {:ok, _} = Bag.add(bag, {:a, :h, :i})
iex> {:ok, _} = Bag.add(bag, {:d, :x, :y})
iex> {:ok, _} = Bag.add(bag, {:d, :e, :f}) # won't insert due to duplicate: false
iex> Bag.to_list(bag)
{:ok, [{:d, :e, :f}, {:d, :x, :y}, {:a, :b, :c}, {:a, :h, :i}]}

add!(bag, record_or_records)

add!(ETS.Bag.t(), tuple() | [tuple()]) :: ETS.Bag.t()

Same as add/3 but unwraps or raises on error.

add_new(bag, record)

add_new(ETS.Bag.t(), tuple() | [tuple()]) ::
  {:ok, ETS.Bag.t()} | {:error, any()}

Same as add/2 but doesn't add any records if one of the given keys already exists.

Examples

iex> bag = Bag.new!()
iex> {:ok, _} = Bag.add_new(bag, [{:a, :b, :c}, {:d, :e, :f}])
iex> {:ok, _} = Bag.add_new(bag, [{:a, :x, :y}, {:g, :h, :i}]) # skips due to duplicate :a key
iex> {:ok, _} = Bag.add_new(bag, {:d, :z, :zz}) # skips due to duplicate :d key
iex> Bag.to_list!(bag)
[{:d, :e, :f}, {:a, :b, :c}]

add_new!(bag, record_or_records)

add_new!(ETS.Bag.t(), tuple() | [tuple()]) :: ETS.Bag.t()

Same as add_new/2 but unwraps or raises on error.

delete(bag)

delete(ETS.Bag.t()) :: {:ok, ETS.Bag.t()} | {:error, any()}

Deletes specified Bag.

Examples

iex> {:ok, bag} = Bag.new()
iex> {:ok, _} = Bag.info(bag, true)
iex> {:ok, _} = Bag.delete(bag)
iex> Bag.info(bag, true)
{:error, :table_not_found}

delete(bag, key)

delete(ETS.Bag.t(), any()) :: {:ok, ETS.Bag.t()} | {:error, any()}

Deletes record with specified key in specified Bag.

Examples

iex> bag = Bag.new!()
iex> Bag.add(bag, {:a, :b, :c})
iex> Bag.delete(bag, :a)
iex> Bag.lookup!(bag, :a)
[]

delete!(bag)

delete!(ETS.Bag.t()) :: ETS.Bag.t()

Same as delete/1 but unwraps or raises on error.

delete!(bag, key)

delete!(ETS.Bag.t(), any()) :: ETS.Bag.t()

Same as delete/2 but unwraps or raises on error.

delete_all(bag)

delete_all(ETS.Bag.t()) :: {:ok, ETS.Bag.t()} | {:error, any()}

Deletes all records in specified Bag.

Examples

iex> bag = Bag.new!()
iex> bag
iex> |> Bag.add!({:a, :b, :c})
iex> |> Bag.add!({:b, :b, :c})
iex> |> Bag.add!({:c, :b, :c})
iex> |> Bag.to_list!()
[{:c, :b, :c}, {:b, :b, :c}, {:a, :b, :c}]
iex> Bag.delete_all(bag)
iex> Bag.to_list!(bag)
[]

delete_all!(bag)

delete_all!(ETS.Bag.t()) :: ETS.Bag.t()

Same as delete_all/1 but unwraps or raises on error.

get_table(bag)

get_table(ETS.Bag.t()) :: {:ok, ETS.table_reference()}

Returns underlying :ets table reference.

For use in functions that are not yet implemented. If you find yourself using this, please consider submitting a PR to add the necessary function to ETS.

Examples

iex> bag = Bag.new!(name: :my_ets_table)
iex> {:ok, table} = Bag.get_table(bag)
iex> info = :ets.info(table)
iex> info[:name]
:my_ets_table

get_table!(bag)

get_table!(ETS.Bag.t()) :: ETS.table_reference()

Same as get_table/1 but unwraps or raises on error

has_key(bag, key)

has_key(ETS.Bag.t(), any()) :: {:ok, boolean()} | {:error, any()}

Determines if specified key exists in specified bag.

Examples

iex> bag = Bag.new!()
iex> Bag.has_key(bag, :key)
{:ok, false}
iex> Bag.add(bag, {:key, :value})
iex> Bag.has_key(bag, :key)
{:ok, true}

has_key!(bag, key)

has_key!(ETS.Bag.t(), any()) :: boolean()

Same as has_key/2 but unwraps or raises on error.

info(bag, force_update \\ false)

info(ETS.Bag.t(), boolean()) :: {:ok, keyword()} | {:error, any()}

Returns information on the bag.

Second parameter forces updated information from ets, default (false) uses in-struct cached information. Force should be used when requesting size and memory.

Examples

iex> {:ok, bag} = Bag.new(duplicate: false, keypos: 3, read_concurrency: true, compressed: false)
iex> {:ok, info} = Bag.info(bag)
iex> info[:read_concurrency]
true
iex> {:ok, _} = Bag.add(bag, {:a, :b, :c})
iex> {:ok, info} = Bag.info(bag)
iex> info[:size]
0
iex> {:ok, info} = Bag.info(bag, true)
iex> info[:size]
1

info!(bag, force_update \\ false)

info!(ETS.Bag.t(), boolean()) :: keyword()

Same as info/1 but unwraps or raises on error.

lookup(bag, key)

lookup(ETS.Bag.t(), any()) :: {:ok, [tuple()]} | {:error, any()}

Returns list of records with specified key.

Examples

iex> Bag.new!()
iex> |> Bag.add!({:a, :b, :c})
iex> |> Bag.add!({:d, :e, :f})
iex> |> Bag.add!({:d, :e, :g})
iex> |> Bag.lookup(:d)
{:ok, [{:d, :e, :f}, {:d, :e, :g}]}

lookup!(bag, key)

lookup!(ETS.Bag.t(), any()) :: [tuple()]

Same as lookup/3 but unwraps or raises on error.

lookup_element(bag, key, pos)

lookup_element(ETS.Bag.t(), any(), non_neg_integer()) ::
  {:ok, [any()]} | {:error, any()}

Returns list of elements in specified position of records with specified key.

Examples

iex> Bag.new!()
iex> |> Bag.add!({:a, :b, :c})
iex> |> Bag.add!({:d, :e, :f})
iex> |> Bag.add!({:d, :h, :i})
iex> |> Bag.lookup_element(:d, 2)
{:ok, [:e, :h]}

lookup_element!(bag, key, pos)

lookup_element!(ETS.Bag.t(), any(), non_neg_integer()) :: [any()]

Same as lookup_element/3 but unwraps or raises on error.

match(continuation)

match(any()) :: {:ok, {[tuple()], any() | :end_of_table}} | {:error, any()}

Matches next bag of records from a match/3 or match/1 continuation.

Examples

iex> bag = Bag.new!()
iex> Bag.add!(bag, [{:a, :b, :c, :d}, {:e, :b, :f, :g}, {:h, :b, :i, :j}])
iex> {:ok, {results, continuation}} = Bag.match(bag, {:"$1", :b, :"$2", :_}, 2)
iex> results
[[:e, :f], [:a, :c]]
iex> {:ok, {records2, continuation2}} = Bag.match(continuation)
iex> records2
[[:h, :i]]
iex> continuation2
:end_of_table

match(bag, pattern)

match(ETS.Bag.t(), ETS.match_pattern()) :: {:ok, [tuple()]} | {:error, any()}

Returns records in the Bag that match the specified pattern.

For more information on the match pattern, see the erlang documentation

Examples

iex> Bag.new!()
iex> |> Bag.add!([{:a, :b, :c, :d}, {:e, :c, :f, :g}, {:h, :b, :i, :j}])
iex> |> Bag.match({:"$1", :b, :"$2", :_})
{:ok, [[:h, :i], [:a, :c]]}

match(bag, pattern, limit)

match(ETS.Bag.t(), ETS.match_pattern(), non_neg_integer()) ::
  {:ok, {[tuple()], any() | :end_of_table}} | {:error, any()}

Same as match/2 but limits number of results to the specified limit.

Examples

iex> bag = Bag.new!()
iex> Bag.add!(bag, [{:a, :b, :c, :d}, {:e, :b, :f, :g}, {:h, :b, :i, :j}])
iex> {:ok, {results, _continuation}} = Bag.match(bag, {:"$1", :b, :"$2", :_}, 2)
iex> results
[[:e, :f], [:a, :c]]

match!(continuation)

match!(any()) :: {[tuple()], any() | :end_of_table}

Same as match/1 but unwraps or raises on error.

match!(bag, pattern)

match!(ETS.Bag.t(), ETS.match_pattern()) :: [tuple()]

Same as match/2 but unwraps or raises on error.

match!(bag, pattern, limit)

match!(ETS.Bag.t(), ETS.match_pattern(), non_neg_integer()) ::
  {[tuple()], any() | :end_of_table}

Same as match/3 but unwraps or raises on error.

new(opts \\ [])

new(bag_options()) :: {:error, any()} | {:ok, ETS.Bag.t()}

Creates new bag module with the specified options.

Note that the underlying :ets table will be attached to the process that calls new and will be destroyed if that process dies.

Possible options:

name: when specified, creates a named table with the specified name
duplicate: when true, allows multiple identical records. (default true)
protection: :private, :protected, :public (default :protected)
heir: :none | {heir_pid, heir_data} (default :none)
keypos: integer (default 1)
read_concurrency: boolean (default false)
write_concurrency: boolean (default false)
compressed: boolean (default false)

Examples

iex> {:ok, bag} = Bag.new(duplicate: false, keypos: 3, read_concurrency: true, compressed: false)
iex> Bag.info!(bag)[:read_concurrency]
true

# Named :ets tables via the name keyword
iex> {:ok, bag} = Bag.new(name: :my_ets_table)
iex> Bag.info!(bag)[:name]
:my_ets_table

new!(opts \\ [])

new!(bag_options()) :: ETS.Bag.t()

Same as new/1 but unwraps or raises on error.

select(bag, spec)

select(ETS.Bag.t(), ETS.match_spec()) :: {:ok, [tuple()]} | {:error, any()}

Returns records in the specified Bag that match the specified match specification.

For more information on the match specification, see the erlang documentation

Examples

iex> Bag.new!()
iex> |> Bag.add!([{:a, :b, :c, :d}, {:e, :c, :f, :g}, {:h, :b, :i, :j}])
iex> |> Bag.select([{{:"$1", :b, :"$2", :_},[],[:"$$"]}])
{:ok, [[:h, :i], [:a, :c]]}

select!(bag, spec)

select!(ETS.Bag.t(), ETS.match_spec()) :: [tuple()]

Same as select/2 but unwraps or raises on error.

select_delete(bag, spec)

select_delete(ETS.Bag.t(), ETS.match_spec()) ::
  {:ok, non_neg_integer()} | {:error, any()}

Deletes records in the specified Bag that match the specified match specification.

For more information on the match specification, see the erlang documentation

Examples

iex> bag = Bag.new!()
iex> bag
iex> |> Bag.add!([{:a, :b, :c, :d}, {:e, :c, :f, :g}, {:h, :b, :c, :h}])
iex> |> Bag.select_delete([{{:"$1", :b, :"$2", :_},[{:"==", :"$2", :c}],[true]}])
{:ok, 2}
iex> Bag.to_list!(bag)
[{:e, :c, :f, :g}]

select_delete!(bag, spec)

select_delete!(ETS.Bag.t(), ETS.match_spec()) :: non_neg_integer()

Same as select_delete/2 but unwraps or raises on error.

to_list(bag)

to_list(ETS.Bag.t()) :: {:ok, [tuple()]} | {:error, any()}

Returns contents of table as a list.

Examples

iex> Bag.new!()
iex> |> Bag.add!({:a, :b, :c})
iex> |> Bag.add!({:d, :e, :f})
iex> |> Bag.add!({:d, :e, :f})
iex> |> Bag.to_list()
{:ok, [{:d, :e, :f}, {:d, :e, :f}, {:a, :b, :c}]}

to_list!(bag)

to_list!(ETS.Bag.t()) :: [tuple()]

Same as to_list/1 but unwraps or raises on error.

wrap_existing(table_identifier)

wrap_existing(ETS.table_identifier()) :: {:ok, ETS.Bag.t()} | {:error, any()}

Wraps an existing :ets :bag or :duplicate_bag in a Bag struct.

Examples

iex> :ets.new(:my_ets_table, [:bag, :named_table])
iex> {:ok, bag} = Bag.wrap_existing(:my_ets_table)
iex> Bag.info!(bag)[:name]
:my_ets_table

wrap_existing!(table_identifier)

wrap_existing!(ETS.table_identifier()) :: ETS.Bag.t()

Same as wrap_existing/1 but unwraps or raises on error.