nimble_ets v0.1.0 NimbleETS View Source

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.

Link to this section Summary

Functions

Creates new ETS table(s) wrapper(s) based on definitions passed as a parameter.

Link to this section Functions

Creates new ETS table(s) wrapper(s) based on definitions passed as a parameter.

Examples:

NimbleETS.new(MyApp.MyExistingModule)
NimbleETS.new([{MyApp.WithOptions, [:bag]}, MyApp.ToCreate])

For the full list of options please refer to :ets.new/2 documentation.