| Overview |  |
Copyright © 2019-2025 Fred Youhanaie
Version: 0.4.0
Authors: Fred Youhanaie (fyrlang@anydata.co.uk).
etsmgr is a simple application that can act as the heir for ETS
tables owned by other applications/processes. This allows the table
owners to crash and restart without loosing the data stored in the
table.
The implementation is inspired by the two blog posts from Steve Vinoski:
While adapting and embedding DeadZen's implementation , as referenced in the second article, would have sufficed, it was felt that a more generic and reusable approach would help future projects.
etsmgr can manage multiple ETS tables for multiple client
processes.
Multiple instances of etsmgr can co-exist on the same node by
starting the etsmgr applications with unique instance names.
An instance of etsmgr can run as a standalone application, or be
embedded within the supervision tree of another application. The
former allows a single server to look after tables belonging to
independent applications, while the latter will let applications to
have their own table manager.
A client can request etsmgr to take an ETS table under management
with the new_table/3,4 or add_table/2,3 calls. The client will
then use del_table/1,2 when table management is no longer
required.
Internally, an instance of the etsmgr server maintains a directory
of client pids and ETS table ids. We always use ETS table ids, even
for named ETS tables. The directory entries will be indexed by a
unique (within the instance) name supplied by the client.
If a client process with a table managed by etsmgr
crashes/terminates, the table will not be lost. Once the client
restarts, it can ask etsmgr for the ownership of the table.
If etsmgr crashes, and provided that the client has the
trap_exit flag set, it will receive an EXIT message with the
process id of etsmgr. This should trigger a mechanism within the
client to reregister its ETS table(s) with the new instance of
etsmgr as soon as the server restarts.
If the client does not set the trap_exit flag, then it will
terminate as soon as etsmgr terminates. However, not setting
trap_exit would be very unusual in an application that cares about
resilience!
It is up to the client software on how to wait and/or check for the
recovery of etsmgr. A set of helper functions,
wait4etsmgr/0,1,2, have been provided for a very simple scenario.
If a client terminates without deleting its ETS table(s), etsmgr
will inherit the managed client table(s) and keep the data alive
until the client restarts, or etsmgr itself terminates. Hence, it
is important for the client to delete the ETS table(s) prior to
normal termination.
etsmgr is already
running.
new_table, which
etsmgr the heir
ETS-TRANSFER message.
del_table, and deletes
the table.
etsmgr will receive the EXIT
message and update its internal state for the table(s) owned by
the client.
new_table for its table(s).
etsmgr will see that the table entry already exists, and subject
to some further checks, it will give the table to the client.
etsmgr does not distinguish between a client that has recovered
from a crash and a client that happens to have chosen the same
table name as an existing application, hence the above checks to
ensure there are no obvious conflicts.
etsmgr crashesetsmgr server that crashes, and restarts.
EXIT message, and should wait for the
etsmgr server to come back up.
etsmgr is back up, the client calls add_table, so that
etsmgr can continue managing the ETS table.
The application consists of the following components
| Module | Purpose |
|---|---|
etsmgr | client API module |
etsmgr_app | The main application for the standalone version |
etsmgr_srv | The main gen_server managing the ETS tables |
etsmgr_sup | The supervisor managing the etsmgr_srv server. |
For standalone mode, all four components are used. It is just a
matter of ensuring that the etsmgr application is started with or
before the client application.
For embedded mode, the main server, etsmgr_srv, can be put under
the supervision of the client application's supervisor. The
embedding can be done with or without the etsmgr_sup supervisor.
The client module, etsmgr, is used in both modes to communicate
with the table manager.
The main component of etsmgr is the gen_server,
etsmgr_srv. Below are the functions for accessing the services of
the manager. There are two variants of each function, one for the
unnamed instance, and one for a named instance.
etsmgr:new_table/3,4
This will create a new ETS table, and the manager will link to the
client process. We expect this call to be made when the client has
started, or restarted following a crash. In the latter case we would
expect the manager to be aware of the entry. On successful
completion, the client will be the owner of the ETS table, and
etsmgr_srv will be the heir.
etsmgr:add_table/2,3
This is similar to new_table, except it will not create a new ETS
table, but start managing an existing ETS table. We expect this call
when a client prefers to create the ETS table itself, or when the
manager has crashed and restarted and the client is reestablishing
the arrangement. On successful completion, the client will be the
owner of the ETS table, and etsmgr_srv will be the heir.
etsmgr:del_table/1,2This call is used when the client no longer needs a table to be managed, such as prior to termination. It will be up to the client to delete the ETS table.
etsmgr:wait4etsmgr/0,1,2
This is a helper function that can be used by the client to ensure
etsmgr is up and running, either at start up or following the
unexpected termination of etsmgr. The functions will block until
etsmgr is available. The caller can specify a specific etsmgr
instance and/or the polling interval when checking for the server.
etsmgr:info/0,1This will return the tables currently under management as a map of maps, or an empty map.
Generated by EDoc