Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ets(3)			   Erlang Module Definition			ets(3)

NAME
       ets - Built-in term storage.

DESCRIPTION
       This  module  is	an interface to	the Erlang built-in term storage BIFs.
       These provide the ability to store very large quantities	of data	in  an
       Erlang  runtime	system,	 and to	have constant access time to the data.
       (In the case of ordered_set, see	below, access time is proportional  to
       the logarithm of	the number of stored objects.)

       Data  is	 organized as a	set of dynamic tables, which can store tuples.
       Each table is created by	a process. When	the  process  terminates,  the
       table  is automatically destroyed. Every	table has access rights	set at
       creation.

       Tables are divided into four different types,  set,  ordered_set,  bag,
       and  duplicate_bag. A set or ordered_set	table can only have one	object
       associated with each key. A bag or duplicate_bag	table  can  have  many
       objects associated with each key.

   Note:
       The number of tables stored at one Erlang node used to be limited. This
       is no longer the	case (except by	memory usage).	The  previous  default
       limit was about 1400 tables and could be	increased by setting the envi-
       ronment variable	ERL_MAX_ETS_TABLES or the command line option  +e  be-
       fore  starting  the Erlang runtime system. This hard limit has been re-
       moved, but it is	currently useful to set	the ERL_MAX_ETS_TABLES anyway.
       It  should  be  set  to	an approximate of the maximum amount of	tables
       used. This since	an internal table for named tables is sized using this
       value. If large amounts of named	tables are used	and ERL_MAX_ETS_TABLES
       hasn't been increased, the performance of named table lookup  will  de-
       grade.

       Notice  that  there is no automatic garbage collection for tables. Even
       if there	are no references to a table from any process, it is not auto-
       matically  destroyed  unless the	owner process terminates. To destroy a
       table explicitly, use function  delete/1.  The  default	owner  is  the
       process	that created the table.	To transfer table ownership at process
       termination, use	option heir or call give_away/3.

       Some implementation details:

	 * In the current implementation, every	object insert and look-up  op-
	   eration results in a	copy of	the object.

	 * '$end_of_table' is not to be	used as	a key, as this atom is used to
	   mark	the end	of the table when using	functions first/1 and next/2.

       Notice the subtle difference  between  matching	and  comparing	equal,
       which is	demonstrated by	table types set	and ordered_set:

	 * Two	Erlang	terms  match if	they are of the	same type and have the
	   same	value, so that 1 matches 1, but	not 1.0	(as 1.0	is  a  float()
	   and not an integer()).

	 * Two	Erlang terms compare equal if they either are of the same type
	   and value, or if both are numeric types  and	 extend	 to  the  same
	   value, so that 1 compares equal to both 1 and 1.0.

	 * The ordered_set works on the	Erlang term order and no defined order
	   exists between an integer() and a float() that extends to the  same
	   value.  Hence the key 1 and the key 1.0 are regarded	as equal in an
	   ordered_set table.

FAILURE
       The functions in	this module exits with reason badarg if	 any  argument
       has the wrong format, if	the table identifier is	invalid, or if the op-
       eration is denied because of table access  rights  (protected  or  pri-
       vate).

CONCURRENCY
       This  module  provides  some limited support for	concurrent access. All
       updates to single objects are guaranteed	to be  both  atomic  and  iso-
       lated.  This means that an updating operation to	a single object	either
       succeeds	or fails completely without any	effect (atomicity) and that no
       intermediate results of the update can be seen by other processes (iso-
       lation).	Some functions that update many	objects	state that  they  even
       guarantee atomicity and isolation for the entire	operation. In database
       terms the isolation level can be	seen as	"serializable",	as if all iso-
       lated  operations  are  carried	out serially, one after	the other in a
       strict order.

TABLE TRAVERSAL
       There are different ways	to traverse through the	objects	of a table.

	 * Single-step traversal one key at at time,  using  first/1,  next/2,
	   last/1 and prev/2.

	 * Search    with    simple   match   patterns,	  using	  match/1/2/3,
	   match_delete/2 and match_object/1/2/3.

	 * Search with more powerful match specifications, using select/1/2/3,
	   select_count/2,  select_delete/2,  select_replace/2	and select_re-
	   verse/1/2/3.

	 * Table conversions, using tab2file/2/3 and tab2list/1.

       None of these ways of table traversal will guarantee a consistent table
       snapshot	 if  the table is also updated during the traversal. Moreover,
       traversals not done in a	safe way, on tables where keys are inserted or
       deleted	during	the  traversal,	 may yield the following undesired ef-
       fects:

	 * Any key may be missed.

	 * Any key may be found	more than once.

	 * The traversal may fail with badarg exception	if keys	are deleted.

       A table traversal is safe if either

	 * the table is	of type	ordered_set.

	 * the entire table traversal is done within one ETS function call.

	 * function safe_fixtable/2 is used to keep the	table  fixated	during
	   the entire traversal.

       Traversals  using  match	 and select functions may not need to scan the
       entire table depending on how the key is	 specified.  A	match  pattern
       with  a fully bound key (without	any match variables) will optimize the
       operation to a single key lookup	without	any table  traversal  at  all.
       For  ordered_set	a partially bound key will limit the traversal to only
       scan a subset of	the table based	on term	order. A partially  bound  key
       is either a list	or a tuple with	a prefix that is fully bound. Example:

       1> T = ets:new(t,[ordered_set]),	ets:insert(T, {"555-1234", "John Smith"}).
       true
       2> %% Efficient search of all with area code 555
       2> ets:match(T,{[$5,$5,$5,$- |'$1'],'$2'}).
       [["1234","John Smith"]]

MATCH SPECIFICATIONS
       Some  of	 the  functions	 use  a	match specification, match_spec. For a
       brief explanation, see select/2.	For a detailed description,  see  sec-
       tion  Match Specifications in Erlang in ERTS User's Guide.

DATA TYPES
       access()	= public | protected | private

       continuation()

	      Opaque  continuation  used  by  select/1,3,  select_reverse/1,3,
	      match/1,3, and match_object/1,3.

       match_spec() = [{match_pattern(), [term()], [term()]}]

	      A	match specification, see above.

       comp_match_spec()

	      A	compiled match specification.

       match_pattern() = atom()	| tuple()

       tab() = atom() |	tid()

       tid()

	      A	table identifier, as returned by new/2.

       type() =	set | ordered_set | bag	| duplicate_bag

EXPORTS
       all() ->	[Tab]

	      Types:

		 Tab = tab()

	      Returns a	list of	all tables at the node.	Named tables are spec-
	      ified  by	their names, unnamed tables are	specified by their ta-
	      ble identifiers.

	      There is no guarantee of consistency in the returned  list.  Ta-
	      bles   created  or  deleted  by  other  processes	 "during"  the
	      ets:all()	call either are	or are not included in the list.  Only
	      tables created/deleted before ets:all() is called	are guaranteed
	      to be included/excluded.

       delete(Tab) -> true

	      Types:

		 Tab = tab()

	      Deletes the entire table Tab.

       delete(Tab, Key)	-> true

	      Types:

		 Tab = tab()
		 Key = term()

	      Deletes all objects with key Key from table Tab.

       delete_all_objects(Tab) -> true

	      Types:

		 Tab = tab()

	      Delete all objects in the	ETS table Tab. The operation is	 guar-
	      anteed to	be atomic and isolated.

       delete_object(Tab, Object) -> true

	      Types:

		 Tab = tab()
		 Object	= tuple()

	      Delete  the  exact object	Object from the	ETS table, leaving ob-
	      jects with the same key but other	differences (useful  for  type
	      bag).  In	a duplicate_bag	table, all instances of	the object are
	      deleted.

       file2tab(Filename) -> {ok, Tab} | {error, Reason}

	      Types:

		 Filename = file:name()
		 Tab = tab()
		 Reason	= term()

	      Reads a file produced by tab2file/2 or  tab2file/3  and  creates
	      the corresponding	table Tab.

	      Equivalent to file2tab(Filename, []).

       file2tab(Filename, Options) -> {ok, Tab}	| {error, Reason}

	      Types:

		 Filename = file:name()
		 Tab = tab()
		 Options = [Option]
		 Option	= {verify, boolean()}
		 Reason	= term()

	      Reads  a	file  produced by tab2file/2 or	tab2file/3 and creates
	      the corresponding	table Tab.

	      The only supported option	is {verify,boolean()}. If verification
	      is  turned  on  (by specifying {verify,true}), the function uses
	      whatever information is present in the file to assert  that  the
	      information  is  not  damaged. How this is done depends on which
	      extended_info was	written	using tab2file/3.

	      If no extended_info is present in	the file and {verify,true}  is
	      specified, the number of objects written is compared to the size
	      of the original table when the dump was started. This  can  make
	      verification fail	if the table was public	and objects were added
	      or removed while the table was dumped to	file.  To  avoid  this
	      problem,	either do not verify files dumped while	updated	simul-
	      taneously	 or  use  option  {extended_info,  [object_count]}  to
	      tab2file/3,  which  extends the information in the file with the
	      number of	objects	written.

	      If verification is turned	on and the file	was written  with  op-
	      tion  {extended_info,  [md5sum]},	reading	the file is slower and
	      consumes radically more CPU time than otherwise.

	      {verify,false} is	the default.

       first(Tab) -> Key | '$end_of_table'

	      Types:

		 Tab = tab()
		 Key = term()

	      Returns the first	key Key	in table Tab. For an  ordered_set  ta-
	      ble,  the	 first key in Erlang term order	is returned. For other
	      table types, the first key according to the  internal  order  of
	      the table	is returned. If	the table is empty, '$end_of_table' is
	      returned.

	      To find subsequent keys in the table, use	next/2.

       foldl(Function, Acc0, Tab) -> Acc1

	      Types:

		 Function = fun((Element :: term(), AccIn) -> AccOut)
		 Tab = tab()
		 Acc0 =	Acc1 = AccIn = AccOut =	term()

	      Acc0 is returned if the table is empty. This function is similar
	      to lists:foldl/3.	The table elements are traversed in an unspec-
	      ified order, except for ordered_set tables, where	they are  tra-
	      versed first to last.

	      If  Function  inserts objects into the table, or another process
	      inserts objects into the table, those objects can	(depending  on
	      key ordering) be included	in the traversal.

       foldr(Function, Acc0, Tab) -> Acc1

	      Types:

		 Function = fun((Element :: term(), AccIn) -> AccOut)
		 Tab = tab()
		 Acc0 =	Acc1 = AccIn = AccOut =	term()

	      Acc0 is returned if the table is empty. This function is similar
	      to lists:foldr/3.	The table elements are traversed in an unspec-
	      ified  order, except for ordered_set tables, where they are tra-
	      versed last to first.

	      If Function inserts objects into the table, or  another  process
	      inserts  objects into the	table, those objects can (depending on
	      key ordering) be included	in the traversal.

       from_dets(Tab, DetsTab) -> true

	      Types:

		 Tab = tab()
		 DetsTab = dets:tab_name()

	      Fills an already created ETS table with the objects in  the  al-
	      ready opened Dets	table DetsTab. Existing	objects	in the ETS ta-
	      ble are kept unless overwritten.

	      If any of	the tables does	not exist or the  Dets	table  is  not
	      open, a badarg exception is raised.

       fun2ms(LiteralFun) -> MatchSpec

	      Types:

		 LiteralFun = function()
		 MatchSpec = match_spec()

	      Pseudo  function that by a parse_transform translates LiteralFun
	      typed as parameter in the	function call to  a  match  specifica-
	      tion.  With  "literal"  is  meant	that the fun must textually be
	      written as the parameter of the function,	it cannot be held in a
	      variable that in turn is passed to the function.

	      The  parse  transform is provided	in the ms_transform module and
	      the source must include file ms_transform.hrl in STDLIB for this
	      pseudo  function to work.	Failing	to include the hrl file	in the
	      source results in	a runtime error, not a compile time error. The
	      include	file   is   easiest   included	by  adding  line  -in-
	      clude_lib("stdlib/include/ms_transform.hrl").  to	  the	source
	      file.

	      The  fun is very restricted, it can take only a single parameter
	      (the object to match): a sole variable or	a tuple. It  must  use
	      the  is_ guard tests. Language constructs	that have no represen-
	      tation in	a match	specification (if, case, receive, and  so  on)
	      are not allowed.

	      The return value is the resulting	match specification.

	      Example:

	      1> ets:fun2ms(fun({M,N}) when N >	3 -> M end).
	      [{{'$1','$2'},[{'>','$2',3}],['$1']}]

	      Variables	from the environment can be imported, so that the fol-
	      lowing works:

	      2> X=3.
	      3
	      3> ets:fun2ms(fun({M,N}) when N >	X -> M end).
	      [{{'$1','$2'},[{'>','$2',{const,3}}],['$1']}]

	      The imported variables are replaced by match specification const
	      expressions, which is consistent with the	static scoping for Er-
	      lang funs. However, local	or global function calls cannot	be  in
	      the guard	or body	of the fun. Calls to built-in match specifica-
	      tion functions is	of course allowed:

	      4> ets:fun2ms(fun({M,N}) when N >	X, my_fun(M) ->	M end).
	      Error: fun containing local Erlang function calls
	      ('my_fun'	called in guard) cannot	be translated into match_spec
	      {error,transform_error}
	      5> ets:fun2ms(fun({M,N}) when N >	X, is_atom(M) -> M end).
	      [{{'$1','$2'},[{'>','$2',{const,3}},{is_atom,'$1'}],['$1']}]

	      As shown by the example, the function can	 be  called  from  the
	      shell also. The fun must be literally in the call	when used from
	      the shell	as well.

	  Warning:
	      If the parse_transform is	not applied to	a  module  that	 calls
	      this pseudo function, the	call fails in runtime (with a badarg).
	      The ets module exports a function	with  this  name,  but	it  is
	      never  to	be called except when using the	function in the	shell.
	      If the parse_transform is	properly applied by  including	header
	      file  ms_transform.hrl,  compiled	code never calls the function,
	      but the function call is replaced	by a literal match  specifica-
	      tion.

	      For more information, see	ms_transform(3).

       give_away(Tab, Pid, GiftData) ->	true

	      Types:

		 Tab = tab()
		 Pid = pid()
		 GiftData = term()

	      Make process Pid the new owner of	table Tab. If successful, mes-
	      sage {'ETS-TRANSFER',Tab,FromPid,GiftData} is sent  to  the  new
	      owner.

	      The  process Pid must be alive, local, and not already the owner
	      of the table. The	calling	process	must be	the table owner.

	      Notice that this function	does not affect	option heir of the ta-
	      ble.  A  table  owner can, for example, set heir to itself, give
	      the table	away, and then get it back if the receiver terminates.

       i() -> ok

	      Displays information about all ETS tables	on a terminal.

       i(Tab) -> ok

	      Types:

		 Tab = tab()

	      Browses table Tab	on a terminal.

       info(Tab) -> InfoList | undefined

	      Types:

		 Tab = tab()
		 InfoList = [InfoTuple]
		 InfoTuple =
		     {compressed, boolean()} |
		     {heir, pid() | none} |
		     {id, tid()} |
		     {keypos, integer()	>= 1} |
		     {memory, integer()	>= 0} |
		     {name, atom()} |
		     {named_table, boolean()} |
		     {node, node()} |
		     {owner, pid()} |
		     {protection, access()} |
		     {size, integer() >= 0} |
		     {type, type()} |
		     {write_concurrency, boolean()} |
		     {read_concurrency,	boolean()}

	      Returns information about	table Tab as a list of tuples. If  Tab
	      has  the correct type for	a table	identifier, but	does not refer
	      to an existing ETS table,	undefined is returned. If Tab  is  not
	      of the correct type, a badarg exception is raised.

		{compressed, boolean()}:
		  Indicates if the table is compressed.

		{heir, pid() | none}:
		  The pid of the heir of the table, or none if no heir is set.

		{id,tid()}:
		  The table identifier.

		{keypos, integer() _= 1}:
		  The key position.

		{memory, integer() _= 0:
		  The number of	words allocated	to the table.

		{name, atom()}:
		  The table name.

		{named_table, boolean()}:
		  Indicates if the table is named.

		{node, node()}:
		  The  node where the table is stored. This field is no	longer
		  meaningful, as tables	cannot be accessed from	other nodes.

		{owner,	pid()}:
		  The pid of the owner of the table.

		{protection,access()}:
		  The table access rights.

		{size, integer() _= 0:
		  The number of	objects	inserted in the	table.

		{type,type()}:
		  The table type.

		{read_concurrency, boolean()}:
		  Indicates whether the	table uses read_concurrency or not.

		{write_concurrency, boolean()}:
		  Indicates whether the	table uses write_concurrency.

       info(Tab, Item) -> Value	| undefined

	      Types:

		 Tab = tab()
		 Item =
		     compressed	|
		     fixed |
		     heir |
		     id	|
		     keypos |
		     memory |
		     name |
		     named_table |
		     node |
		     owner |
		     protection	|
		     safe_fixed	|
		     safe_fixed_monotonic_time |
		     size |
		     stats |
		     type |
		     write_concurrency |
		     read_concurrency
		 Value = term()

	      Returns the information associated with Item for table  Tab,  or
	      returns  undefined  if Tab does not refer	an existing ETS	table.
	      If Tab is	not of the correct type, or if Item is not one of  the
	      allowed values, a	badarg exception is raised.

	      In  addition  to	the {Item,Value} pairs defined for info/1, the
	      following	items are allowed:

		* Item=fixed, Value=boolean()

		  Indicates if the table is fixed by any process.

		*

		  Item=safe_fixed|safe_fixed_monotonic_time,  Value={Fixation-
		  Time,Info}|false

		  If  the table	has been fixed using safe_fixtable/2, the call
		  returns a tuple where	FixationTime is	the time when the  ta-
		  ble  was first fixed by a process, which either is or	is not
		  one of the processes it is fixed by now.

		  The format and value of FixationTime depends on Item:

		  safe_fixed:
		    FixationTime corresponds to	the  result  returned  by  er-
		    lang:timestamp/0 at	the time of fixation. Notice that when
		    the	system uses single or multi time warp modes  this  can
		    produce  strange  results, as the use of safe_fixed	is not
		    time  warp	safe.	Time   warp   safe   code   must   use
		    safe_fixed_monotonic_time instead.

		  safe_fixed_monotonic_time:
		    FixationTime  corresponds  to  the	result returned	by er-
		    lang:monotonic_time/0 at the time of fixation. The use  of
		    safe_fixed_monotonic_time is  time warp safe.

		  Info is a possibly empty lists of tuples {Pid,RefCount}, one
		  tuple	for every process the table is fixed by	now.  RefCount
		  is  the value	of the reference counter and it	keeps track of
		  how many times the table has been fixed by the process.

		  If the table never has been fixed, the call returns false.

		* Item=stats, Value=tuple()

		  Returns internal  statistics	about  set,  bag,  and	dupli-
		  cate_bag  tables  on	an  internal  format  used by OTP test
		  suites. Not for production use.

       init_table(Tab, InitFun)	-> true

	      Types:

		 Tab = tab()
		 InitFun = fun((Arg) ->	Res)
		 Arg = read | close
		 Res = end_of_input | {Objects :: [term()], InitFun} | term()

	      Replaces the existing objects of table Tab with objects  created
	      by  calling the input function InitFun, see below. This function
	      is provided for compatibility with the dets module,  it  is  not
	      more efficient than filling a table by using insert/2.

	      When  called with	argument read, the function InitFun is assumed
	      to return	end_of_input when there	is no more input, or {Objects,
	      Fun},  where Objects is a	list of	objects	and Fun	is a new input
	      function.	Any other value	Value is returned as an	error  {error,
	      {init_fun,  Value}}. Each	input function is called exactly once,
	      and if an	error occur, the last function is called with argument
	      close, the reply of which	is ignored.

	      If  the table type is set	and more than one object exists	with a
	      given key, one of	the objects is chosen. This is not necessarily
	      the  last	 object	 with the given	key in the sequence of objects
	      returned by the input functions. This holds also for  duplicated
	      objects stored in	tables of type bag.

       insert(Tab, ObjectOrObjects) -> true

	      Types:

		 Tab = tab()
		 ObjectOrObjects = tuple() | [tuple()]

	      Inserts the object or all	of the objects in list ObjectOrObjects
	      into table Tab.

		* If the table type is set and the key of the inserted objects
		  matches  the	key of any object in the table,	the old	object
		  is replaced.

		* If the table type is ordered_set and the key of the inserted
		  object compares equal	to the key of any object in the	table,
		  the old object is replaced.

		* If the list contains more than one object with matching keys
		  and the table	type is	set, one is inserted, which one	is not
		  defined. The same holds for table type  ordered_set  if  the
		  keys compare equal.

	      The  entire  operation  is guaranteed to be atomic and isolated,
	      even when	a list of objects is inserted.

       insert_new(Tab, ObjectOrObjects)	-> boolean()

	      Types:

		 Tab = tab()
		 ObjectOrObjects = tuple() | [tuple()]

	      Same as insert/2 except that instead of overwriting objects with
	      the  same	 key  (for  set	or ordered_set)	or adding more objects
	      with keys	already	existing in the	 table	(for  bag  and	dupli-
	      cate_bag), false is returned.

	      If  ObjectOrObjects is a list, the function checks every key be-
	      fore inserting anything. Nothing is  inserted  unless  all  keys
	      present  in  the	list are absent	from the table.	Like insert/2,
	      the entire operation is guaranteed to be atomic and isolated.

       is_compiled_ms(Term) -> boolean()

	      Types:

		 Term =	term()

	      Checks if	a term is a valid compiled  match  specification.  The
	      compiled	match  specification is	an opaque datatype that	cannot
	      be sent between Erlang nodes or be stored	on disk.  Any  attempt
	      to  create an external representation of a compiled match	speci-
	      fication results in an empty binary (____).

	      Examples:

	      The following expression yields true::

	      ets:is_compiled_ms(ets:match_spec_compile([{'_',[],[true]}])).

	      The following expressions	yield false, as	variable  Broken  con-
	      tains a compiled match specification that	has passed through ex-
	      ternal representation:

	      MS = ets:match_spec_compile([{'_',[],[true]}]),
	      Broken = binary_to_term(term_to_binary(MS)),
	      ets:is_compiled_ms(Broken).

	  Note:
	      The reason for not having	an external representation of compiled
	      match specifications is performance. It can be subject to	change
	      in future	releases, while	this interface	remains	 for  backward
	      compatibility.

       last(Tab) -> Key	| '$end_of_table'

	      Types:

		 Tab = tab()
		 Key = term()

	      Returns the last key Key according to Erlang term	order in table
	      Tab of type ordered_set. For other table types, the function  is
	      synonymous to first/1. If	the table is empty, '$end_of_table' is
	      returned.

	      To find preceding	keys in	the table, use prev/2.

       lookup(Tab, Key)	-> [Object]

	      Types:

		 Tab = tab()
		 Key = term()
		 Object	= tuple()

	      Returns a	list of	all objects with key Key in table Tab.

		* For tables of	type set, bag, or duplicate_bag, an object  is
		  returned  only  if  the specified key	matches	the key	of the
		  object in the	table.

		* For tables of	type ordered_set, an object is returned	if the
		  specified  key compares equal	to the key of an object	in the
		  table.

	      The difference is	the same as between =:=	and ==.

	      As an example, one can insert an object with integer()  1	 as  a
	      key in an	ordered_set and	get the	object returned	as a result of
	      doing a lookup/2 with float() 1.0	as the key to search for.

	      For tables of type set or	ordered_set, the function returns  ei-
	      ther  the	empty list or a	list with one element, as there	cannot
	      be more than one object with the same key. For  tables  of  type
	      bag  or  duplicate_bag, the function returns a list of arbitrary
	      length.

	      Notice that the time order of object  insertions	is  preserved;
	      the first	object inserted	with the specified key is the first in
	      the resulting list, and so on.

	      Insert and lookup	times in tables	of type	set, bag,  and	dupli-
	      cate_bag are constant, regardless	of the table size. For the or-
	      dered_set	datatype, time is proportional to the  (binary)	 loga-
	      rithm of the number of objects.

       lookup_element(Tab, Key,	Pos) ->	Elem

	      Types:

		 Tab = tab()
		 Key = term()
		 Pos = integer() >= 1
		 Elem =	term() | [term()]

	      For a table Tab of type set or ordered_set, the function returns
	      the Pos:th element of the	object with key	Key.

	      For tables of type bag or	duplicate_bag, the functions returns a
	      list with	the Pos:th element of every object with	key Key.

	      If no object with	key Key	exists,	the function exits with	reason
	      badarg.

	      The difference between set, bag, and duplicate_bag on one	 hand,
	      and  ordered_set	on  the	 other,	 regarding  the	 fact that or-
	      dered_set	view keys as equal when	they compare equal whereas the
	      other  table types regard	them equal only	when they match, holds
	      for lookup_element/3.

       match(Continuation) -> {[Match],	Continuation} |	'$end_of_table'

	      Types:

		 Match = [term()]
		 Continuation =	continuation()

	      Continues	a match	started	with match/3. The next	chunk  of  the
	      size  specified in the initial match/3 call is returned together
	      with a new Continuation, which can be used in  subsequent	 calls
	      to this function.

	      When  there are no more objects in the table, '$end_of_table' is
	      returned.

       match(Tab, Pattern) -> [Match]

	      Types:

		 Tab = tab()
		 Pattern = match_pattern()
		 Match = [term()]

	      Matches the objects in table Tab against pattern Pattern.

	      A	pattern	is a term that can contain:

		* Bound	parts (Erlang terms)

		* '_' that matches any Erlang term

		* Pattern variables '$N', where	N=0,1,...

	      The function returns a list with one element for	each  matching
	      object,  where  each element is an ordered list of pattern vari-
	      able bindings, for example:

	      6> ets:match(T, '$1'). % Matches every object in table
	      [[{rufsen,dog,7}],[{brunte,horse,5}],[{ludde,dog,5}]]
	      7> ets:match(T, {'_',dog,'$1'}).
	      [[7],[5]]
	      8> ets:match(T, {'_',cow,'$1'}).
	      []

	      If the key is specified in the pattern, the match	is very	 effi-
	      cient. If	the key	is not specified, that is, if it is a variable
	      or an underscore,	the entire table must be searched. The	search
	      time can be substantial if the table is very large.

	      For  tables of type ordered_set, the result is in	the same order
	      as in a first/next traversal.

       match(Tab, Pattern, Limit) ->
		{[Match], Continuation}	| '$end_of_table'

	      Types:

		 Tab = tab()
		 Pattern = match_pattern()
		 Limit = integer() >= 1
		 Match = [term()]
		 Continuation =	continuation()

	      Works like match/2, but returns only a limited (Limit) number of
	      matching	objects.  Term Continuation can	then be	used in	subse-
	      quent calls to match/1 to	get the	next  chunk  of	 matching  ob-
	      jects. This is a space-efficient way to work on objects in a ta-
	      ble, which is faster than	traversing the table object by	object
	      using first/1 and	next/2.

	      If the table is empty, '$end_of_table' is	returned.

	      Use  safe_fixtable/2  to guarantee safe traversal	for subsequent
	      calls to match/1.

       match_delete(Tab, Pattern) -> true

	      Types:

		 Tab = tab()
		 Pattern = match_pattern()

	      Deletes all objects that match pattern Pattern from  table  Tab.
	      For a description	of patterns, see match/2.

       match_object(Continuation) ->
		       {[Object], Continuation}	| '$end_of_table'

	      Types:

		 Object	= tuple()
		 Continuation =	continuation()

	      Continues	a match	started	with match_object/3. The next chunk of
	      the size specified in the	initial	 match_object/3	 call  is  re-
	      turned  together	with  a	new Continuation, which	can be used in
	      subsequent calls to this function.

	      When there are no	more objects in	the table, '$end_of_table'  is
	      returned.

       match_object(Tab, Pattern) -> [Object]

	      Types:

		 Tab = tab()
		 Pattern = match_pattern()
		 Object	= tuple()

	      Matches  the objects in table Tab	against	pattern	Pattern. For a
	      description of patterns, see match/2.  The  function  returns  a
	      list of all objects that match the pattern.

	      If  the key is specified in the pattern, the match is very effi-
	      cient. If	the key	is not specified, that is, if it is a variable
	      or  an underscore, the entire table must be searched. The	search
	      time can be substantial if the table is very large.

	      For tables of type ordered_set, the result is in the same	 order
	      as in a first/next traversal.

       match_object(Tab, Pattern, Limit) ->
		       {[Object], Continuation}	| '$end_of_table'

	      Types:

		 Tab = tab()
		 Pattern = match_pattern()
		 Limit = integer() >= 1
		 Object	= tuple()
		 Continuation =	continuation()

	      Works  like  match_object/2,  but	only returns a limited (Limit)
	      number of	matching objects. Term Continuation can	then  be  used
	      in  subsequent  calls to match_object/1 to get the next chunk of
	      matching objects.	This is	a space-efficient way to work  on  ob-
	      jects  in	a table, which is faster than traversing the table ob-
	      ject by object using first/1 and next/2.

	      If the table is empty, '$end_of_table' is	returned.

	      Use safe_fixtable/2 to guarantee safe traversal  for  subsequent
	      calls to match_object/1.

       match_spec_compile(MatchSpec) ->	CompiledMatchSpec

	      Types:

		 MatchSpec = match_spec()
		 CompiledMatchSpec = comp_match_spec()

	      Transforms a match specification into an internal	representation
	      that can be used in subsequent calls  to	match_spec_run/2.  The
	      internal representation is opaque	and cannot be converted	to ex-
	      ternal term format and then back again without losing its	 prop-
	      erties  (that is,	it cannot be sent to a process on another node
	      and still	remain a valid compiled	match specification,  nor  can
	      it be stored on disk). To	check the validity of a	compiled match
	      specification, use is_compiled_ms/1.

	      If term MatchSpec	cannot be compiled (does not represent a valid
	      match specification), a badarg exception is raised.

	  Note:
	      This  function has limited use in	normal code. It	is used	by the
	      dets module to perform the dets:select() operations.

       match_spec_run(List, CompiledMatchSpec) -> list()

	      Types:

		 List =	[term()]
		 CompiledMatchSpec = comp_match_spec()

	      Executes the matching specified in a compiled  match  specifica-
	      tion on a	list of	terms. Term CompiledMatchSpec is to be the re-
	      sult of a	call to	match_spec_compile/1 and is hence the internal
	      representation of	the match specification	one wants to use.

	      The  matching  is	executed on each element in List and the func-
	      tion returns a list containing all results.  If  an  element  in
	      List  does  not match, nothing is	returned for that element. The
	      length of	the result list	is therefore equal or  less  than  the
	      length of	parameter List.

	      Example:

	      The  following two calls give the	same result (but certainly not
	      the same execution time):

	      Table = ets:new...
	      MatchSpec	= ...
	      %	The following call...
	      ets:match_spec_run(ets:tab2list(Table),
				 ets:match_spec_compile(MatchSpec)),
	      %	...gives the same result as the	more common (and more efficient)
	      ets:select(Table,	MatchSpec),

	  Note:
	      This function has	limited	use in normal code. It is used by  the
	      dets  module to perform the dets:select()	operations and by Mne-
	      sia during transactions.

       member(Tab, Key)	-> boolean()

	      Types:

		 Tab = tab()
		 Key = term()

	      Works like lookup/2, but does not	return	the  objects.  Returns
	      true if one or more elements in the table	has key	Key, otherwise
	      false.

       new(Name, Options) -> tid() | atom()

	      Types:

		 Name =	atom()
		 Options = [Option]
		 Option	=
		     Type |
		     Access |
		     named_table |
		     {keypos, Pos} |
		     {heir, Pid	:: pid(), HeirData} |
		     {heir, none} |
		     Tweaks
		 Type =	type()
		 Access	= access()
		 Tweaks	=
		     {write_concurrency, boolean()} |
		     {read_concurrency,	boolean()} |
		     compressed
		 Pos = integer() >= 1
		 HeirData = term()

	      Creates a	new table and returns a	table identifier that  can  be
	      used  in subsequent operations. The table	identifier can be sent
	      to other processes so that a table can be	shared between differ-
	      ent processes within a node.

	      Parameter	 Options  is  a	 list  of options that specifies table
	      type, access rights, key position,  and  whether	the  table  is
	      named.  Default  values are used for omitted options. This means
	      that not specifying any options ([]) is the same	as  specifying
	      [set,   protected,   {keypos,1},	 {heir,none},	{write_concur-
	      rency,false}, {read_concurrency,false}].

		set:
		  The table is a set table: one	 key,  one  object,  no	 order
		  among	objects. This is the default table type.

		ordered_set:
		  The  table  is a ordered_set table: one key, one object, or-
		  dered	in Erlang term order, which is the  order  implied  by
		  the  <  and >	operators. Tables of this type have a somewhat
		  different behavior in	some situations	than tables  of	 other
		  types.  Most	notably, the ordered_set tables	regard keys as
		  equal	when they compare equal, not  only  when  they	match.
		  This	means  that  to	 an ordered_set	table, integer() 1 and
		  float() 1.0 are regarded as equal. This also means that  the
		  key  used  to	 lookup	an element not necessarily matches the
		  key in the returned elements,	if float()'s  and  integer()'s
		  are mixed in keys of a table.

		bag:
		  The  table  is a bag table, which can	have many objects, but
		  only one instance of each object, per	key.

		duplicate_bag:
		  The table is a duplicate_bag table, which can	have many  ob-
		  jects,  including  multiple  copies  of the same object, per
		  key.

		public:
		  Any process can read or write	to the table.

		protected:
		  The owner process can	read and write	to  the	 table.	 Other
		  processes  can only read the table. This is the default set-
		  ting for the access rights.

		private:
		  Only the owner process can read or write to the table.

		named_table:
		  If this option is present, the table is registered under its
		  Name	which can then be used instead of the table identifier
		  in subsequent	operations.

		  The function will also return	the Name instead of the	 table
		  identifier.  To  get	the table identifier of	a named	table,
		  use whereis/1.

		{keypos,Pos}:
		  Specifies which element in the stored	tuples to use as  key.
		  By  default,	it  is the first element, that is, Pos=1. How-
		  ever,	this is	not always appropriate.	In particular,	we  do
		  not want the first element to	be the key if we want to store
		  Erlang records in a table.

		  Notice that any tuple	stored in the table must have at least
		  Pos number of	elements.

		{heir,Pid,HeirData} | {heir,none}:
		  Set  a  process  as heir. The	heir inherits the table	if the
		  owner	       terminates.	  Message	  {'ETS-TRANS-
		  FER',tid(),FromPid,HeirData}	is  sent to the	heir when that
		  occurs. The heir must	be a local process.  Default  heir  is
		  none,	which destroys the table when the owner	terminates.

		{write_concurrency,boolean()}:
		  Performance  tuning. Defaults	to false, in which case	an op-
		  eration that mutates (writes to) the table obtains exclusive
		  access, blocking any concurrent access of the	same table un-
		  til finished.	If set to true,	the table is optimized to con-
		  current  write  access.  Different objects of	the same table
		  can be mutated (and read) by concurrent processes.  This  is
		  achieved to some degree at the expense of memory consumption
		  and the performance  of  sequential  access  and  concurrent
		  reading.

		  Option   write_concurrency   can  be	combined  with	option
		  read_concurrency. You	typically want to combine  these  when
		  large	 concurrent  read  bursts  and	large concurrent write
		  bursts  are  common;	for  more  information,	  see	option
		  read_concurrency.

		  Notice that this option does not change any guarantees about
		  atomicity and	isolation. Functions that makes	such  promises
		  over	many  objects  (like  insert/2)	gain less (or nothing)
		  from this option.

		  Table	type ordered_set is not	affected by this option. Also,
		  the  memory  consumption inflicted by	both write_concurrency
		  and read_concurrency is a constant overhead per table.  This
		  overhead  can	be especially large when both options are com-
		  bined.

		{read_concurrency,boolean()}:
		  Performance tuning. Defaults to false. When set to true, the
		  table	is optimized for concurrent read operations. When this
		  option is enabled on a runtime system	with SMP support, read
		  operations  become  much cheaper; especially on systems with
		  multiple physical  processors.  However,  switching  between
		  read and write operations becomes more expensive.

		  You  typically  want	to  enable this	option when concurrent
		  read operations are much more	 frequent  than	 write	opera-
		  tions,  or  when  concurrent reads and writes	comes in large
		  read and write bursts	(that is, many reads  not  interrupted
		  by writes, and many writes not interrupted by	reads).

		  You  typically  do  not  want	to enable this option when the
		  common access	pattern	is a few read  operations  interleaved
		  with	a  few	write operations repeatedly. In	this case, you
		  would	get a performance degradation by enabling this option.

		  Option  read_concurrency  can	 be   combined	 with	option
		  write_concurrency.  You typically want to combine these when
		  large	concurrent read	 bursts	 and  large  concurrent	 write
		  bursts are common.

		compressed:
		  If  this  option  is	present, the table data	is stored in a
		  more compact format to consume less memory. However, it will
		  make	table  operations  slower.  Especially operations that
		  need to inspect entire objects, such as  match  and  select,
		  get much slower. The key element is not compressed.

       next(Tab, Key1) -> Key2 | '$end_of_table'

	      Types:

		 Tab = tab()
		 Key1 =	Key2 = term()

	      Returns  the next	key Key2, following key	Key1 in	table Tab. For
	      table type ordered_set, the next key in Erlang term order	is re-
	      turned. For other	table types, the next key according to the in-
	      ternal order of the table	is returned. If	no  next  key  exists,
	      '$end_of_table' is returned.

	      To find the first	key in the table, use first/1.

	      Unless a table of	type set, bag, or duplicate_bag	is fixated us-
	      ing safe_fixtable/2, a call to  next/2  will  fail  if  Key1  no
	      longer  exists  in  the  table.  For table type ordered_set, the
	      function always returns the next key after Key1 in  term	order,
	      regardless whether Key1 ever existed in the table.

       prev(Tab, Key1) -> Key2 | '$end_of_table'

	      Types:

		 Tab = tab()
		 Key1 =	Key2 = term()

	      Returns  the  previous key Key2, preceding key Key1 according to
	      Erlang term order	in table Tab of	type  ordered_set.  For	 other
	      table  types, the	function is synonymous to next/2. If no	previ-
	      ous key exists, '$end_of_table' is returned.

	      To find the last key in an ordered_set table, use	last/1.

       rename(Tab, Name) -> Name

	      Types:

		 Tab = tab()
		 Name =	atom()

	      Renames the named	table Tab to the new  name  Name.  Afterwards,
	      the old name cannot be used to access the	table. Renaming	an un-
	      named table has no effect.

       repair_continuation(Continuation, MatchSpec) -> Continuation

	      Types:

		 Continuation =	continuation()
		 MatchSpec = match_spec()

	      Restores an opaque continuation returned by select/3 or select/1
	      if  the  continuation  has  passed  through external term	format
	      (been sent between nodes or stored on disk).

	      The reason for this function is that continuation	terms  contain
	      compiled	match  specifications and therefore are	invalidated if
	      converted	to external term format. Given that the	original match
	      specification  is	kept intact, the continuation can be restored,
	      meaning it can once again	be used	in subsequent  select/1	 calls
	      even though it has been stored on	disk or	on another node.

	      Examples:

	      The following sequence of	calls fails:

	      T=ets:new(x,[]),
	      {_,C} = ets:select(T,ets:fun2ms(fun({N,_}=A)
	      when (N rem 10) =:= 0 ->
	      A
	      end),10),
	      Broken = binary_to_term(term_to_binary(C)),
	      ets:select(Broken).

	      The  following  sequence	works, as the call to repair_continua-
	      tion/2 reestablishes the (deliberately) invalidated continuation
	      Broken.

	      T=ets:new(x,[]),
	      MS = ets:fun2ms(fun({N,_}=A)
	      when (N rem 10) =:= 0 ->
	      A
	      end),
	      {_,C} = ets:select(T,MS,10),
	      Broken = binary_to_term(term_to_binary(C)),
	      ets:select(ets:repair_continuation(Broken,MS)).

	  Note:
	      This  function  is rarely	needed in application code. It is used
	      by Mnesia	to  provide  distributed  select/3  and	 select/1  se-
	      quences.	A  normal  application would either use	Mnesia or keep
	      the continuation from being converted to external	format.

	      The reason for not having	an external representation of  a  com-
	      piled  match  specification is performance. It can be subject to
	      change in	future releases,  while	 this  interface  remains  for
	      backward compatibility.

       safe_fixtable(Tab, Fix) -> true

	      Types:

		 Tab = tab()
		 Fix = boolean()

	      Fixes  a table of	type set, bag, or duplicate_bag	for  safe tra-
	      versal using first/1 & next/2, match/3 & match/1,	match_object/3
	      &	match_object/1,	or select/3 & select/1.

	      A	process	fixes a	table by calling safe_fixtable(Tab, true). The
	      table remains fixed until	the process  releases  it  by  calling
	      safe_fixtable(Tab, false), or until the process terminates.

	      If many processes	fix a table, the table remains fixed until all
	      processes	have released it (or terminated). A reference  counter
	      is kept on a per process basis, and N consecutive	fixes requires
	      N	releases to release the	table.

	      When a table is fixed, a sequence	of first/1  and	 next/2	 calls
	      are  guaranteed  to  succeed even	if keys	are removed during the
	      traversal. The keys for objects inserted	or  deleted  during  a
	      traversal	 may or	may not	be returned by next/2 depending	on the
	      ordering of keys within the table	and if the key exists  at  the
	      time next/2 is called.

	      Example:

	      clean_all_with_value(Tab,X) ->
		  safe_fixtable(Tab,true),
		  clean_all_with_value(Tab,X,ets:first(Tab)),
		  safe_fixtable(Tab,false).

	      clean_all_with_value(Tab,X,'$end_of_table') ->
		  true;
	      clean_all_with_value(Tab,X,Key) ->
		  case ets:lookup(Tab,Key) of
		      [{Key,X}]	->
			  ets:delete(Tab,Key);
		      _	->
			  true
		  end,
		  clean_all_with_value(Tab,X,ets:next(Tab,Key)).

	      Notice that deleted objects are not freed	from a fixed table un-
	      til it has been released.	If a process fixes a table  but	 never
	      releases	it,  the  memory  used by the deleted objects is never
	      freed. The performance of	operations on the table	also  degrades
	      significantly.

	      To  retrieve  information	about which processes have fixed which
	      tables, use info(Tab, safe_fixed_monotonic_time).	A system  with
	      many  processes  fixing  tables  can  need  a monitor that sends
	      alarms when tables have been fixed for too long.

	      Notice that safe_fixtable/2 is not necessary for table type  or-
	      dered_set	and for	traversals done	by a single ETS	function call,
	      like select/2.

       select(Continuation) -> {[Match], Continuation} | '$end_of_table'

	      Types:

		 Match = term()
		 Continuation =	continuation()

	      Continues	a match	started	with select/3. The next	chunk  of  the
	      size specified in	the initial select/3 call is returned together
	      with a new Continuation, which can be used in  subsequent	 calls
	      to this function.

	      When  there are no more objects in the table, '$end_of_table' is
	      returned.

       select(Tab, MatchSpec) -> [Match]

	      Types:

		 Tab = tab()
		 MatchSpec = match_spec()
		 Match = term()

	      Matches the objects in table Tab using  a	 match	specification.
	      This  is	a  more	 general  call than match/2 and	match_object/2
	      calls. In	its simplest form, the match specification is as  fol-
	      lows:

	      MatchSpec	= [MatchFunction]
	      MatchFunction = {MatchHead, [Guard], [Result]}
	      MatchHead	= "Pattern as in ets:match"
	      Guard = {"Guardtest name", ...}
	      Result = "Term construct"

	      This  means that the match specification is always a list	of one
	      or more tuples (of arity 3). The first element of	the  tuple  is
	      to  be  a	pattern	as described in	match/2. The second element of
	      the tuple	is to be a list	of 0 or	more  guard  tests  (described
	      below).  The third element of the	tuple is to be a list contain-
	      ing a description	of the value to	return.	In almost  all	normal
	      cases,  the  list	contains exactly one term that fully describes
	      the value	to return for each object.

	      The return value is  constructed	using  the  "match  variables"
	      bound  in	 MatchHead  or	using the special match	variables '$_'
	      (the whole matching object) and '$$' (all	match variables	 in  a
	      list), so	that the following match/2 expression:

	      ets:match(Tab,{'$1','$2','$3'})

	      is exactly equivalent to:

	      ets:select(Tab,[{{'$1','$2','$3'},[],['$$']}])

	      And that the following match_object/2 call:

	      ets:match_object(Tab,{'$1','$2','$1'})

	      is exactly equivalent to

	      ets:select(Tab,[{{'$1','$2','$1'},[],['$_']}])

	      Composite	 terms can be constructed in the Result	part either by
	      simply writing a list, so	that the following code:

	      ets:select(Tab,[{{'$1','$2','$3'},[],['$$']}])

	      gives the	same output as:

	      ets:select(Tab,[{{'$1','$2','$3'},[],[['$1','$2','$3']]}])

	      That is, all the bound variables in the match head as a list. If
	      tuples  are to be	constructed, one has to	write a	tuple of arity
	      1	where the single element in the	tuple is the tuple  one	 wants
	      to construct (as an ordinary tuple can be	mistaken for a Guard).

	      Therefore	the following call:

	      ets:select(Tab,[{{'$1','$2','$1'},[],['$_']}])

	      gives the	same output as:

	      ets:select(Tab,[{{'$1','$2','$1'},[],[{{'$1','$2','$3'}}]}])

	      This  syntax  is equivalent to the syntax	used in	the trace pat-
	      terns (see the dbg(3)) module in Runtime_Tools.

	      The Guards are constructed as tuples, where the first element is
	      the  test	 name  and the remaining elements are the test parame-
	      ters. To check for a specific type (say a	list) of  the  element
	      bound  to	 the  match variable '$1', one would write the test as
	      {is_list,	'$1'}. If the test fails, the object in	the table does
	      not  match  and  the  next MatchFunction (if any)	is tried. Most
	      guard tests present in Erlang can	be used, but only the new ver-
	      sions prefixed is_ are allowed (is_float,	is_atom, and so	on).

	      The  Guard  section can also contain logic and arithmetic	opera-
	      tions, which are written with the	same syntax as the guard tests
	      (prefix  notation),  so that the following guard test written in
	      Erlang:

	      is_integer(X), is_integer(Y), X +	Y < 4711

	      is expressed as follows (X replaced with '$1' and	Y with '$2'):

	      [{is_integer, '$1'}, {is_integer,	'$2'}, {'<', {'+', '$1', '$2'},	4711}]

	      For tables of type ordered_set, objects are visited in the  same
	      order  as	 in  a first/next traversal. This means	that the match
	      specification is executed	 against  objects  with	 keys  in  the
	      first/next order and the corresponding result list is in the or-
	      der of that execution.

       select(Tab, MatchSpec, Limit) ->
		 {[Match], Continuation} | '$end_of_table'

	      Types:

		 Tab = tab()
		 MatchSpec = match_spec()
		 Limit = integer() >= 1
		 Match = term()
		 Continuation =	continuation()

	      Works like select/2, but only returns a limited  (Limit)	number
	      of  matching objects. Term Continuation can then be used in sub-
	      sequent calls to select/1	to get the next	chunk of matching  ob-
	      jects. This is a space-efficient way to work on objects in a ta-
	      ble, which is still faster than traversing the table  object  by
	      object using first/1 and next/2.

	      If the table is empty, '$end_of_table' is	returned.

	      Use  safe_fixtable/2  to guarantee safe traversal	for subsequent
	      calls to select/1.

       select_count(Tab, MatchSpec) -> NumMatched

	      Types:

		 Tab = tab()
		 MatchSpec = match_spec()
		 NumMatched = integer()	>= 0

	      Matches the objects in table Tab using a match specification. If
	      the  match specification returns true for	an object, that	object
	      considered a match and is	counted. For any other result from the
	      match  specification the object is not considered	a match	and is
	      therefore	not counted.

	      This function can	be described as	a match_delete/2 function that
	      does not delete any elements, but	only counts them.

	      The function returns the number of objects matched.

       select_delete(Tab, MatchSpec) ->	NumDeleted

	      Types:

		 Tab = tab()
		 MatchSpec = match_spec()
		 NumDeleted = integer()	>= 0

	      Matches the objects in table Tab using a match specification. If
	      the match	specification returns true for an object, that	object
	      is  removed  from	the table. For any other result	from the match
	      specification the	object is retained. This  is  a	 more  general
	      call than	the match_delete/2 call.

	      The  function returns the	number of objects deleted from the ta-
	      ble.

	  Note:
	      The match	specification has to return the	atom true if  the  ob-
	      ject  is	to  be	deleted. No other return value gets the	object
	      deleted. So one cannot use  the  same  match  specification  for
	      looking up elements as for deleting them.

       select_replace(Tab, MatchSpec) -> NumReplaced

	      Types:

		 Tab = tab()
		 MatchSpec = match_spec()
		 NumReplaced = integer() >= 0

	      Matches  the  objects  in	the table Tab using a match specifica-
	      tion. For	each matched object, the existing object  is  replaced
	      with the match specification result.

	      The  match-and-replace  operation	 for each individual object is
	      guaranteed to be atomic and isolated. The	 select_replace	 table
	      traversal	 as a whole, like all other select functions, does not
	      give such	guarantees.

	      The match	specifiction must be guaranteed	to retain the  key  of
	      any matched object. If not, select_replace will fail with	badarg
	      without updating any objects.

	      For the moment, due to performance and semantic constraints, ta-
	      bles of type bag are not yet supported.

	      The function returns the total number of replaced	objects.

	      Example

	      For  all	2-tuples  with	a  list	 in  second position, add atom
	      'marker' first in	the list:

	      1> T = ets:new(x,[]), ets:insert(T, {key,	[1, 2, 3]}).
	      true
	      2> MS = ets:fun2ms(fun({K, L}) when is_list(L) ->	{K, [marker | L]} end).
	      [{{'$1','$2'},[{is_list,'$2'}],[{{'$1',[marker|'$2']}}]}]
	      3> ets:select_replace(T, MS).
	      1
	      4> ets:tab2list(T).
	      [{key,[marker,1,2,3]}]

	      A	generic	single object compare-and-swap operation:

	      [Old] = ets:lookup(T, Key),
	      New = update_object(Old),
	      Success =	(1 =:= ets:select_replace(T, [{Old, [],	[{const, New}]}])),

       select_reverse(Continuation) ->
			 {[Match], Continuation} | '$end_of_table'

	      Types:

		 Continuation =	continuation()
		 Match = term()

	      Continues	a match	started	with select_reverse/3. For  tables  of
	      type  ordered_set,  the  traversal of the	table continues	to ob-
	      jects with keys earlier in the Erlang term order.	 The  returned
	      list  also  contains objects with	keys in	reverse	order. For all
	      other table types, the behavior is exactly that of select/1.

	      Example:

	      1> T = ets:new(x,[ordered_set]).
	      2> [ ets:insert(T,{N}) ||	N <- lists:seq(1,10) ].
	      3> {R0,C0} = ets:select_reverse(T,[{'_',[],['$_']}],4).
	      4> R0.
	      [{10},{9},{8},{7}]
	      5> {R1,C1} = ets:select_reverse(C0).
	      6> R1.
	      [{6},{5},{4},{3}]
	      7> {R2,C2} = ets:select_reverse(C1).
	      8> R2.
	      [{2},{1}]
	      9> '$end_of_table' = ets:select_reverse(C2).

       select_reverse(Tab, MatchSpec) -> [Match]

	      Types:

		 Tab = tab()
		 MatchSpec = match_spec()
		 Match = term()

	      Works like select/2, but returns the list	in reverse  order  for
	      table  type  ordered_set.	 For all other table types, the	return
	      value is identical to that of select/2.

       select_reverse(Tab, MatchSpec, Limit) ->
			 {[Match], Continuation} | '$end_of_table'

	      Types:

		 Tab = tab()
		 MatchSpec = match_spec()
		 Limit = integer() >= 1
		 Match = term()
		 Continuation =	continuation()

	      Works like select/3, but for table type  ordered_set  traversing
	      is  done	starting  at  the last object in Erlang	term order and
	      moves to the first. For all other	table types, the return	 value
	      is identical to that of select/3.

	      Notice  that this	is not equivalent to reversing the result list
	      of a select/3 call, as the result	list is	not only reversed, but
	      also  contains the last Limit matching objects in	the table, not
	      the first.

       setopts(Tab, Opts) -> true

	      Types:

		 Tab = tab()
		 Opts =	Opt | [Opt]
		 Opt = {heir, pid(), HeirData} | {heir,	none}
		 HeirData = term()

	      Sets table options. The only allowed option to be	set after  the
	      table  has been created is heir. The calling process must	be the
	      table owner.

       slot(Tab, I) -> [Object]	| '$end_of_table'

	      Types:

		 Tab = tab()
		 I = integer() >= 0
		 Object	= tuple()

	      This  function  is  mostly  for  debugging  purposes,   Normally
	      first/next or last/prev are to be	used instead.

	      Returns  all objects in slot I of	table Tab. A table can be tra-
	      versed by	repeatedly calling the	function,  starting  with  the
	      first  slot  I=0 and ending when '$end_of_table' is returned. If
	      argument I is out	of  range,  the	 function  fails  with	reason
	      badarg.

	      Unless  a	 table of type set, bag, or duplicate_bag is protected
	      using safe_fixtable/2, a traversal can fail  if  concurrent  up-
	      dates  are  made	to  the	table. For table type ordered_set, the
	      function returns a list containing object	I in Erlang  term  or-
	      der.

       tab2file(Tab, Filename) -> ok | {error, Reason}

	      Types:

		 Tab = tab()
		 Filename = file:name()
		 Reason	= term()

	      Dumps table Tab to file Filename.

	      Equivalent to tab2file(Tab, Filename,[])

       tab2file(Tab, Filename, Options)	-> ok |	{error,	Reason}

	      Types:

		 Tab = tab()
		 Filename = file:name()
		 Options = [Option]
		 Option	= {extended_info, [ExtInfo]} | {sync, boolean()}
		 ExtInfo = md5sum | object_count
		 Reason	= term()

	      Dumps table Tab to file Filename.

	      When  dumping  the  table,  some	information about the table is
	      dumped to	a header at the	beginning of the dump.	This  informa-
	      tion contains data about the table type, name, protection, size,
	      version, and if it is a named  table.  It	 also  contains	 notes
	      about  what extended information is added	to the file, which can
	      be a count of the	objects	in the file or a MD5 sum of the	header
	      and records in the file.

	      The  size	field in the header might not correspond to the	number
	      of records in the	file if	the table is public  and  records  are
	      added  or	 removed  from the table during	dumping. Public	tables
	      updated during dump, and that one	wants to verify	when  reading,
	      needs  at	 least	one field of extended information for the read
	      verification process to be reliable later.

	      Option extended_info specifies what extra	information is written
	      to the table dump:

		object_count:
		  The  number  of  objects written to the file is noted	in the
		  file footer, so file truncation can be verified even if  the
		  file was updated during dump.

		md5sum:
		  The header and objects in the	file are checksummed using the
		  built-in MD5 functions. The MD5 sum of all objects is	 writ-
		  ten  in  the file footer, so that verification while reading
		  detects the slightest	bitflip	in the file data.  Using  this
		  costs	a fair amount of CPU time.

	      Whenever	option extended_info is	used, it results in a file not
	      readable by versions of ETS before that in STDLIB	1.15.1

	      If option	sync is	set to true, it	ensures	that  the  content  of
	      the  file	 is  written  to the disk before tab2file returns. De-
	      faults to	{sync, false}.

       tab2list(Tab) ->	[Object]

	      Types:

		 Tab = tab()
		 Object	= tuple()

	      Returns a	list of	all objects in table Tab.

       tabfile_info(Filename) -> {ok, TableInfo} | {error, Reason}

	      Types:

		 Filename = file:name()
		 TableInfo = [InfoItem]
		 InfoItem =
		     {name, atom()} |
		     {type, Type} |
		     {protection, Protection} |
		     {named_table, boolean()} |
		     {keypos, integer()	>= 0} |
		     {size, integer() >= 0} |
		     {extended_info, [ExtInfo]}	|
		     {version,
		      {Major ::	integer() >= 0,	Minor :: integer() >= 0}}
		 ExtInfo = md5sum | object_count
		 Type =	bag | duplicate_bag | ordered_set | set
		 Protection = private |	protected | public
		 Reason	= term()

	      Returns information about	the table dumped to file by tab2file/2
	      or tab2file/3.

	      The following items are returned:

		name:
		  The  name  of	the dumped table. If the table was a named ta-
		  ble, a table with the	same name cannot exist when the	 table
		  is  loaded  from  file  with file2tab/2. If the table	is not
		  saved	as a named table, this field has no significance  when
		  loading the table from file.

		type:
		  The  ETS type	of the dumped table (that is, set, bag,	dupli-
		  cate_bag, or ordered_set). This type is  used	 when  loading
		  the table again.

		protection:
		  The  protection  of the dumped table (that is, private, pro-
		  tected, or public). A	table loaded from the  file  gets  the
		  same protection.

		named_table:
		  true	if  the	 table	was a named table when dumped to file,
		  otherwise false. Notice that when a named  table  is	loaded
		  from	a  file, there cannot exist a table in the system with
		  the same name.

		keypos:
		  The keypos of	the table dumped to file, which	is  used  when
		  loading the table again.

		size:
		  The  number  of  objects in the table	when the table dump to
		  file started.	For a public table, this number	does not  need
		  to correspond	to the number of objects saved to the file, as
		  objects can have been	added or deleted  by  another  process
		  during table dump.

		extended_info:
		  The extended information written in the file footer to allow
		  stronger verification	during table  loading  from  file,  as
		  specified  to	 tab2file/3.  Notice  that  this function only
		  tells	which information is present, not the  values  in  the
		  file	footer.	 The value is a	list containing	one or more of
		  the atoms object_count and md5sum.

		version:
		  A tuple {Major,Minor}	containing the major and minor version
		  of  the  file	format for ETS table dumps. This version field
		  was added beginning with STDLIB  1.5.1.  Files  dumped  with
		  older	versions return	{0,0} in this field.

	      An error is returned if the file is inaccessible,	badly damaged,
	      or not produced with tab2file/2 or tab2file/3.

       table(Tab) -> QueryHandle

       table(Tab, Options) -> QueryHandle

	      Types:

		 Tab = tab()
		 QueryHandle = qlc:query_handle()
		 Options = [Option] | Option
		 Option	= {n_objects, NObjects}	| {traverse, TraverseMethod}
		 NObjects = default | integer()	>= 1
		 TraverseMethod	=
		     first_next	|
		     last_prev |
		     select |
		     {select, MatchSpec	:: match_spec()}

	      Returns a	Query List Comprehension (QLC) query handle.  The  qlc
	      module provides a	query language aimed mainly at Mnesia, but ETS
	      tables, Dets tables, and lists are also  recognized  by  QLC  as
	      sources  of data.	Calling	table/1,2 is the means to make the ETS
	      table Tab	usable to QLC.

	      When there are only simple restrictions on the key position, QLC
	      uses  lookup/2  to  look up the keys. When that is not possible,
	      the whole	table is traversed.  Option  traverse  determines  how
	      this is done:

		first_next:
		  The  table is	traversed one key at a time by calling first/1
		  and next/2.

		last_prev:
		  The table is traversed one key at a time by  calling	last/1
		  and prev/2.

		select:
		  The table is traversed by calling select/3 and select/1. Op-
		  tion n_objects determines the	 number	 of  objects  returned
		  (the	third  argument	of select/3); the default is to	return
		  100 objects at a time. The match specification  (the	second
		  argument  of	select/3)  is assembled	by QLC:	simple filters
		  are translated into equivalent  match	 specifications	 while
		  more	complicated filters must be applied to all objects re-
		  turned by select/3 given a match specification that  matches
		  all objects.

		{select, MatchSpec}:
		  As  for  select,  the	table is traversed by calling select/3
		  and select/1.	The difference is that the match specification
		  is explicitly	specified. This	is how to state	match specifi-
		  cations that cannot easily be	expressed  within  the	syntax
		  provided by QLC.

	      Examples:

	      An explicit match	specification is here used to traverse the ta-
	      ble:

	      9> true =	ets:insert(Tab = ets:new(t, []), [{1,a},{2,b},{3,c},{4,d}]),
	      MS = ets:fun2ms(fun({X,Y}) when (X > 1) or (X < 5) -> {Y}	end),
	      QH1 = ets:table(Tab, [{traverse, {select,	MS}}]).

	      An example with an implicit match	specification:

	      10> QH2 =	qlc:q([{Y} || {X,Y} <- ets:table(Tab), (X > 1) or (X < 5)]).

	      The latter example is equivalent to the  former,	which  can  be
	      verified using function qlc:info/1:

	      11> qlc:info(QH1)	=:= qlc:info(QH2).
	      true

	      qlc:info/1 returns information about a query handle, and in this
	      case identical information is returned for the  two  query  han-
	      dles.

       take(Tab, Key) -> [Object]

	      Types:

		 Tab = tab()
		 Key = term()
		 Object	= tuple()

	      Returns  and removes a list of all objects with key Key in table
	      Tab.

	      The specified Key	is used	to identify the	object by either  com-
	      paring  equal  the  key of an object in an ordered_set table, or
	      matching in other	types of tables	(for details  on  the  differ-
	      ence, see	lookup/2 and new/2).

       test_ms(Tuple, MatchSpec) -> {ok, Result} | {error, Errors}

	      Types:

		 Tuple = tuple()
		 MatchSpec = match_spec()
		 Result	= term()
		 Errors	= [{warning | error, string()}]

	      This function is a utility to test a match specification used in
	      calls to select/2. The function both tests MatchSpec  for	 "syn-
	      tactic" correctness and runs the match specification against ob-
	      ject Tuple.

	      If the match specification is syntactically correct,  the	 func-
	      tion either returns {ok,Result}, where Result is what would have
	      been the result in a real	select/2 call, or false	if  the	 match
	      specification does not match object Tuple.

	      If  the  match  specification contains errors, tuple {error, Er-
	      rors} is returned, where Errors is a list	 of  natural  language
	      descriptions of what was wrong with the match specification.

	      This  is a useful	debugging and test tool, especially when writ-
	      ing complicated select/2 calls.

	      See also:	 erlang:match_spec_test/3.

       to_dets(Tab, DetsTab) ->	DetsTab

	      Types:

		 Tab = tab()
		 DetsTab = dets:tab_name()

	      Fills an already created/opened Dets table with the  objects  in
	      the  already  opened ETS table named Tab.	The Dets table is emp-
	      tied before the objects are inserted.

       update_counter(Tab, Key,	UpdateOp) -> Result

       update_counter(Tab, Key,	UpdateOp, Default) -> Result

       update_counter(Tab, Key,	X3 :: [UpdateOp]) -> [Result]

       update_counter(Tab, Key,	X3 :: [UpdateOp], Default) -> [Result]

       update_counter(Tab, Key,	Incr) -> Result

       update_counter(Tab, Key,	Incr, Default) -> Result

	      Types:

		 Tab = tab()
		 Key = term()
		 UpdateOp = {Pos, Incr}	| {Pos,	Incr, Threshold, SetValue}
		 Pos = Incr = Threshold	= SetValue = Result = integer()
		 Default = tuple()

	      This function provides an	efficient way to update	 one  or  more
	      counters,	 without  the  trouble of having to look up an object,
	      update the object	by incrementing	an element, and	insert the re-
	      sulting object into the table again. The operation is guaranteed
	      to be atomic and isolated.

	      This function destructively update the object with  key  Key  in
	      table Tab	by adding Incr to the element at position Pos. The new
	      counter value is returned. If no position	is specified, the ele-
	      ment directly following key (_keypos_+1) is updated.

	      If  a Threshold is specified, the	counter	is reset to value Set-
	      Value if the following conditions	occur:

		* Incr is not negative (_= 0) and the result would be  greater
		  than (_) Threshold.

		* Incr is negative (_ 0) and the result	would be less than (_)
		  Threshold.

	      A	list of	UpdateOp can be	supplied to do many update  operations
	      within  the  object. The operations are carried out in the order
	      specified	in the list. If	the same counter position occurs  more
	      than once	in the list, the corresponding counter is thus updated
	      many times, each time based on the previous result.  The	return
	      value is a list of the new counter values	from each update oper-
	      ation in the same	order as in the	operation list.	 If  an	 empty
	      list  is	specified, nothing is updated and an empty list	is re-
	      turned. If the function fails, no	updates	are done.

	      The specified Key	is used	 to  identify  the  object  by	either
	      matching	the  key of an object in a set table, or compare equal
	      to the key of an object in an ordered_set	table (for details  on
	      the difference, see lookup/2 and new/2).

	      If  a default object Default is specified, it is used as the ob-
	      ject to be updated if the	key is missing	from  the  table.  The
	      value  in	place of the key is ignored and	replaced by the	proper
	      key value. The return value is as	if the default object had  not
	      been used, that is, a single updated element or a	list of	them.

	      The  function  fails  with reason	badarg in the following	situa-
	      tions:

		* The table type is not	set or ordered_set.

		* No object with the correct key exists	and no default	object
		  was supplied.

		* The object has the wrong arity.

		* The default object arity is smaller than _keypos_.

		* Any  field from the default object that is updated is	not an
		  integer.

		* The element to update	is not an integer.

		* The element to update	is also	the key.

		* Any of Pos, Incr, Threshold, or SetValue is not an integer.

       update_element(Tab, Key,	ElementSpec :: {Pos, Value}) ->	boolean()

       update_element(Tab, Key,	ElementSpec :: [{Pos, Value}]) ->
			 boolean()

	      Types:

		 Tab = tab()
		 Key = term()
		 Value = term()
		 Pos = integer() >= 1

	      This function provides an	efficient way to update	 one  or  more
	      elements within an object, without the trouble of	having to look
	      up, update, and write back the entire object.

	      This function destructively updates the object with key  Key  in
	      table Tab. The element at	position Pos is	given the value	Value.

	      A	 list  of  {Pos,Value} can be supplied to update many elements
	      within the same object. If the same position  occurs  more  than
	      once  in the list, the last value	in the list is written.	If the
	      list is empty or the function fails, no updates  are  done.  The
	      function	is  also  atomic in the	sense that other processes can
	      never see	any intermediate results.

	      Returns true if an object	 with  key  Key	 is  found,  otherwise
	      false.

	      The  specified  Key  is  used  to	 identify the object by	either
	      matching the key of an object in a set table, or	compare	 equal
	      to  the key of an	object in an ordered_set table (for details on
	      the difference, see lookup/2 and new/2).

	      The function fails with reason badarg in	the  following	situa-
	      tions:

		* The table type is not	set or ordered_set.

		* Pos <	1.

		* Pos >	object arity.

		* The element to update	is also	the key.

       whereis(TableName) -> tid() | undefined

	      Types:

		 TableName = atom()

	      This function returns the	tid() of the named table identified by
	      TableName, or undefined if no such table exists. The  tid()  can
	      be  used	in place of the	table name in all operations, which is
	      slightly faster since the	name does not have to be  resolved  on
	      each call.

	      If  the  table is	deleted, the tid() will	be invalid even	if an-
	      other named table	is created with	the same name.

Ericsson AB			  stdlib 3.8				ets(3)

NAME | DESCRIPTION | FAILURE | CONCURRENCY | TABLE TRAVERSAL | MATCH SPECIFICATIONS | DATA TYPES | EXPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ets&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help