GEN_ETS - GEN(eric) Erlang Term Storage

Copyright (c) 2011-2016 by Joseph Wayne Norton

Authors: Joseph Wayne Norton ([email protected]).

GEN_ETS is an generic wrapper for Erlang Term Storage with a callback interface for a backend implementation.

GEN_ETS is not intended to be an exact clone of ETS. The currently supported ETS APIs are:

• all/0

• delete/1

• delete/2

• delete_all_objects/1

• first/1

• foldl/3

• foldr/3

• info/1 only a subset of items

• info/2 only a subset of items

• insert/2

• insert_new/2

• last/1

• lookup/2

• lookup_element/3

• match/1

• match/2

• match/3

• match_delete/2

• match_object/1

• match_object/2

• match_object/3

• member/2

• new/2

• next/2

• prev/2

• select/1

• select/2

• select/3

• select_count/2

• select_delete/2

• select_reverse/1

• select_reverse/2

• select_reverse/3

• tab2list/1

In particular, GEN_ETS differs from ETS in the following ways:

• The name of a table can be any Erlang term.

• All APIs require a namespace. A namespace must be a unique, reserved atom. Due to limitiations of the current implementation of GEN_ETS, this reserved atom is used to register a local named process and to create a named ets table.

  Caution

  Choose your application's namespace(s) wisely.

For convience and testing purposes, GEN_ETS provides a default namespace wrapper and backend implementation based on ETS. See gen_ets and gen_ets_impl_ets for further details.

This repository is experimental in nature - use at your own risk and please contribute if you find GEN_ETS useful.

Quick Start Recipe

To download and build the gen_ets application in one shot, please follow this recipe:

$ mkdir working-directory-name
$ cd working-directory-name
$ git clone https://github.com/norton/gen-ets.git gen_ets
$ cd gen_ets
$ make deps clean compile

OR if QuickCheck is available then follow this recipe:

$ mkdir working-directory-name
$ cd working-directory-name
$ git clone https://github.com/norton/gen-ets.git gen_ets
$ cd gen_ets
$ make deps clean compile-for-eqc
$ (cd .qc; erl -smp +A 5 -pz ../deps/qc/ebin)

1> qc_statem_gen_ets:qc_run(500).
  :
  :
OK, passed 500 tests

100.0% {1,attempts}

3.81% {insert_new,2,ok}
3.60% {match_object,2,ok}
3.57% {select,2,ok}
3.57% {foldl,3,ok}
3.55% {foldr,3,ok}
3.53% {lookup,2,ok}
3.52% {select_count,2,ok}
3.52% {all,1,ok}
3.52% {match_delete,2,ok}
3.51% {select31,3,ok}
3.50% {delete,1,ok}
3.45% {match31,3,ok}
3.44% {member,2,ok}
3.43% {insert,2,ok}
3.39% {new,3,ok}
3.39% {match_object31,3,ok}
3.39% {match,2,ok}
3.35% {select_reverse,2,ok}
3.35% {tab2list,1,ok}
3.34% {select_delete,2,ok}
3.34% {new,2,ok}
3.33% {delete_all_objects,1,ok}
3.27% {delete,2,ok}
3.25% {select_reverse31,3,ok}
3.24% {last,1,ok}
3.23% {first,1,ok}
2.95% {lookup_element,3,{error,badarg}}
2.35% {prev,2,ok}
1.98% {next,2,ok}
1.40% {prev,2,{error,badarg}}
1.26% {next,2,{error,badarg}}
0.68% {lookup_element,3,ok}
true

OR if PropEr is available then follow this recipe:

$ mkdir working-directory-name
$ cd working-directory-name
$ git clone https://github.com/norton/gen-ets.git gen_ets
$ cd gen_ets
$ make deps clean compile-for-proper
$ (cd .qc; erl -smp +A 5 -pz ../deps/qc/ebin)

1> qc_statem_gen_ets:qc_run(500).
  :
  :
OK: Passed 500 test(s).

8% {new,2,ok}
3% {all,1,ok}
3% {select31,3,ok}
3% {match_object31,3,ok}
3% {first,1,ok}
3% {match_delete,2,ok}
3% {select_count,2,ok}
3% {delete,1,ok}
3% {foldr,3,ok}
3% {select_reverse31,3,ok}
3% {match_object,2,ok}
3% {foldl,3,ok}
3% {select_delete,2,ok}
3% {select,2,ok}
3% {insert_new,2,ok}
3% {delete,2,ok}
3% {insert,2,ok}
3% {delete_all_objects,1,ok}
3% {new,3,ok}
3% {lookup,2,ok}
3% {match,2,ok}
3% {member,2,ok}
3% {match31,3,ok}
3% {select_reverse,2,ok}
3% {tab2list,1,ok}
2% {last,1,ok}
2% {lookup_element,3,{error,badarg}}
2% {next,2,ok}
1% {prev,2,ok}
1% {next,2,{error,badarg}}
1% {prev,2,{error,badarg}}
0% {lookup_element,3,ok}
true

Documentation

Where should I start?

This README is the only bit of documentation right now.

The QC (a.k.a. QuickCheck) tests underneath the "tests/qc" directory should be helpful for understanding the specification and behavior of ETS and GEN_ETS. NIF-based implementations.

What is ETS and DETS?

ETS and DETS are Erlang/OTP's standard library modules for Erlang term storage. ETS is a memory-based implementation. DETS is a disk-based implementation.

See http://www.erlang.org/doc/man/ets.html and http://www.erlang.org/doc/man/dets.html for further details.

Tools

For further information and help for related tools, please refer to the following links:

• Erlang - http://www.erlang.org/

  • R15 or newer, 17.0 has been tested most recently

• Git - http://git-scm.com/

  • Git 1.5.4 or newer, Git 1.9.2 has been tested most recently

• GitHub - https://github.com

Roadmap

N/A

Modules

gen_ets

gen_ets_impl_ets

gen_ets_lib

gen_ets_ns

gen_ets_reg