Module espace_util

.

Copyright © (C) 2019, Fred Youhanaie

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

Description

A set of utility functions to support the rest of the espace modules.

When espace instances are started, a number of instance specific persistent_term entries are created. The pterm_* functions are used for handling these terms.

The persistent_term entries are expected to have the following format: {espace, Inst_name, Key}, where, Key identifies the particular espace item, such as server name to ETS table name, and Inst_name is the espace instance name, which is the same as the application name. For the unnamed instance the Inst_name is espace.

Data Types

espace_op()

espace_op() = in | rd | inp | rdp | out | eval

pt_key()

pt_key() = {espace, atom(), atom()}

Function Index

eval_out/1Conditionally evaluate a tuple and out the result to the unnamed instance.
eval_out/2Conditionally evaluate a tuple and out the result to a named instance.
inst_to_name/2 Convert an instance name to longer prefixed name.
opcount_counts/0Return the current counts for the unnamed instance as a map.
opcount_counts/1Return the current counts for a named instance as a map.
opcount_incr/1Increment a single espace op counter for the unnamed instance.
opcount_incr/2Increment a single espace op counter for a named instance.
opcount_new/0Create a new ops counter array for the unnamed instance.
opcount_new/1Create a new ops counter array for a named instance.
opcount_reset/0Reset all the op counters of the unnamed instance.
opcount_reset/1Reset all the op counters of a named instance.
pterm_erase/1Remove all the persistent terms for a given espace instance.
pterm_get/2Lookup the instance Key for Inst_name.
pterm_put/3Create an espace persistent term.
wait4etsmgr/4wait for etsmgr to (re)start, then ask it to manage our table.

Function Details

eval_out/1

eval_out(Tuple_in::tuple()) -> done

Conditionally evaluate a tuple and out the result to the unnamed instance.

See eval_out/2 for details.

eval_out/2

eval_out(Inst_name::atom(), Tuple_in::tuple()) -> done

Conditionally evaluate a tuple and out the result to a named instance.

The elements of the output tuple correspond to those of Tuple_in. If any of the elements of Tuple_in are recognized as function, then the corresponding output element will be the value of the function.

Two types of patterns are recognized as functions and are evaluated. A normal function expression of arity zero, fun () -> expr end. And, a tuple with two elements, a function expresion of arity N and a list of length N, N can be zero.

Any other pattern will move the element to the output tuple untouched.

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(espace_sup, aaa) will return espace_sup_aaa.

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

Instead of generating the full name each time this function is called, we perform the conversion once and cache the result as an entry in the persistent_term store. Each entry has the key {espace, Inst_name, Prefix}, e.g. {espace, aaa, espace_sup}, and the full name as value, e.g. espace_sup_aaa.

The use of persistent_term store will help speed up all named instances, including the short lived eval/2 processes.

opcount_counts/0

opcount_counts() -> #{espace_op() => integer()}

Return the current counts for the unnamed instance as a map.

See opcount_count/1 for details.

opcount_counts/1

opcount_counts(Inst_name::atom()) -> #{espace_op() => integer()}

Return the current counts for a named instance as a map.

opcount_incr/1

opcount_incr(Op::espace_op()) -> ok

Increment a single espace op counter for the unnamed instance.

See opcount_incr/1 for details.

opcount_incr/2

opcount_incr(Inst_name::atom(), Op::espace_op()) -> ok

Increment a single espace op counter for a named instance.

In the interested of keeping the code simple, the counter index of each op corresponds to the position of Op in the record tuple, which ranges from 2 to 7.

opcount_new/0

opcount_new() -> ok

Create a new ops counter array for the unnamed instance.

See opcount_new/1 for details.

opcount_new/1

opcount_new(Inst_name::atom()) -> ok

Create a new ops counter array for a named instance.

The array will have one counter per espace operation. The counters ref is saved in as a persistent term.

opcount_reset/0

opcount_reset() -> ok

Reset all the op counters of the unnamed instance.

See opcount_reset/1 for details.

opcount_reset/1

opcount_reset(Inst_name::atom()) -> ok

Reset all the op counters of a named instance.

This function has been provided for investigating an application.

pterm_erase/1

pterm_erase(Inst_name::atom()) -> [] | [{pt_key(), term()}]

Remove all the persistent terms for a given espace instance.

pterm_get/2

pterm_get(Inst_name::atom(), Key::atom()) -> undefined | term()

Lookup the instance Key for Inst_name.

If the persistence term does not exist, undefined is returned.

pterm_put/3

pterm_put(Inst_name::atom(), Key::atom(), Term::term()) -> ok

Create an espace persistent term.

wait4etsmgr/4

wait4etsmgr(Inst_name::atom(), X2::init | recover, Table_name::atom(), Table_opts::term()) -> {ok, pid(), ets:tab()} | {error, term()}

wait for etsmgr to (re)start, then ask it to manage our table.

There are two occassions where this function is called:

  1. init - start/restart of our gen_server that owns a table, in this case we do not have, or know of, the ETS table. So we ask etsmgr to create a new table using etsmgr:new_table/4. If etsmgr is already managing such a table that does not already belong to another process, then that table will be given to us.
  2. recover - recovery of the etsmgr server, in this case we ask etsmgr to start managing our ETS table.


Generated by EDoc