Module etsmgr

Description
Function Index
Function Details

Authors: Fred Youhanaie (fyrlang@anydata.co.uk).

Description

These are the main functions for interacting with the etsmgr server.

If multiple instances of etsmgr are going be running concurrently, then they need to run as named instances. One unnamed instance can coexist with named instances, however, the unnamed instance is in fact a named instance with the fixed name of etsmgr.

All the functions, except one, have two variants, one for the unnamed instance of the server, and one for the named one.

An instance of etsmgr can run as a standalone application, or it can be embedded within the supervision tree of another application.

If etsmgr is running as an standalone application, then start/0,1 and stop/0,1 can be used to start and stop the application.

For the embedded mode, the etsmgr_srv server will need to be started from within the client's supervisor, either directly or via etsmgr_sup.

Function Index

add_table/2	Start managing an existing ETS table.
add_table/3	Start managing an existing ETS table.
del_table/1	Remove a table from the list of managed tables.
del_table/2	Remove a table from the list of managed tables.
info/0	Return the tables currently under management.
info/1	Return the tables currently under management.
inst_to_name/2	Convert an instance name to longer prefixed name.
new_table/3	Create and manage an ETS table.
new_table/4	Create and manage an ETS table.
start/0	Start the unnamed instance of the application.
start/1	Start a named instance of the application.
stop/0	Stop the unnamed instance of the application.
stop/1	Stop a named instance of the application.
wait4etsmgr/0	Block until the unnamed instance of the table manager has started.
wait4etsmgr/1	Block until an instance of the table manager has started.
wait4etsmgr/2	Block until an instance of the table manager has started.

Function Details

add_table/2

add_table(Table_name::atom(), Table_id::ets:tid()) -> {ok, pid(), ets:tid()} | {error, term()}

Start managing an existing ETS table.

This request is sent to the unnamed (aka etsmgr) instance.

See add_table/3 for details.

add_table/3

add_table(Inst_name::atom(), Table_name::atom(), Table_id::ets:tid()) -> {ok, pid(), ets:tid()} | {error, term()}

Start managing an existing ETS table.

This function is typically called when an application needs etsmgr to manage its ETS table(s), which already exist, either because the application prefers to create its own tables, or it has detected that the instance of etsmgr that was already managing the ETS tables has crashed and restarted.

Table_name uniquely identifies the table within this instance of etsmgr.

del_table/1

del_table(Table_name::atom()) -> ok | {error, term()}

Remove a table from the list of managed tables.

This request is sent to the unnamed (aka etsmgr) instance.

See del_table/2 for details.

del_table/2

del_table(Inst_name::atom(), Table_name::atom()) -> ok | {error, term}

Remove a table from the list of managed tables.

This function is called by a client when it no longer needs the ETS table to be managed by etsmgr. This is likely to be when the client is shutting down.

info/0

info() -> map()

Return the tables currently under management.

The request is sent to the unnamed (aka etsmgr) instance.

See info/1 for details.

info/1

info(Inst_name::atom()) -> map()

Return the tables currently under management.

A map of the table under management will be returned.

inst_to_name/2

inst_to_name(Prefix::atom(), Inst_name::atom()) -> atom()

Convert an instance name to longer prefixed name.

This is used for obtaining the instance specific server/table names. For example inst_to_name(etsmgr_srv, aaa) will return etsmgr_srv_aaa.

If the instance name is etsmgr, then the prefix is returned without an instance name suffix. For example inst_to_name(etsmgr_srv, etsmgr) will return etsmgr_srv.

new_table/3

new_table(Table_name::atom(), ETS_name::atom(), ETS_opts::list()) -> {ok, pid(), ets:tid()} | {error, term()}

Create and manage an ETS table.

The request is sent to the unnamed (aka etsmgr) instance.

See new_table/4 for details.

new_table/4

new_table(Inst_name::atom(), Table_name::atom(), ETS_name::atom(), ETS_opts::list()) -> {ok, pid(), ets:tid()} | {error, term()}

Create and manage an ETS table.

This function is called by client software on start up, or on crash/restart. etsmgr will check and create the table.

If Table_name is not known to etsmgr, a new ETS table will be created, the calling process will be the owner of the table, with etsmgr the heir, and etsmgr will be linked to the client process.

If Table_name is already known to the server, then either the client has restarted following a crash, or there is a name conflict with another application. In the case of a restart, etsmgr will behave as if this is a fresh start, but the table will not be created and no data will be lost. In the case of a name conflict, an error will be returned.

start/0

start() -> ok | {error, term()}

Start the unnamed instance of the application.

The unnamed instance is convenient as it can serve any application within the same node.

Internally the unnamed instance is in fact an instance with the name etsmgr.

start/1

start(Inst_name::atom()) -> ok | {error, term()}

Start a named instance of the application.

The instance name should be an atom. The name etsmgr is reserved for the "unnamed" instance. If the instance name is already in use, then the call will fail.

stop/0

stop() -> ok | {error, term()}

Stop the unnamed instance of the application.

The unnamed instance, or the instance known etsmgr, will be stopped. This is same as calling stop(etsmgr).

stop/1

stop(Inst_name::atom()) -> ok | {error, term()}

Stop a named instance of the application.

The named instance will be stopped. Any ETS table, and data within, where this instance is the owner, e.g. perhaps because the the main application has died, will be lost.

wait4etsmgr/0

wait4etsmgr() -> ok

Block until the unnamed instance of the table manager has started.

The function applies to the unnamed (aka etsmgr) instance.

See wait4etsmgr/1 for details.

wait4etsmgr/1

wait4etsmgr(Inst_name::atom() | integer()) -> ok

Block until an instance of the table manager has started.

The single argument may be an instance name or an interval (milliseconds) for the polling of the server. In either case, wait4etsmgr/2 is called with the default value for the missing argument. These are etsmgr for the instance name, and 1000 milliseconds for the polling interval.

wait4etsmgr/2

wait4etsmgr(Inst_name::atom(), Interval::integer()) -> ok

Block until an instance of the table manager has started.

This function is typically called when a client process detects that an instance of etsmgr has died.

This is a very simplistic function that will block, perhaps forever, until the unnamed instance of etsmgr is up and running.

Any sophisticated monitoring and restart scheme is beyond the scope of this module. Such functionality deserves its own module/application.

Generated by EDoc