Eternal

v1.0.3

Eternal v1.0.3 Eternal

This module implements bindings around what should be an eternal ETS table, or at least until you decide to terminate it. It works by using “bouncing” GenServers which come up as needed to provide an heir for the ETS table. It operates as follows:

  1. An ETS table is created with the provided name and options.
  2. Two GenServers are started, an owner and an heir. The ETS table is gifted to the owner, and has the heir set as the heir.
  3. If the owner crashes, the heir becomes the owner, and a new GenServer is started and assigned the role of heir.
  4. If an heir dies, we attempt to start a new GenServer and notify the owner so that they may change the assigned heir.
  5. The owner will check to see if the heir is alive once a minute in order to try and minimise situations where there is no heir. Note that this interval is configurable.

This means that there should always be an heir to your table, which should ensure that you don’t lose anything inside ETS.

Summary

Types

table()

Functions

heir(table)

Returns the heir of a given ETS table

new(name, ets_opts \\ [], opts \\ [])

Creates a new ETS table using the provided ets_opts

owner(table)

Returns the owner of a given ETS table

terminate(table)

Terminates both servers in charge of a given ETS table

Types 

table :: number | atom

Functions

heir(table)

Specs

heir(table :: table) :: pid | :undefined

Returns the heir of a given ETS table.

Examples

iex> Eternal.heir(:my_table)
#PID<0.134.0>
new(name, ets_opts \\ [], opts \\ [])

Specs

new(name :: atom, ets_opts :: Keyword.t, opts :: Keyword.t) :: table

Creates a new ETS table using the provided ets_opts.

These options are passed through as-is, with the exception of prepending the :public option. Seeing as you can’t execute inside the GenServers, your table will have to be public to be interacted with.

The result of the call to :ets.new/2 is the return value of this function.

Options

You may provide a third parameter containing Eternal options:

  • :monitor - determines which frequency will be used to check the state of the heir server. It defaults to a minute, and should be set in milliseconds. Setting this to false will disable this type of monitoring.
  • :quiet - by default, Eternal logs debug messages. Setting this to true will disable this logging.

Examples

iex> Eternal.new(:table1)
126995

iex> Eternal.new(:table2, [ :named_table ])
:table2

iex> Eternal.new(:table3, [ :named_table ], [ quiet: true ])
:table3
owner(table)

Specs

owner(table :: table) :: pid | :undefined

Returns the owner of a given ETS table.

Examples

iex> Eternal.owner(:my_table)
#PID<0.132.0>
terminate(table)

Specs

terminate(table :: table) :: :ok

Terminates both servers in charge of a given ETS table.

Note: this will terminate your ETS table.

Examples

iex> Eternal.terminate(:my_table)
:ok