NimbleETS is a very thin simple ETS wrapper, simplifying the trivial usage of ETS as key-value store. It is not intended to replicate :ets module functionality by any mean. It might be used as a drop-in to avoid process-based Agent as key-value store.

It exposes only CRUD functionality of ETS, alongside with Access behaviour.

Built on top of :ets, it’s not distributed. Tables created are sets; public and named by default. This might be changed by passing {table_name, options} tuple instead of just table name to the initializer (see below.)

Usage

There are two ways NimbleETS might be used: as a standalone module, or as a module extension.

Standalone usage

{:ok, pid} = NimbleETS.Tables.start_link()
NimbleETS.new(MyApp.MyModuleToBeGenerated)
MyApp.MyModuleToBeGenerated.ets_put(:foo, 42)
#⇒ %MyApp.MyModuleToBeGenerated{table: MyApp.MyModuleToBeGenerated}

MyApp.MyModuleToBeGenerated.ets_get(:foo, 42)
#⇒ 42

term = %{data: MyApp.MyModuleToBeGenerated.ets_put(:value, 42)}
update_in(term, [:data, :value], fn _ -> "👍" end)
get_in(term, [:data, :value])
#⇒ "👍"
GenServer.stop(pid)

The table is actually managed by the NimbleETS application, so it won’t be destroyed if the process called NimbleETS.new/1 exits.

Module

defmodule MyApp.MyModuleBackedByTable do
  use NimbleETS
end
MyApp.MyModuleBackedByTable.ets_put(:foo, 42)
MyApp.MyModuleBackedByTable.ets_get(:foo)
#⇒ 42
MyApp.MyModuleBackedByTable.ets_del(:foo)
MyApp.MyModuleBackedByTable.ets_get(:foo)
#⇒ 42

One might override ets_table_name/0 in the module to change the name of the table.

Interface exported

NimbleETS exports the simplest possible interface for CRUD on purpose. Whether one needs more sophisticated :ets operations, it’s still possible through %MyApp.MyModuleBackedByTable{}.table (yes, it’s a struct underneath.) The latter holds the reference to the respective :ets table.

@doc "Updates the value in the table under the key passed"
@spec ets_put(key :: term(), value :: term()) :: NimbleETS.t()

@doc "Retrieves the value from the table stored under the key passed"
@spec ets_get(key :: term(), default :: any()) :: term()

@doc "Deletes the value from the table stored under the key passed"
@spec ets_del(key :: term()) :: NimbleETS.t()

@doc "Returns all the values from the table"
@spec ets_all() :: list()

Access behaviour

Modules produced / updated by NimbleETS do support Access behaviour.

Envío support

Modules produced / updated by NimbleETS do send broadcast messages on both :update and :delete actions. See Envío documentation on how to subscribe to them.

Each message is sent to two channels: :all (all the updates managed by NimbleCSV) and the channel with the name equal to the name of the table updated.